Implementing the Tweet\Type class

As said in the introduction, the Type class of a FieldType must implement eZ\Publish\SPI\FieldType\FieldType (later referred to as "FieldType interface").

All native FieldTypes also extend the eZ\Publish\Core\FieldType\FieldType abstract class, that implements this interface, and provides implementation facilities through a set of abstract methods of its own. In this case, Type classes implement a mix of methods from the FieldType interface and from the abstract FieldType .

Let’s go over those methods and their implementation.

Identification method: getFieldTypeIdentifier()

It must return the string that uniquely identifies this FieldType (DataTypeString in eZ Publish 4). We will use "eztweet":

Value handling methods: createValueFromInput() and checkValueStructure()

Both methods are used by the abstract FieldType implementation of acceptValue(). This FieldType interface method checks and transforms various input values into the type's own Value class: eZ\FieldType\Tweet\Value. This method must:

• either return the Value object it was able to create out of the input value,
• or return this value untouched. The API will detect this, and inform that the input value was not accepted.

The only acceptable value for our type is the URL of a tweet (we could of course imagine more possibilities). This should do:

Use this method to provide convenient ways to set an attribute’s value using the API. This can be anything from primitives to complex business objects.

Next, we will implement checkValueStructure(). It is called by the abstract FieldType to ensure that the Value fed to the Type is acceptable. In our case, we want to be sure that Tweet\Value::$url is a string:

Yes, we execute the same check than in createValueFromInput(). But both methods aren't responsible for the same thing. The first will, if given something else than a Value of its type, try to convert it to one. checkValueStructure() will always be used, even if the FieldType is directly fed a Value object, and not a string.

Value initialization: getEmptyValue()

This method provides what is considered as an empty value of this type, depending on our business requirements. No extra initialization is required in our case.

If you run the unit tests at this point, you should get about five failures, all of them on the fromHash() or toHash() methods.

Validation methods: validateValidatorConfiguration() and validate()

The Type class is also responsible for validating input data (to a Field), as well as configuration input data (to a FieldDefinition). In this tutorial, we will run two validation operations on input data:

• validate submitted urls, ensuring they actually reference a twitter status;

• limit input to a known list of authors, as an optional validation step.

validateValidatorConfiguration() will be called when an instance of the FieldType is added to a ContentType, to ensure that the validator configuration is valid. For a TextLine (length validation), it means checking that both min length and max length are positive integers, and that min is lower than max.

When an instance of the type is added to a content type, validateValidatorConfiguration() receives the configuration for the validators used by the Type as an array. It must return an array of error messages if errors are found in the configuration, and an empty array if no errors were found.

 For TextLine, the provided array looks like this:

The structure of this array is totally free, and up to each type implementation. We will in this tutorial mimic what is done in native FieldTypes:

Each level one key is the name of a validator, as acknowledged by the Type. That key contains a set of parameter name / parameter value rows. We must check that:

• all the validators in this array are known to the type

• arguments for those validators are valid and have sane values

We do not need to include mandatory validators if they don’t have options. Here is an example of what our Type expects as validation configuration:

The configuration says that tweets must be either by johndoe or by janedoe. If we had not provided TweetAuthorValidator at all, it would have been ignored.

We will iterate over the items in $validatorConfiguration, and:

• add errors for those we don’t know about;

• check that provided arguments are known and valid:

• TweetAuthorValidator accepts a non-empty array of valid twitter usernames

validate() is the method that runs the actual validation on data, when a content item is created with a field of this type:

First, we validate the url with a regular expression. If it doesn’t match, we add an instance of ValidationError to the return array. Note that the tested value isn’t directly embedded in the message but passed as an argument. This ensures that the variable is properly encoded in order to prevent attacks, and allows for singular/plural phrases using the 2nd parameter.

Then, if our FieldType instance’s configuration contains a TweetAuthorValidator key, we check that the username in the status url matches one of the valid authors.

Metadata handling methods: getName() and getSortInfo().

FieldTypes require two methods related to Field metadata:

• getName() is used to generate a name out of a field value, either to name a content item (naming pattern in legacy) or to generate a part for an URL Alias.

• getSortInfo() is used by the persistence layer to obtain the value it can use to sort & filter on a field of this type

Obviously, a tweet’s full URL isn’t really suitable as a name. Let’s use a subset of it: <username>-<tweetId> should be reasonable enough, and suitable for both sorting and naming.

We can assume that this method will not be called if the field is empty, and will assume that the URL is a valid twitter URL:

In getName(), we run a regular expression replace on the URL to extract the part we’re interested in.

This name is a perfect match for getSortInfo(), as it allows us to sort on the tweet’s author and on the tweet’s ID.

FieldType serialization methods: fromHash() and toHash()

Both methods, defined in the FieldType interface, are core to the REST API. They are used to export values to serializable hashes.

In our case, it is quite easy:

• toHash() will build a hash with every property from Tweet\Value;

• fromHash() will instantiate a Tweet\Value with the hash it receives. 

Persistence methods: fromPersistenceValue and toPersistenceValue

Storage of fieldType data is done through the persistence layer (SPI).

FieldTypes use their own Value objects to expose their contents using their own domain language. However, to store those objects, the Type needs to map this custom object to a structure understood by the persistence layer: PersistenceValue. This simple value object has three properties:

• data standard data, stored using the storage engine's native features
• externalData external data, stored using a custom storage handler
• sortKey sort value used for sorting

The role of those mapping methods is to convert a Value of the FieldType into a PersistenceValue, and the other way around.

We will follow a simple implementation here: the Tweet\Value object will be serialized as an array to the code property using fromHash() and toHash():

Fetching data from the twitter API