Creating Datatypes in eZ Publish 4

Our custom datatype extends the functionality of eZ Publish and therefore needs to be included in an extension. Refer to Felix Woldt's article An Introduction to Developing eZ Publish Extensions to learn more about different types of extensions. Here we will outline the necessary files and configuration for the extension.

At Young Media Concepts we have one extension called “ymcdatatype” that contains all of our general-purpose datatypes. Each datatype can also be created in a separate extension or combined with a related module in an extension.

In any case, the extension containing your datatype needs to be activated in a site.ini.append file, either in settings/override, settings/siteaccess/your_siteaccess or in the settings directory of an already activated extension, like this:

[ExtensionSettings<span>]
ActiveExtensions<span>[]=ymcdatatype

(Note that the setting name is “ActiveAccessExtensions[]” if you are activating the datatype for a specific siteaccess.)

Based on the settings above, eZ Publish knows that there is an extension called “ymcdatatype”, but it does not know about the new datatype yet. To point eZ Publish to the datatype contained in the extension, we place the settings below in a content.ini.append file, which is best placed in the settings directory of the datatype extension:

[DataTypeSettings<span>]
ExtensionDirectories[]</span>=ymcdatatype
AvailableDataTypes[]=ymcdatetime

The datatype also requires some templates (to be described next), so the extension also needs to be specified as a design extension in design.ini.append:

[ExtensionSettings<span>]
DesignExtensions<span>[]=ymcdatatype

Template files

Templates are required for class and object attributes of our datatype. In both cases, we need both view and edit templates, making a total of four required templates:

• design/standard/templates/class/datatype/edit/ymcdatetime.tpl
• design/standard/templates/class/datatype/view/ymcdatetime.tpl
• design/standard/templates/content/datatype/edit/ymcdatetime.tpl
• design/standard/templates/content/datatype/view/ymcdatetime.tpl

We will explore the code in these templates a bit more later.

PHP files

Required files

The main code of the datatype consists of two PHP classes in the following files:

• datatypes/ymcdatetime/ymcdatetime.php: ymcDatatypeDatetime
• datatypes/ymcdatetime/ymcdatetimetype.php: ymcDatatypeDatetimeType

The first file contains the actual content holder. Some simple datatypes like string or number types do not have an extra class to represent their content, but simply return an array or a primitive PHP type as representation of their content. If the content of your datatype has a complex structure or methods associated to the content, you should represent the content by a PHP class of its own.

In our case, the ymcDatatypeDatetime class contains shortcut methods to retrieve the elements of a DateTime object, such as the day, month, second or timezone, as well as methods for serializing and unserializing the information. The constructor of the class also checks the given input for validity. This way we could shorten the ymcDatatypeDatetimeType class and let the content container decide whether or not to handle the user input.

The name and location of the file ymcdatetime.php is not strictly forced, but it is general convention in eZ Publish and many extensions to name it this way. You thus have the main code blocks of your datatype in one place and everybody knows where to search for it.

The second file handles the connection between eZ Publish and our new datatype. The name and path of the second file is important because eZ Publish tries to load a file with this exact name when you register a datatype with the identifier “ymcdatetime”.

We also need to handle the HTTP input forms. This is done with two classes, defined in datatypes/ymcdatetime/classform.php and datatypes/ymcdatetime/objectform.php, which both extend ymcDatatypeForm from interfaces/form.php. Since this datatype has been developed for eZ Publish 4, we can make use of the UserInput component from eZ Components to handle form input. This is explained in detail later.

Useful additions

PHP 5 and therefore eZ Publish 4 have two notable features to write more stable and robust code. The first one is the autoloading functionality, which frees you from all those “requires” and “includes”.

The second feature is the introduction of exceptions. In PHP 4, the only way to report errors from a function is for it to return FALSE or some other value, by convention indicating an error. However, this is a sub-optimal solution – how do we know which problem actually occurred and what if FALSE should also be a valid return value?

In every extension, we have an exceptions directory containing an exception class for, hopefully, each type of error that can occur. One such error in our datatype is invalid user input, which is indicated by a ymcDatatypeInvalidParamsException exception, defined in invalid_params.php.

Input validation in PHP 5 should be done using the filter extension. This extension comes with many configurable filters to either block invalid data or sanitize it with certain rules. If you need to add extra filters, you can provide a callback function to the filter extension.

In our case, we need special filters for integer numbers with leading zeros. If somebody enters the month as “09” instead of “9”, it should still be valid for September, even if a leading zero in PHP usually indicates an octal number and “09” is not a valid octal number.

We put our filter callbacks in classes inside the filter_callbacks directory. For this datatype, we only need the ymcDatatypeFilterIntLeadingZero class, which is defined in filter_callbacks/int_leading_zero.php.