Introduction

This document explains how to register a custom FieldType in eZ P= ublish 5. It will not contain the development part as it is already = covered in t= he API section.

Please be sure you first have read the basic documentation on how to develop a custo= m FieldType.

Service containe= r configuration

To be able to declare a FieldType, you need to have registered a bundle in your application kerne= l.

This bundle needs to expose some configuration for the service container= somehow (read related Symfony documentation)

Basic configuration

This part relates to the=20 base FieldType class that interacts w= ith the Publish API.

Let's take a basic example from ezstring configuration.

=20

parameters:
    ezpublish.fieldType.ezstring.class: eZ\Publish\Core\FieldType\TextLine\=
Type
 
services:
    ezpublish.fieldType.ezstring:
        class: %ezpublish.fieldType.ezstring.class%
        parent: ezpublish.fieldType
        tags:
            - {name: ezpublish.fieldType, alias: ezstring}

=20

So far, this is a regular service configuration but 2 parts worth partic= ular attention.

parent

As described in the Symfony Dependency Injection Compone= nt documentation, the parent config key indicates that you= want your service to inherit from the parent's dependencies, including con= structor arguments and method calls. This is actually a helper avoiding rep= etition in your field type configuration and keeping consistency between al= l field types.

tags

Tagging your field type service with ezpublish.fieldType is mandatory to be recognized= by the API loader as a regular field type, the alias key bein= g simply the fieldTypeIdentifier (formerly called datatype str= ing)

Basic field types configuration is located in EzPublishCoreBundle/Resources/config/fieldtypes.yml<= /a>.

Legacy Storage Engine

Converter

As stated in Field Type AP= I & best practices, a conversion of Field Type values is needed in = order to properly store the data into the old database schema (aka= Legacy Storage).

Those converters also need to be correctly exposed as services.

Field Type converter for ezstring

=20

parameters:
    ezpublish.fieldType.ezstring.converter.class: eZ\Publish\Core\Persisten=
ce\Legacy\Content\FieldValue\Converter\TextLine
 
services:
    ezpublish.fieldType.ezstring.converter:
        class: %ezpublish.fieldType.ezstring.converter.class%
        tags:
            - {name: ezpublish.storageEngine.legacy.converter, alias: ezstr=
ing, lazy: true, callback: '::create'}

=20

Here again we need to tag our converter service, with ezpublish.storageEngine.legacy.converter tag this time.

As for the tag attributes:

Attribute name Usage

alias Represents the fieldTypeIdenti= fier (just like for the FieldType service)

Attribute name	Usage
`alias`	Represents the fieldTypeIdenti= fier (just like for the FieldType service)
`lazy`	Boolean indicating if the conve= rter should be lazy loaded or not. Performance wise, it is recommende= d to set it to true unless you have very specific reasons.=
`callback`	If `lazy` is set to = true, it represents the callback that will be called to build the converter= . Any valid callback can be used. = Note that if the callback is defined in the converter class, the class name= can be omitted. This way, in the example above, the full callback will= be resolved to `eZ\Publish\Core\Persistence\Legacy\Content\FieldValue= \Converter\TextLine::create`

lazy

Boolean indicating if the conve= rter should be lazy loaded or not.

Performance wise, it is recommende= d to set it to true unless you have very specific reasons.=

callback

If lazy is set to = true, it represents the callback that will be called to build the converter= . Any valid callback can be used.

= Note that if the callback is defined in the converter class, the class name= can be omitted.
This way, in the example above, the full callback will= be resolved to eZ\Publish\Core\Persistence\Legacy\Content\FieldValue= \Converter\TextLine::create

The converter configuration for basic field types are located in=20 EzPublishCoreBundle/Resources/config/storage_en= gines.yml.

External storage

A FieldType has the ability to stor= e its value (or part of it) in external data sources. This is made poss= ible through the eZ\Publish\SPI\FieldType\FieldStorage interface. Thus, if one wants to use this functionalit= y, he needs to define a service implementing this interface and tagged as&n= bsp;ezpublish.fieldType.externalStorageHandler to be recognized by the Repository.


Here is an example for ezurl field type:


External storage handler for ezurl

=20
parameters:
    ezpublish.fieldType.ezurl.externalStorage.class: eZ\Publish\Core\FieldT=
ype\Url\UrlStorage
 
services:
    ezpublish.fieldType.ezurl.externalStorage:
        class: %ezpublish.fieldType.ezurl.externalStorage.class%
        tags:
            - {name: ezpublish.fieldType.externalStorageHandler, alias: ezu=
rl}=20


The configuration is straight forward. Nothing specific except the ezpublish.fieldType.externalStorageHandler ta=
g, the alias attribute still begin the fieldTypeIdentifier=
.



External storage configuration for basic field types is located in&nb=
sp;
EzPublishCoreBundle/Resources/config/fieldtypes.yml
.


Gateway based storage
As stated in the FieldType best pra=
ctices, in order to be storage agnostic and external storage handler sh=
ould use a storage gateway. This can be done by implementing anoth=
er service implementing eZ\Publish\Core\FieldType\StorageG=
ateway and being tagged as ezpublish.fieldType.ex=
ternalStorageHandler.gateway.


Storage gateway for ezurl

=20
parameters:
    ezpublish.fieldType.ezurl.storage_gateway.class: eZ\Publish\Core\FieldT=
ype\Url\UrlStorage\Gateway\LegacyStorage
 
services:
    ezpublish.fieldType.ezurl.storage_gateway:
        class: %ezpublish.fieldType.ezurl.storage_gateway.class%
        tags:
            - {name: ezpublish.fieldType.externalStorageHandler.gateway, al=
ias: ezurl, identifier: LegacyStorage}=20






Attribute name
Usage


alias
Represents the fi=
eldTypeIdentifier (just like for the FieldType service)


identifier
Identifier for the gateway.
Mus=
t be unique per storage engine. LegacyStorage is the convention na=
me for Legacy Storage Engine.







For this to work properly, your storage handler must inherit from&=
nbsp;eZ\Publish\Core\FieldType\GatewayBasedStorage.

Also note that there can be several gateways per field type (one p=
er storage engine basically).
The gateway configuration for basic field types are located =
in EzPublishCoreBundle/Resources/config/=
storage_engines.yml.

Attribute name	Usage
`alias`	Represents the fi= eldTypeIdentifier (just like for the FieldType service)
`identifier`	Identifier for the gateway. Mus= t be unique per storage engine. LegacyStorage is the convention na= me for Legacy Storage Engine.