Field Types reference¶
A Field Type is the underlying building block of the content model. It consists of two entities: Field value and Field definition. Field value is determined by values entered into the Content Field. Field definition is provided by the Content Type, and holds any user defined rules used by Field Type to determine how a Field Value is validated, stored, retrieved, formatted and so on.
eZ Platform comes with a collection of Field Types that can be used to build powerful and complex content structures. In addition, it is possible to extend the system by creating custom types for special needs.
Tip
For general Field Type documentation, see Field Type API. For the documentation on how to implement a custom Field Type, see the Creating a Tweet Field Type tutorial.
Custom Field Types have to be programmed in PHP. However, the built-in Field Types are usually sufficient enough for typical scenarios. The following table gives an overview of the supported Field Types that come with eZ Platform.
Available Field Types¶
Field Type | Description | Searchable in Legacy Storage engine | Searchable with Solr |
---|---|---|---|
Author | Stores a list of authors, each consisting of author name and author email. | No | Yes |
BinaryFile | Stores a file. | Yes | Yes |
Checkbox | Stores a boolean value. | Yes | Yes |
Country | Stores country names as a string. | Yes1 | Yes |
DateAndTime | Stores a full date including time information. | Yes | Yes |
Date | Stores date information. | Yes | Yes |
EmailAddress | Validates and stores an email address. | Yes | Yes |
Float | Validates and stores a floating-point number. | No | Yes |
Image | Validates and stores an image. | No | Yes |
Integer | Validates and stores an integer value. | Yes | Yes |
ISBN | Handles International Standard Book Number (ISBN) in 10-digit or 13-digit format. | Yes | Yes |
Keyword | Stores keywords. | Yes1 | Yes |
Landing Page | Stores a Landing Page with a layout consisting of multiple zones. | N/A | N/A |
MapLocation | Stores map coordinates. | Yes, with MapLocationDistance criterion | Yes |
Media | Validates and stores a media file. | No | Yes |
Null | Used as fallback for missing Field Types and for testing purposes. | N/A | N/A |
Rating | Deprecated | N/A | N/A |
Relation | Validates and stores a relation to a Content item. | Yes, with both Field and FieldRelation criterions | Yes |
RelationList | Validates and stores a list of relations to Content items. | Yes, with FieldRelation criterion | Yes |
RichText | Validates and stores structured rich text in DocBook xml format, and exposes it in several formats. | Yes1 | Yes |
Selection | Validates and stores a single selection or multiple choices from a list of options. | Yes1 | Yes |
TextBlock | Validates and stores a larger block of text. | Yes1 | Yes |
TextLine | Validates and stores a single line of text. | Yes | Yes |
Time | Stores time information. | Yes | Yes |
Url | Stores a URL / address. | No | Yes |
User | Validates and stores information about a user. | No | No |
[1] Note on Legacy Search Engine
Legacy Search/Storage Engine index is limited to 255 characters in database design, so formatted and unformatted text blocks will only index the first part. In case of multiple selection Field Types like Keyword, Selection, Country, etc., only the first choices are indexed. They are indexed only as a text blob separated by string separator. Proper indexing of these Field Types is done with Solr Search Bundle.
Other Field Types¶
FieldType | Description | Searchable | Editing support in Platform UI | Planned to be included in the future |
---|---|---|---|---|
XmlText | Validates and stores multiple lines of formatted text using XML format. | Yes | Partial (Raw XML editing) | No (has been superseded by RichText)The XmlText Field Type is not enabled by default in eZ Platform. |
Field Types provided by Community¶
FieldType | Description | Searchable | Editing support in Platform UI | Planned to be included in the future |
---|---|---|---|---|
Tags | Tags Field and full-fledged taxonomy management | Yes | Yes, since Netgen Tags v3.0.0 | No (but can be previewed in Studio Demo) |
Price | Price Field for use in product catalogs | Yes | No | Yes |
Matrix | Matrix Field for matrix data | Yes | No | Yes |
Generate new Field Type¶
You can learn how to create a custom Field Type by following the Creating a Tweet Field Type tutorial
You can also make use of the Field Type Generator Bundle from our partner Smile. It helps you get started by creating a skeleton for a Field Type, including templates for the editorial interface.
Author Field Type¶
This Field Type allows the storage and retrieval of one or more authors. For each author, it can handle a name and an email address. It is typically used to store information about additional authors who have written/created different parts of a Content item.
Name | Internal name | Expected input | Output |
---|---|---|---|
Author |
ezauthor |
mixed | string |
PHP API Field Type¶
Value Object¶
Properties¶
Attribute | Type | Description | Example |
---|---|---|---|
authors |
\eZ\Publish\Core\FieldType\Author\Author[] |
List of authors. | See below |
Example:
1 2 3 4 5 6 7 8 9 10 11 12 | $authorList = Author\Value([ new Author\Author([ 'id' => 1, 'name' => 'Boba Fett', 'email' => 'boba.fett@example.com' ]), new Author\Author([ 'id' => 2, 'name' => 'Darth Vader', 'email' => 'darth.vader@example.com' ]), ]); |
Hash format¶
The hash format mostly matches the value object. It has the following key authors
.
Example
1 2 3 4 5 6 7 8 9 10 11 12 | [ [ 'id' => 1, 'name' => 'Boba Fett', 'email' => 'boba.fett@example.com' ], [ 'id' => 2, 'name' => 'Darth Vader', 'email' => 'darth.vader@example.com' ] ] |
String representation¶
The string will contain all the authors with their names and emails.
Example: John Doe john@doe.com
BinaryFile Field Type¶
This Field Type represents and handles a single binary file. It also counts the number of times the file has been downloaded from the content/download
module.
It is capable of handling virtually any file type and is typically used for storing legacy document types such as PDF files, Word documents, spreadsheets, etc. The maximum allowed file size is determined by the "Max file size" class attribute edit parameter and the upload_max_filesize
directive in the main PHP configuration file (php.ini
).
Name | Internal name | Expected input | Output |
---|---|---|---|
BinaryFile |
ezbinaryfile |
mixed | mixed |
PHP API Field Type¶
Value Object¶
Properties¶
Note that both BinaryFile
and Media
Value and Type inherit from the BinaryBase
abstract Field Type, and share common properties.
eZ\Publish\Core\FieldType\BinaryFile\Value
offers the following properties:
Attribute | Type | Description | Example |
---|---|---|---|
id |
string | Binary file identifier. This ID depends on the IO Handler that is being used. With the native, default handlers (FileSystem and Legacy), the ID is the file path, relative to the binary file storage root dir (var/<vardir>/storage/original by default). |
application/63cd472dd7.pdf |
fileName |
string | The human-readable file name, as exposed to the outside. Used when sending the file for download in order to name the file. | 20130116_whitepaper.pdf |
fileSize |
int | File size, in bytes. | 1077923 |
mimeType |
string | The file's MIME type. | application/pdf |
uri |
string | The binary file's content/download URI. If the URI doesn't include a host or protocol, it applies to the request domain. |
/content/download/210/2707 |
downloadCount |
integer | Number of times the file was downloaded | 0 |
path |
string | deprecated | N/A |
Hash format¶
The hash format mostly matches the value object. It has the following keys:
id
path
(for backwards compatibility)fileName
fileSize
mimeType
uri
downloadCount
Example:
1 2 3 4 5 6 7 8 | [ 'id' => 'some/file/here', 'fileName' => 'sindelfingen.jpg', 'fileSize' => 2342, 'downloadCount' => 0, 'mimeType' => 'image/jpeg', 'uri' => 'http://some/file/here', ] |
REST API specifics¶
Used in the REST API, a BinaryFile Field will mostly serialize the hash described above. However there are a couple specifics worth mentioning.
Reading content: url
property¶
When reading the contents of a Field of this type, an extra key is added: url
. This key gives you the absolute file URL, protocol and host included.
Example: http://example.com/var/ezdemo_site/storage/original/application/63cd472dd7819da7b75e8e2fee507c68.pdf
Creating content: data property¶
When creating BinaryFile content with the REST API, it is possible to provide data as a base64 encoded string, using the data
fieldValue key:
1 2 3 4 5 6 7 8 9 10 11 | <field> <fieldDefinitionIdentifier>file</fieldDefinitionIdentifier> <languageCode>eng-GB</languageCode> <fieldValue> <value key="fileName">My file.pdf</value> <value key="fileSize">17589</value> <value key="data"><![CDATA[/9j/4AAQSkZJRgABAQEAZABkAAD/2wBDAAIBAQIBAQICAgICAgICAwUDAwMDAwYEBAMFBwYHBwcG ... ...]]></value> </fieldValue> </field> |
Checkbox Field Type¶
The Checkbox Field Type stores the current status for a checkbox input, checked or unchecked, by storing a boolean value.
Name | Internal name | Expected input type |
---|---|---|
Checkbox |
ezboolean |
boolean |
PHP API Field Type¶
Value object¶
Properties¶
The Value class of this Field Type contains the following properties:
Property | Type | Default value | Description |
---|---|---|---|
$bool |
boolean |
false |
This property is used for the checkbox status, represented by a boolean value. |
1 2 3 4 5 6 7 8 9 10 11 | //Value object content examples use eZ\Publish\Core\FieldType\Checkbox\Type; // Instantiates a checkbox value with a default state (false) $checkboxValue = new Checkbox\Value(); // Checked $value->bool = true; // Unchecked $value->bool = false; |
Constructor¶
The Checkbox\Value
constructor accepts a boolean value:
1 2 3 4 5 | // Constructor example use eZ\Publish\Core\FieldType\Checkbox\Type; // Instantiates a checkbox value with a checked state $checkboxValue = new Checkbox\Value( true ); |
String representation¶
As this Field Type is not a string but a boolean, it will return "1" (true) or "0" (false) in cases where it is cast to string.
Country Field Type¶
This Field Type represents one or multiple countries.
Name | Internal name | Expected input |
---|---|---|
Country |
ezcountry |
array |
PHP API Field Type¶
Input expectations¶
Example array:
1 2 3 4 5 6 7 8 | [ "JP" => [ "Name" => "Japan", "Alpha2" => "JP", "Alpha3" => "JPN", "IDC" => 81 ] ]; |
When you set an array directly on a Content field you don't need to provide all this information, the Field Type will assume it is a hash and in this case will accept a simplified structure described below under Hash format.
Validation¶
This Field Type validates whether multiple countries are allowed by the Field definition, and whether the Alpha2 is valid according to the countries configured in eZ Platform.
Settings¶
The Field definition of this Field Type can be configured with one option:
Name | Type | Default value | Description |
---|---|---|---|
isMultiple |
boolean |
false |
This setting allows (if true) or prohibits (if false) the selection of multiple countries. |
1 2 3 4 | // Country FieldType example settings $settings = [ "isMultiple" => true ]; |
Hash format¶
The format used for serialization is simpler than the full format. It is also available when setting value on the content field, by setting the value to an array instead of the Value object. Example of that shown below:
1 2 | // Value object content example $content->fields["countries"] = [ "JP", "NO" ]; |
The format used by the toHash method is the Alpha2 value, however the input is capable of accepting either Name, Alpha2 or Alpha3 value as shown below in the Value object section.
Value object¶
Properties¶
The Value class of this Field Type contains the following properties:
Property | Type | Description |
---|---|---|
$countries |
array[] |
This property is used for the country selection provided as input, as its attributes. |
1 2 3 4 5 6 7 8 9 | // Value object content example $value->countries = [ "JP" => [ "Name" => "Japan", "Alpha2" => "JP", "Alpha3" => "JPN", "IDC" => 81 ] ]; |
Constructor¶
The Country\Value
constructor will initialize a new Value object with the value provided. It expects an array as input.
1 2 3 4 5 6 7 8 9 10 11 12 13 | // Constructor example // Instantiates a Country Value object $countryValue = new Country\Value( [ "JP" => [ "Name" => "Japan", "Alpha2" => "JP", "Alpha3" => "JPN", "IDC" => 81 ] ] ); |
Date Field Type¶
This Field Type represents a date without time information.
Name | Internal name | Expected input type |
---|---|---|
Date |
ezdate |
mixed |
PHP API Field Type¶
Input expectations¶
If input value is in string
or integer
format, it will be passed directly to PHP's built-in \DateTime
class constructor, therefore the same input format expectations apply.
It is also possible to directly pass an instance of \DateTime
.
Type | Example |
---|---|
string |
"2012-08-28 12:20 Europe/Berlin" |
integer |
1346149200 |
\DateTime |
new \DateTime() |
Time information is not stored.
Before storing, the provided input value will be set to the beginning of the day in the given or the environment timezone.
Value object¶
Properties¶
The Value class of this Field Type contains the following properties:
Property | Type | Description |
---|---|---|
$date |
\DateTime |
This property will be used for the text content. |
String representation¶
String representation of the date value will generate the date string in the format "l d F Y" as accepted by PHP's built-in date()
function.
Character | Description | Example |
---|---|---|
l | Textual representation of a day of the week, range Monday to Sunday | Wednesday |
d | Two digit representation of a day, range 01 to 31 | 22 |
F | Textual representation of a month, range January to December | May |
Y | Four digit representation of a year | 2016 |
Example: Wednesday 22 May 2016
Constructor¶
The constructor for this value object will initialize a new Value object with the value provided. It accepts an instance of PHP's built-in \DateTime
class.
Hash format¶
Hash value of this Field Type is an array with two keys:
Key | Type | Description | Example |
---|---|---|---|
timestamp |
integer |
Time information in unix format timestamp. | 1400856992 |
rfc850 |
string |
Time information as a string in RFC 850 date format. As input, this will have higher precedence over the timestamp value. | "Friday, 23-May-14 14:56:14 GMT+0000" |
1 2 3 4 5 | // Example of the hash value in PHP $hash = [ "timestamp" => 1400856992, "rfc850" => "Friday, 23-May-14 14:56:14 GMT+0000" ]; |
Validation¶
This Field Type does not perform any special validation of the input value.
Settings¶
The Field definition of this Field Type can be configured with a single option:
Name | Type | Default value | Description |
---|---|---|---|
defaultType |
mixed |
Type::DEFAULT_EMPTY |
One of the DEFAULT_* constants, used by the administration interface for setting the default Field value. See below for more details. |
Following defaultType
default value options are available as constants in the eZ\Publish\Core\FieldType\Date\Type
class:
Constant | Description |
---|---|
DEFAULT_EMPTY |
Default value will be empty. |
DEFAULT_CURRENT_DATE |
Default value will use current date. |
1 2 3 4 5 6 7 | // Date Field Type example settings use eZ\Publish\Core\FieldType\Date\Type; $settings = [ "defaultType" => Type::DEFAULT_EMPTY ]; |
Template rendering¶
The template called by the ez_render_field()
Twig function while rendering a Date Field has access to the following parameters:
Parameter | Type | Description |
---|---|---|
locale |
string |
Internal parameter set by the system based on current request locale or if not set, calculated based on the language of the Field. |
Example:
1 | {{ ez_render_field(content, 'date') }} |
DateAndTime Field Type¶
This Field Type represents a full date and time information.
Name | Internal name | Expected input type |
---|---|---|
DateAndTime |
ezdatetime |
mixed |
PHP API Field Type¶
Input expectations¶
If input value is of type string
or integer
, it will be passed directly to the PHP's built-in \DateTime
class constructor, therefore the same input format expectations apply.
It is also possible to directly pass an instance of \DateTime
.
Type | Example |
---|---|
integer |
"2017-08-28 12:20 Europe/Berlin" |
integer |
1346149200 |
\DateTime |
new \DateTime() |
Value object¶
Properties¶
The Value class of this Field Type contains the following properties:
Property | Type | Description |
---|---|---|
$value |
\DateTime |
The date and time value as an instance of \DateTime . |
Constructor¶
The constructor for this value object will initialize a new Value object with the value provided. It accepts an instance of PHP's built-in \DateTime
class.
String representation¶
String representation of the date value will generate the date string in the format D Y-d-m H:i:s
as accepted by PHP's built-in date()
function.
Character | Description | Example |
---|---|---|
D | Three letter representation of a day, range Mon to Sun | Wed |
Y | Four digit representation of a year | 2016 |
d | Two digit representation of a day, range 01 to 31 | 22 |
m | Two digit representation of a month, range 01 to 12 | 05 |
H | Two digit representation of an hour, 24-hour format, range 00 to 23 | 12 |
i | Two digit representation of minutes, range 00 to 59 | 19 |
s | Two digit representation of seconds, range 00 to 59 | 18 |
Example: Wed 2016-22-05 12:19:18
Hash format¶
Hash value of this Field Type is an array with two keys:
Key | Type | Description | Example |
---|---|---|---|
timestamp |
integer |
Time information in Unix format timestamp. | 1400856992 |
rfc850 |
string |
Time information as a string in RFC 850 date format. As input, this will have precedence over the timestamp value. | "Friday, 23-May-14 14:56:14 GMT+0000" |
1 2 3 4 | $hash = [ "timestamp" => 1400856992, "rfc850" => "Friday, 23-May-14 14:56:14 GMT+0000" ]; |
Validation¶
This Field Type does not perform any special validation of the input value.
Settings¶
The Field definition of this Field Type can be configured with several options:
Name | Type | Default value | Description |
---|---|---|---|
useSeconds |
boolean |
false |
Used to control displaying of seconds in the output. |
defaultType |
mixed |
Type::DEFAULT_EMPTY |
One of the DEFAULT_* constants, used by the administration interface for setting the default Field value. See below for more details. |
dateInterval |
null|\DateInterval |
null |
This setting complements defaultType setting and can be used only when the latter is set to Type::DEFAULT_CURRENT_DATE_ADJUSTED . In that case the default input value when using administration interface will be adjusted by the given \DateInterval . |
Following defaultType
default value options are available as constants in the eZ\Publish\Core\FieldType\DateAndTime\Type
class:
Constant | Description |
---|---|
DEFAULT_EMPTY |
Default value will be empty. |
DEFAULT_CURRENT_DATE |
Default value will use current date. |
DEFAULT_CURRENT_DATE_ADJUSTED |
Default value will use current date, adjusted by the interval defined in dateInterval setting. |
1 2 3 4 5 6 7 8 9 | // DateAndTime FieldType example settings use eZ\Publish\Core\FieldType\DateAndTime\Type; $settings = [ "useSeconds" => false, "defaultType" => Type::DEFAULT_EMPTY, "dateInterval" => null ]; |
Template rendering¶
The template called by the ez_render_field()
Twig function while rendering a Date Field has access to the following parameters:
Parameter | Type | Default | Description |
---|---|---|---|
locale |
string |
n/a | Internal parameter set by the system based on current request locale or if not set calculated based on the language of the Field. |
Example:
1 | {{ ez_render_field(content, 'datetime') }} |
EmailAddress Field Type¶
The EmailAddress Field Type represents an email address, in the form of a string.
Name | Internal name | Expected input type |
---|---|---|
EmailAddress |
ezemail |
string |
PHP API Field Type¶
Value object¶
Properties¶
The Value
class of this Field Type contains the following properties:
Property | Type | Description |
---|---|---|
$email |
string |
This property will be used for the input string provided as email address. |
1 2 3 4 5 6 7 8 9 | // Value object content example use eZ\Publish\Core\FieldType\EmailAddress\Type; // Instantiates an EmailAddress Value object with default value (empty string) $emailaddressValue = new Type\Value(); // Email definition $emailaddressValue->email = "someuser@example.com"; |
Constructor¶
The EmailAddress\Value
constructor will initialize a new Value object with the value provided. It accepts a string as input.
1 2 3 4 5 6 | // Constructor example use eZ\Publish\Core\FieldType\EmailAddress\Type; // Instantiates an EmailAddress Value object $emailaddressValue = new Type\Value( "someuser@example.com" ); |
String representation¶
String representation of the Field Type's Value object is the email address contained in it.
Example: someuser@example.com
Hash format¶
Hash value for this Field Type's Value is simply the email address as a string.
Example: someuser@example.com
Validation¶
This Field Type uses the EmailAddressValidator
validator as a resource which will test the string supplied as input against a pattern, to make sure that a valid email address has been provided.
If the validations fail, a ValidationError
is thrown, specifying the error message.
Settings¶
This Field Type does not support settings.
Float Field Type¶
This Field Type stores numeric values which will be provided as floats.
Name | Internal name | Expected input |
---|---|---|
Float |
ezfloat |
float |
PHP API Field Type¶
Input expectations¶
The Field Type expects a number as input. Both decimal and integer numbers are accepted.
Type | Example |
---|---|
float |
194079.572 |
int |
144 |
Value object¶
Properties¶
The Value class of this Field Type contains the following properties:
Property | Type | Description |
---|---|---|
$value |
float |
This property will be used to store the value provided as a float. |
1 2 3 4 5 6 7 8 | // Value object content example use eZ\Publish\Core\FieldType\Float\Type; // Instantiates a Float Value object $floatValue = new Type\Value(); $float->value = 284.773 |
Constructor¶
The Float\Value
constructor will initialize a new Value object with the value provided. It expects a numeric value with or without decimals.
1 2 3 4 5 6 | // Constructor example use eZ\Publish\Core\FieldType\Float\Type; // Instantiates a Float Value object $floatValue = new Type\Value( 284.773 ); |
Validation¶
This Field Type supports FloatValueValidator
, defining maximum and minimum float value:
Name | Type | Default value | Description |
---|---|---|---|
minFloatValue |
float |
`null | This setting defines the minimum value this Field Type will allow as input. |
maxFloatValue |
float |
`null | This setting defines the maximum value this Field Type will allow as input. |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | // Validator configuration example in PHP use eZ\Publish\Core\FieldType\Float\Type; $contentTypeService = $repository->getContentTypeService(); $floatFieldCreateStruct = $contentTypeService->newFieldDefinitionCreateStruct( "float", "ezfloat" ); // Accept only numbers between 0.1 and 203.99 $floatFieldCreateStruct->validatorConfiguration = [ "FileSizeValidator" => [ "minFloatValue" => 0.1, "maxFloatValue" => 203.99 ] ]; |
Settings¶
This Field Type does not support settings.
Image Field Type¶
Name | Internal name |
---|---|
Image |
ezimage |
The Image Field Type allows you to store an image file.
A variation service handles the conversion of the original image into different formats and sizes through a set of preconfigured named variations: large, small, medium, black and white thumbnail, etc.
PHP API Field Type¶
Value object¶
The value
property of an Image Field will return an \eZ\Publish\Core\FieldType\Image\Value
object with the following properties:
Properties¶
Property | Type | Example | Description |
---|---|---|---|
id |
string | 0/8/4/1/1480-1-eng-GB/image.png |
The image's unique identifier. Usually the path, or a part of the path. To get the full path, use the uri property. |
alternativeText |
string | Picture of an apple. |
The alternative text, as entered in the Field's properties |
fileName |
string | image.png |
The original image's filename, without the path |
fileSize |
int | 37931 |
The original image's size, in bytes |
uri |
string | var/ezdemo_site/storage/images/0/8/4/1/1480-1-eng-GB/image.png |
The original image's URI |
imageId |
string | 240-1480 |
A special image ID, used by REST |
inputUri |
string | var/storage/images/test/199-2-eng-GB/image.png |
Input image file URI. |
width * |
int | null |
Original image width in pixels. For more details see Caution note below. |
height * |
int | null |
Original image height in pixels. For more details see Caution note below. |
Caution
Properties marked with an asterisk are currently unsupported. They are available but their value is always null
.
Follow EZP-27987 for future progress on this issue.
Settings¶
This Field Type does not support settings.
Image Variations¶
Using the variation Service, variations of the original image can be obtained. They are \eZ\Publish\SPI\Variation\Values\ImageVariation
objects with the following properties:
Property | Type | Example | Description |
---|---|---|---|
width * |
int | null |
The variation's width in pixels. For more details see Caution note below. |
height * |
int | null |
The variation's height in pixels. For more details see Caution note below. |
name |
string | medium |
The variation's identifier, name of the image alias |
info |
mixed | n/a | Extra information about the image, depending on the image type, such as EXIF data. If there is no information, the info value will be null . |
fileSize |
int | 31010 |
Size (in byte) of current variation |
mimeType |
string | image/png |
The MIME type |
fileName |
string | my_image.png |
The name of the file |
dirPath |
string | var/storage/images/test/199-2-eng-GB |
The path to the file |
uri |
string | var/storage/images/test/199-2-eng-GB/apple.png |
The variation's URI. Complete path with a name of image file |
lastModified |
DateTime | "2017-08-282 12:20 Europe/Berlin" |
When the variation was last modified |
Caution
Properties marked with an asterisk are currently unsupported. They are available but their value is always null
.
Follow EZP-27987 for future progress on this issue.
Field Definition options¶
The Image Field Type supports one FieldDefinition
option: the maximum size for the file.
Note
Maximum size is rounded to 1 MB (legacy storage limitation).
Using an Image Field¶
To read more about handling images and image variations, see the Images documentation.
Template Rendering¶
When displayed using ez_render_field
, an Image Field will output this type of HTML:
1 | <img src="var/ezdemo_site/storage/images/0/8/4/1/1480-1-eng-GB/image_medium.png" width="844" height="430" alt="Alternative text" /> |
The template called by the ez_render_field()
Twig function while rendering a Image Field accepts the following parameters:
Parameter | Type | Default | Description |
---|---|---|---|
alias |
string |
"original" |
The image variation name, must be defined in your SiteAccess's image_variations settings. Defaults to "original", the originally uploaded image. |
width |
int |
n/a | Optionally to specify a different width set on the image HTML tag then then one from image alias. |
height |
int |
n/a | Optionally to specify a different height set on the image HTML tag then then one from image alias. |
class |
string |
n/a | Optionally to specify a specific html class for use in custom JavaScript and/or CSS. |
Example:
1 | {{ ez_render_field( content, 'image', { 'parameters':{ 'alias': 'imagelarge', 'width': 400, 'height': 400 } } ) }} |
The raw Field can also be used if needed. Image variations for the Field's content can be obtained using the ez_image_alias
Twig helper:
1 | {% set imageAlias = ez_image_alias( field, versionInfo, 'medium' ) %} |
The variation's properties can be used to generate the required output:
1 | <img src="{{ asset( imageAlias.uri ) }}" width="{{ imageAlias.width }}" height="{{ imageAlias.height }}" alt="{{ field.value.alternativeText }}" /> |
With the REST API¶
Image Fields within REST are exposed by the application/vnd.ez.api.Content
media-type. An Image Field will look like this:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | <field> <id>1480</id> <fieldDefinitionIdentifier>image</fieldDefinitionIdentifier> <languageCode>eng-GB</languageCode> <fieldValue> <value key="inputUri">/var/ezdemo_site/storage/images/0/8/4/1/1480-1-eng-GB/kidding.png</value> <value key="alternativeText"></value> <value key="fileName">kidding.png</value> <value key="fileSize">37931</value> <value key="imageId">240-1480</value> <value key="uri">/var/ezdemo_site/storage/images/0/8/4/1/1480-1-eng-GB/kidding.png</value> <value key="variations"> <value key="articleimage"> <value key="href">/api/ezp/v2/content/binary/images/240-1480/variations/articleimage</value> </value> <value key="articlethumbnail"> <value key="href">/api/ezp/v2/content/binary/images/240-1480/variations/articlethumbnail</value> </value> </value> </fieldValue> </field> |
Children of the fieldValue
node will list the general properties of the Field's original image (fileSize
, fileName
, inputUri
, etc.), as well as variations. For each variation, a URI is provided. Requested through REST, this resource will generate the variation if it doesn't exist yet, and list the variation details:
1 2 3 4 5 6 7 | <ContentImageVariation media-type="application/vnd.ez.api.ContentImageVariation+xml" href="/api/ezp/v2/content/binary/images/240-1480/variations/tiny"> <uri>/var/ezdemo_site/storage/images/0/8/4/1/1480-1-eng-GB/kidding_tiny.png</uri> <contentType>image/png</contentType> <width>30</width> <height>30</height> <fileSize>1361</fileSize> </ContentImageVariation> |
From PHP code¶
Getting an image variation¶
The variation service, ezpublish.fieldType.ezimage.variation_service
, can be used to generate/get variations for a Field. It expects a VersionInfo, the Image Field, and the variation name as a string (large
, medium
, etc.)
1 2 3 4 5 | $variation = $imageVariationHandler->getVariation( $imageField, $versionInfo, 'large' ); echo $variation->uri; |
Manipulating image content¶
From PHP¶
As for any Field Type, there are several ways to input content to a Field. For an Image, the quickest is to call setField()
on the ContentStruct:
1 2 3 4 5 6 | $createStruct = $contentService->newContentCreateStruct( $contentTypeService->loadContentType( 'image' ), 'eng-GB' ); $createStruct->setField( 'image', '/tmp/image.png' ); |
In order to customize the Image's alternative texts, you must first get an Image\Value
object, and set this property. For that, you can use the Image\Value::fromString()
method that accepts the path to a local file:
1 2 3 4 5 6 7 8 | $createStruct = $contentService->newContentCreateStruct( $contentTypeService->loadContentType( 'image' ), 'eng-GB' ); $imageField = \eZ\Publish\Core\FieldType\Image\Value::fromString( '/tmp/image.png' ); $imageField->alternativeText = 'My alternative text'; $createStruct->setField( 'image', $imageField ); |
You can also provide a hash of Image\Value
properties, either to setField()
, or to the constructor:
1 2 3 4 5 6 7 8 9 10 | $imageValue = new \eZ\Publish\Core\FieldType\Image\Value( [ 'id' => '/tmp/image.png', 'fileSize' => 37931, 'fileName' => 'image.png', 'alternativeText' => 'My alternative text' ] ); $createStruct->setField( 'image', $imageValue ); |
From REST¶
The REST API expects Field values to be provided in a hash-like structure. Those keys are identical to those expected by the Image\Value
constructor: fileName
, alternativeText
. In addition, image data can be provided using the data
property, with the image's content encoded as base64.
Creating an Image Field¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | <?xml version="1.0" encoding="UTF-8"?> <ContentCreate> <!-- [...metadata...] --> <fields> <field> <id>247</id> <fieldDefinitionIdentifier>image</fieldDefinitionIdentifier> <languageCode>eng-GB</languageCode> <fieldValue> <value key="fileName">rest-rocks.jpg</value> <value key="alternativeText">HTTP</value> <value key="data"><![CDATA[/9j/4AAQSkZJRgABAQEAZABkAAD/2wBDAAIBAQIBAQICAgICAgICAwUDAwMDAwYEBAMFBwYHBwcG BwcICQsJCAgKCAcHCg0KCgsMDAwMBwkODw0MDgsMDAz/2[...]</value> </fieldValue> </field> </fields> </ContentCreate> |
Updating an Image Field¶
Updating an Image Field requires that you re-send existing data. This can be done by re-using the Field obtained via REST, removing the variations key, and updating alternativeText
, fileName
or data
. If you do not want to change the image itself, do not provide the data
key.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | <?xml version="1.0" encoding="UTF-8"?> <VersionUpdate> <fields> <field> <id>247</id> <fieldDefinitionIdentifier>image</fieldDefinitionIdentifier> <languageCode>eng-GB</languageCode> <fieldValue> <value key="id">media/images/507-1-eng-GB/Existing-image.png</value> <value key="alternativeText">Updated alternative text</value> <value key="fileName">Updated-filename.png</value> </fieldValue> </field> </fields> </VersionUpdate> |
Naming¶
Each storage engine determines how image files are named.
Legacy Storage Engine naming¶
Images are stored within the following directory structure:
<varDir>/<StorageDir>/<ImagesStorageDir>/<FieldId[-1]>/<FieldId[-2]>/<FieldId[-3]>/<FieldId[-4]>/<FieldId>-<VersionNumber>-<LanguageCode>/
With the following values:
VarDir
=var
(default)StorageDir
=storage
(default)ImagesStorageDir
=images
(default)FieldId
=1480
VersionNumber
=1
LanguageCode
=eng-GB
Images will be stored in web/var/ezdemo_site/storage/images/0/8/4/1/1480-1-eng-GB
.
Using the Field ID digits in reverse order as the folder structure maximizes sharding of files through multiple folders on the filesystem.
Within this folder, images will be named like the uploaded file, suffixed with an underscore and the variation name:
MyImage.png
MyImage_large.png
MyImage_rss.png
Integer Field Type¶
This Field Type represents an integer value.
Name | Internal name | Expected input |
---|---|---|
Integer |
ezinteger |
integer |
PHP API Field Type¶
Input expectations¶
Type | Example |
---|---|
integer |
2397 |
Value object¶
Properties¶
The Value class of this Field Type contains the following properties:
Property | Type | Description |
---|---|---|
$value |
int |
This property is used to store the value provided as an integer. |
1 2 | // Value object content example $integer->value = 8 |
Constructor¶
The Integer\Value
constructor will initialize a new Value object with the value provided. It expects a numeric, integer value.
1 2 3 4 5 | // Constructor example use eZ\Publish\Core\FieldType\Integer; // Instantiates a Integer Value object $integerValue = new Integer\Value( 8 ); |
Hash format¶
Hash value of this Field Type is an integer value as a string.
Example: "8"
String representation¶
String representation of the Field Type's value will return the integer value as a string.
Example: "8"
Validation¶
This Field Type supports IntegerValueValidator
, defining maximum and minimum float value:
Name | Type | Default value | Description |
---|---|---|---|
minIntegerValue |
int |
0 |
This setting defines the minimum value this Field Type will allow as input. |
maxIntegerValue |
int |
null |
This setting defines the maximum value this Field Type will allow as input. |
1 2 3 4 5 | // Example of validator configuration in PHP $validatorConfiguration = [ "minIntegerValue" => 1, "maxIntegerValue" => 24 ]; |
Settings¶
This Field Type does not support settings.
ISBN Field Type¶
This Field Type represents an ISBN string either an ISBN-10 or ISBN-13 format.
Name | Internal name | Expected input type |
---|---|---|
ISBN |
ezisbn |
string |
PHP API Field Type¶
Value object¶
Properties¶
The Value class of this Field Type contains the following properties:
Property | Type | Description |
---|---|---|
$isbn |
string |
This property will be used for the ISBN string. |
String representation¶
An ISBN's string representation is the $isbn
property's value, as a string.
Constructor¶
The constructor for this value object will initialize a new Value object with the value provided. It accepts a string as argument and will set it to the isbn
attribute.
Validation¶
The input passed into this Field Type is subject of ISBN validation depending on the Field settings in its FieldDefinition stored in the Content Type. An example of this Field setting is shown below and will control if input is validated as ISBN-13 or ISBN-10:
1 2 3 4 | Array ( [isISBN13] => true ) |
Keyword Field Type¶
This Field Type stores one or several comma-separated keywords as a string or array of strings.
Name | Internal name | Expected input |
---|---|---|
Keyword |
ezkeyword |
string[]|string |
PHP API Field Type¶
Input expectations¶
Type | Example |
---|---|
string |
"documentation" |
string |
"php, eZ Platform, html5" |
string[] |
[ "eZ Systems", "Enterprise", "User Experience Management" ] |
Value object¶
Properties¶
The Value class of this Field Type contains the following properties:
Property | Type | Description |
---|---|---|
$value |
string[] |
Holds an array of keywords as strings. |
1 2 3 4 5 6 7 8 | // Value object content example use eZ\Publish\Core\FieldType\Keyword\Value; // Instantiates a Value object $keywordValue = new Value(); // Sets an array of keywords as a value $keyword->value = [ "php", "css3", "html5", "eZ Platform" ]; |
Constructor¶
The Keyword\Value
constructor will initialize a new Value object with the value provided.
It expects a list of keywords, either comma-separated in a string or as an array of strings.
1 2 3 4 5 6 7 8 9 | // Constructor example use eZ\Publish\Core\FieldType\Keyword\Value; // Instantiates a Value object with an array of keywords $keywordValue = new Value( [ "php5", "css3", "html5" ] ); // Instantiates a Value object with a list of keywords in a string // This is equivalent to the example above $keywordValue = new Value( "php5,css3,html5" ); |
Enterprise
Landing Page Field Type¶
Landing Page Field Type represents a page with a layout consisting of multiple zones. Each zone can in turn contain blocks.
Landing Page Field Type is only used in the Landing Page Content Type that is included in eZ Enterprise.
Caution
The default Field Type identifiers of the Landing Page Content Type should not be modified, as it may cause fatal errors. Fields of other types can be added safely but shouldn't be required.
Name | Internal name | Expected input |
---|---|---|
Landing page |
ezlandingpage |
string (JSON) |
Layout and zones¶
Layout defines how a Landing Page is divided into zones.
The placement of zones is defined in a template which is a part of the layout configuration. You can modify the template in order to define your own layout of zones.
For information on how to create and configure new blocks for the Landing Page, see Landing Page layouts.
Blocks¶
For information on how to create and configure new blocks for the Landing Page, see Landing Page blocks.
Rendering Landing Pages¶
Landing Page rendering takes place while editing or viewing.
When rendering a Landing Page, its zones are passed to the layout as a zones
array with a blocks
array each. You can access them using twig (e.g. {{ zones[0].id }}
).
Each div that's a zone or zone's container should have data attributes:
data-studio-zones-container
for a div containing zonesdata-studio-zone
with zone ID as a value for a zone container
To render a block inside the layout, use the Twig render_esi()
function to call ez_block:renderBlockAction
.
ez_block
is an alias to EzSystems\LandingPageFieldTypeBundle\Controller\BlockController
The action has the following parameters:
Parameter | Description |
---|---|
contentId |
ID of the Content item which can be accessed by contentInfo.id |
blockId |
ID of the block which you want to render |
Example usage:
1 2 3 4 5 | {{ render_esi(controller('ez_block:renderBlockAction', { 'contentId': contentInfo.id, 'blockId': block.id })) }} |
As a whole a sample layout could look as follows:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | <!--landing_page_simple_layout.html.twig--> {# The required "data-studio-zones-container" attribute, enables displaying zones #} <div data-studio-zones-container> {# The required attribute for the displayed zone #} <div data-studio-zone="{{ zones[0].id }}"> {# If a zone with [0] index contains any blocks #} {% if zones[0].blocks %} {# for each block #} {% for block in blocks %} {# create a new layer with appropriate ID #} <div class="landing-page__block block_{{ block.type }}"> {# render the block by using the "ez_block:renderBlockAction" controller #} {# contentInfo.id is the ID of the current Content item, block.id is the ID of the current block #} {{ render_esi(controller('ez_block:renderBlockAction', { 'contentId': contentInfo.id, 'blockId': block.id })) }} </div> {% endfor %} {% endif %} </div> </div> |
Viewing template¶
Your view is populated with data (parameters) retrieved from the getTemplateParameters()
method which must be implemented in your block's class.
Example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | /** * @param \EzSystems\LandingPageFieldTypeBundle\FieldType\LandingPage\Model\BlockValue $blockValue * * @return array */ public function getTemplateParameters(BlockValue $blockValue) { $attributes = $blockValue->getAttributes(); $limit = (isset($attributes['limit'])) ? $attributes['limit'] : 10; $offset = (isset($attributes['offset'])) ? $attributes['offset'] : 0; $parameters = [ 'title' => $attributes['title'], 'limit' => $limit, 'offset' => $offset, 'feeds' => $this->RssProvider->getFeeds($attributes['url']), ]; return $parameters; } |
MapLocation Field Type¶
This Field Type represents a geographical location.
As input it expects three values: - two float values latitude and longitude, - a string value, corresponding to the name or address of the location.
Name | Internal name | Expected input |
---|---|---|
MapLocation |
ezgmaplocation |
mixed |
PHP API Field Type¶
Input expectations¶
Type | Example |
---|---|
array |
[ 'latitude' => 59.928732, 'longitude' => 10.777888, 'address' => "eZ Systems Norge" ] |
Value object¶
Properties¶
The Value class of this Field Type contains the following properties:
Property | Type | Description |
---|---|---|
$latitude |
float |
This property stores the latitude value of the map location reference. |
$longitude |
float |
This property stores the longitude value of the map location reference. |
$address |
string |
This property stores the address of map location. |
Constructor¶
The MapLocation\Value
constructor will initialize a new Value object with values provided as hash. Accepted keys are latitude
(float
), longitude
(float
), address
(string
).
1 2 3 4 5 6 7 8 9 10 | // Constructor example // Instantiates a MapLocation Value object $MapLocationValue = new MapLocation\Value( [ 'latitude' => 59.928732, 'longitude' => 10.777888, 'address' => "eZ Systems Norge" ] ); |
Template rendering¶
The template called by the ez_render_field()
Twig function while rendering a Map Location Field accepts the following parameters:
Parameter | Type | Default | Description |
---|---|---|---|
draggable |
boolean |
true |
Whether to enable a draggable map |
height |
string|false |
"200px" |
The height of the rendered map with its unit (for example "200px" or "20em"), set to false to not set any height style inline. |
mapType |
string |
"ROADMAP" |
One of the GMap types of map |
scrollWheel |
boolean |
true |
Allows you to disable scroll wheel starting to zoom when mouse comes over the map as user scrolls down a page. |
showInfo |
booolean |
true |
Whether to show a latitude, longitude and the address outside of the map |
showMap |
boolean |
true |
Whether to show a Google Map |
width |
string|false |
"500px" |
The width of the rendered map with its unit (for example "500px" or "50em"), set to false to not set any width style inline. |
zoom |
integer |
13 |
The initial zoom level on the map |
Example:
1 | {{ ez_render_field(content, 'location', {'parameters': {'width': '100%', 'height': '330px', 'showMap': true, 'showInfo': false}}) }} |
Configuration¶
Config | SiteAccess-aware | Description |
---|---|---|
api_keys.google_maps |
yes | Google maps requires the use of an API key for serving maps to web pages. This setting allows you to specify your personal Google Maps API key used during template rendering. |
Example use:
1 2 3 4 5 | # ezplatform.yml ezpublish: system: site_group: api_keys: { google_maps: MY_KEY } |
Media Field Type¶
This Field Type represents and handles a media (audio/video) binary file.
It is capable of handling the following types of files:
- Apple QuickTime
- Adobe Flash
- Microsoft Windows Media
- Real Media
- Silverlight
- HTML5 Video
- HTML5 Audio
Name | Internal name | Expected input |
---|---|---|
Media |
ezmedia |
mixed |
PHP API Field Type¶
Input expectations¶
Type | Description | Example |
---|---|---|
string |
Path to the media file. | /Users/jane/butterflies.mp4 |
eZ\Publish\Core\FieldType\Media\Value |
Media Field Type Value Object with path to the media file as the value of id property. |
See below. |
Value object¶
Properties¶
eZ\Publish\Core\FieldType\Media\Value
offers the following properties.
Note that both Media
and BinaryFile
Value and Type inherit from the BinaryBase
abstract Field Type and share common properties.
Property | Type | Description | Example |
---|---|---|---|
id |
string | Media file identifier. This ID depends on the IO Handler that is being used. With the native, default handlers (FileSystem and Legacy), the ID is the file path, relative to the binary file storage root dir (var/<vardir>/storage/original by default). |
application/63cd472dd7819da7b75e8e2fee507c68.mp4 |
fileName |
string | The human-readable file name, as exposed to the outside. Used to name the file when sending it for download. | butterflies.mp4 |
fileSize |
int | File size, in bytes. | 1077923 |
mimeType |
string | The file's MIME type. | video/mp4 |
uri |
string | The binary file's HTTP URI. If the URI doesn't include a host or protocol, it applies to the request domain. The URI is not publicly readable, and must NOT be used to link to the file for download. Use ez_render_field to generate a valid link to the download controller. |
/var/ezdemo_site/storage/original/application/63cd472dd7819da7b75e8e2fee507c68.mp4 |
hasController |
boolean | Whether the media has a controller when being displayed. | true |
autoplay |
boolean | Whether the media should be automatically played. | true |
loop |
boolean | Whether the media should be played in a loop. | false |
height |
int | Height of the media. | 300 |
width |
int | Width of the media. | 400 |
path |
string | deprecated |
Hash format¶
The hash format mostly matches the value object. It has the following keys:
id
path
(for backwards compatibility)fileName
fileSize
mimeType
uri
hasController
autoplay
loop
height
width
Validation¶
The Field Type supports FileSizeValidator
, defining maximum size of media file in bytes:
Name | Type | Default value | Description |
---|---|---|---|
maxFileSize |
int |
false |
Maximum size of the file in bytes. |
1 2 3 4 5 6 7 8 9 10 11 12 13 | // Example of using Media Field Type validator in PHP use eZ\Publish\Core\FieldType\Media\Type; $contentTypeService = $repository->getContentTypeService(); $mediaFieldCreateStruct = $contentTypeService->newFieldDefinitionCreateStruct( "media", "ezmedia" ); // Setting maximum file size to 5 megabytes $mediaFieldCreateStruct->validatorConfiguration = [ "FileSizeValidator" => [ "maxFileSize" => 5 * 1024 * 1024 ] ]; |
Settings¶
The Field Type supports the mediaType
setting, defining how the media file should be handled in output.
Name | Type | Default value | Description |
---|---|---|---|
mediaType |
mixed | Type::TYPE_HTML5_VIDEO |
Type of the media, accepts one of the predefined constants. |
List of all available mediaType
constants is defined in the eZ\Publish\Core\FieldType\Media\Type
class:
Name | Description |
---|---|
TYPE_FLASH |
Adobe Flash |
TYPE_QUICKTIME |
Apple QuickTime |
TYPE_REALPLAYER |
Real Media |
TYPE_SILVERLIGHT |
Silverlight |
TYPE_WINDOWSMEDIA |
Microsoft Windows Media |
TYPE_HTML5_VIDEO |
HTML5 Video |
TYPE_HTML5_AUDIO |
HTML5 Audio |
1 2 3 4 5 6 7 8 9 10 11 | // Example of using Media Field Type settings in PHP use eZ\Publish\Core\FieldType\Media\Type; $contentTypeService = $repository->getContentTypeService(); $mediaFieldCreateStruct = $contentTypeService->newFieldDefinitionCreateStruct( "media", "ezmedia" ); // Setting Adobe Flash as the media type $mediaFieldCreateStruct->fieldSettings = [ "mediaType" => Type::TYPE_FLASH, ]; |
Null Field Type¶
This Field Type is used as fallback and for testing purposes.
Name | Internal name | Expected input type |
---|---|---|
Null |
variable | mixed |
Description¶
The Null Field Type serves as an aid when migrating from eZ Publish Platform and earlier versions. It is a dummy for legacy Field Types that are not implemented in eZ Platform.
Null Field Type will accept anything provided as a value. When used with NullConverter, it also won't store anything to the database, nor will it read any data from the database.
This Field Type does not have its own fixed internal name. Its identifier is instead configured as needed by passing it as an argument to the constructor.
Following example shows how Null Field Type and NullConverter are used to configure dummy implementations for ezcomcomments
and ezpaex
legacy datatypes:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | # Null Fieldtype example configuration parameters: ezpublish.fieldType.eznull.class: eZ\Publish\Core\FieldType\Null\Type ezpublish.fieldType.eznull.converter.class: eZ\Publish\Core\Persistence\Legacy\Content\FieldValue\Converter\NullConverter services: ezpublish.fieldType.ezcomcomments: class: %ezpublish.fieldType.eznull.class% parent: ezpublish.fieldType arguments: [ "ezcomcomments" ] tags: - {name: ezpublish.fieldType, alias: ezcomcomments} ezpublish.fieldType.ezpaex: class: '%ezpublish.fieldType.eznull.class%' parent: ezpublish.fieldType arguments: [ezpaex] tags: - {name: ezpublish.fieldType, alias: ezpaex} ezpublish.fieldType.ezcomcomments.converter: class: '%ezpublish.fieldType.eznull.converter.class%' tags: - {name: ezpublish.storageEngine.legacy.converter, alias: ezcomcomments} ezpublish.fieldType.ezpaex.converter: class: '%ezpublish.fieldType.eznull.converter.class%' tags: - {name: ezpublish.storageEngine.legacy.converter, alias: ezpaex} |
Rating Field Type¶
Caution
The Rating Field Type is available in the back-end interface, but it does not have editing templates, which makes it unusable in practice.
Follow EZP-25802 for future progress on this Field Type.
Relation Field Type¶
This Field Type makes it possible to store and retrieve the value of a relation to another Content item.
Name | Internal name | Expected input |
---|---|---|
Relation |
ezobjectrelation |
mixed |
PHP API Field Type¶
Input expectations¶
Type | Example |
---|---|
string |
"150" |
integer |
150 |
Value object¶
Properties¶
The Value class of this Field Type contains the following properties:
Property | Type | Description |
---|---|---|
$destinationContentId |
string|int|null |
This property is used to store the value provided, which represents the related content. |
1 2 3 | // Value object content example $relation->destinationContentId = $contentInfo->id; |
Constructor¶
The Relation\Value
constructor will initialize a new Value object with the value provided. It expects a mixed value.
1 2 3 4 | // Constructor example // Instantiates a Relation Value object $relationValue = new Relation\Value( $contentInfo->id ); |
Validation¶
This Field Type validates whether the provided relation exists, but before that it will check that the value is either a string or an int.
Settings¶
The Field definition of this Field Type can be configured with two options:
Name | Type | Default value | Description |
---|---|---|---|
selectionMethod |
int |
Relation\Type::SELECTION_BROWSE |
This setting is not implemented yet, only one selection method is available. |
selectionRoot |
string |
null |
This setting defines the selection root. |
selectionContentTypes |
array |
[] |
This setting defines allowed Content Types |
1 2 3 4 5 6 7 8 | // Relation FieldType example settings use eZ\Publish\Core\FieldType\Relation\Type; $settings = [ "selectionMethod" => 0, "selectionRoot" => null ]; |
RelationList Field Type¶
This Field Type makes it possible to store and retrieve values of a relation to other Content items.
Name | Internal name | Expected input |
---|---|---|
RelationList |
ezobjectrelationlist |
mixed |
PHP API Field Type¶
Input expectations¶
Type | Description | Example |
---|---|---|
int|string |
ID of the related Content item | 42 |
array |
An array of related Content IDs | [ 24, 42 ] |
eZ\Publish\API\Repository\Values\Content\ContentInfo |
ContentInfo instance of the related Content | n/a |
eZ\Publish\Core\FieldType\RelationList\Value |
RelationList Field Type Value Object | See below. |
Value Object¶
Properties¶
eZ\Publish\Core\FieldType\RelationList\Value
contains the following properties:
Property | Type | Description | Example |
---|---|---|---|
destinationContentIds |
array |
An array of related Content IDs | [ 24, 42 ] |
1 2 3 4 5 6 | // Value object content example $relationList->destinationContentId = [ $contentInfo1->id, $contentInfo2->id, 170 ]; |
Constructor¶
The RelationList\Value
constructor will initialize a new Value object with the value provided. It expects a mixed array as value.
1 2 3 4 5 6 7 8 9 10 | //Constructor example // Instantiates a RelationList Value object $relationListValue = new RelationList\Value( [ $contentInfo1->id, $contentInfo2->id, 170 ] ); |
Validation¶
This Field Type validates if:
- the
selectionMethod
specified is\eZ\Publish\Core\FieldType\RelationList\Type::SELECTION_BROWSE
or\eZ\Publish\Core\FieldType\RelationList\Type::SELECTION_DROPDOWN
. A validation error is thrown if the value does not match. - the
selectionDefaultLocation
specified isnull
,string
orinteger
. If the type validation fails a validation error is thrown. - the value specified in
selectionContentTypes
is anarray
. If not, a validation error in given.
Note
The dropdown selection method is not implemented yet.
Settings¶
The Field definition of this Field Type can be configured with the following options:
Name | Type | Default value | Description |
---|---|---|---|
selectionMethod |
mixed |
SELECTION_BROWSE |
Method of selection in the back-end interface |
selectionDefaultLocation |
string|integer |
null |
ID of the default Location for the selection when using the back-end interface |
selectionContentTypes |
array |
[] |
An array of Content Type IDs that are allowed for related Content |
Following selection methods are available:
Name | Description |
---|---|
SELECTION_BROWSE |
Selection will use browse mode |
SELECTION_DROPDOWN |
Not implemented yet |
1 2 3 4 5 6 7 8 9 | // Example of using settings in PHP use eZ\Publish\Core\FieldType\RelationList\Type; $settings = [ "selectionMethod" => Type::SELECTION_BROWSE, "selectionDefaultLocation" => null, "selectionContentTypes" => [] ]; |
RichText Field Type¶
This Field Type validates and stores structured rich text, and exposes it in several formats.
Name | Internal name | Expected input |
---|---|---|
RichText |
ezrichtext |
mixed |
PHP API Field Type¶
Input expectations¶
Type | Description | Example |
---|---|---|
string |
XML document in one of the Field Type's input formats as a string. | See the example below. |
DOMDocument |
XML document in one of the Field Type's input formats as a DOMDocument object. |
See the example below. |
eZ\Publish\Core\FieldType\RichText\Value |
An instance of the Field Type's Value object. |
See the example below. |
Input formats¶
The Field Type works with XML and also expects an XML value as input, whether as a string, DOMDocument
object or Field Type's Value
object. When the value is given as a string or a DOMDocument
object, it will be checked for conformance with one of the supported input formats, then dispatched to the appropriate converter, to be converted to the Field Type's internal format. No conversion will be performed if providing the value in Field Type's internal format or as Field Type's Value
object. In the latter case it will be expected that the Value
object holds the value in the Field Type's internal format.
Currently supported input formats are described in the table below:
Name | Description |
---|---|
eZ Platform's DocBook variant | Field Type's internal format |
XHTML5 editing format | Typically used with in-browser HTML editor |
Legacy eZXML format | Compatibility with legacy eZXML format, used by XmlText Field Type |
Example of the Field Type's internal format¶
1 2 3 4 5 6 7 8 9 | <?xml version="1.0" encoding="UTF-8"?> <section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ezxhtml="http://ez.no/xmlns/ezpublish/docbook/xhtml" xmlns:ezcustom="http://ez.no/xmlns/ezpublish/docbook/custom" version="5.0-variant ezpublish-1.0"> <title ezxhtml:level="2">This is a title.</title> <para ezxhtml:class="paraClass">This is a paragraph.</para> </section> |
Example of the Field Type's XHTML5 edit format¶
This format is used by eZ Platform's Online Editor.
1 2 3 4 5 | <?xml version="1.0" encoding="UTF-8"?> <section xmlns="http://ez.no/namespaces/ezpublish5/xhtml5/edit"> <h2>This is a title.</h2> <p class="paraClass">This is a paragraph.</p> </section> |
For more information about internal format and input formats, see Field Type's conversion test fixtures on GitHub.
For example, ezxml does not use explicit level attributes for <header>
elements, instead <header>
element levels are indicated through the level of nesting inside <section>
elements.
Example of using XML document in internal format as a string¶
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | ... $contentService = $repository->getContentService(); $contentTypeService = $repository->getContentTypeService(); $contentType = $contentTypeService->loadContentTypeByIdentifier( "article" ); $contentCreateStruct = $contentService->newContentCreateStruct( $contentType, "eng-GB" ); $inputString = <<<DOCBOOK <?xml version="1.0" encoding="UTF-8"?> <section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ezxhtml="http://ez.no/xmlns/ezpublish/docbook/xhtml" xmlns:ezcustom="http://ez.no/xmlns/ezpublish/docbook/custom" version="5.0-variant ezpublish-1.0"> <title ezxhtml:level="2">This is a title.</title> <para ezxhtml:class="paraClass">This is a paragraph.</para> </section> DOCBOOK; $contentCreateStruct->setField( "description", $inputString ); ... |
Value object¶
eZ\Publish\Core\FieldType\RichText\Value
offers the following properties:
Property | Type | Description |
---|---|---|
xml |
DOMDocument |
Internal format value as an instance of DOMDocument . |
REST API specifics¶
Creating or updating Content¶
When creating RichText content with the REST API, it is possible to provide data as a string, using the xml
fieldValue key:
1 2 3 4 5 6 7 | <fieldValue> <value key="xml"><?xml version="1.0" encoding="UTF-8"?> <section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ezxhtml="http://ez.no/xmlns/ezpublish/docbook/xhtml" xmlns:ezcustom="http://ez.no/xmlns/ezpublish/docbook/custom" version="5.0-variant ezpublish-1.0"> <title ezxhtml:level="2">This is a title.</title> </section> </value> </fieldValue> |
When the value given over REST API is transformed into a Field Type's Value
object, it will be treated as a string. This means you can use any supported input format for input over REST API.
For further information about the internal implementation of RichText Field Type, see the kernel documentation
Selection Field Type¶
The Selection Field Type stores single selections or multiple choices from a list of options, by populating a hash with the list of selected values.
Name | Internal name | Expected input type |
---|---|---|
Selection |
ezselection |
mixed |
PHP API Field Type¶
Input expectations¶
Type | Example |
---|---|
array |
[ 1, 2 ] |
Value object¶
Properties¶
The Value class of this Field Type contains the following properties:
Property | Type | Description |
---|---|---|
$selection |
int[] |
This property is used for the list of selections, which is a list of integer values, or one single integer value. |
1 2 3 4 5 6 7 | // Value object content examples // Single selection $value->selection = 1; // Multiple selection $value->selection = [ 1, 4, 5 ]; |
Constructor¶
The Selection\Value
constructor accepts an array of selected element identifiers.
1 2 3 4 | // Constructor example // Instanciates a selection value with items #1 and #2 selected $selectionValue = new Selection\Value( [ 1, 2 ] ); |
String representation¶
String representation of this Field Type is its list of selections as a string, concatenated with a comma.
Example: "1,2,24,42"
Hash format¶
Hash format of this Field Type is the same as Value object's selection
property.
1 2 3 | // Example of value in hash format $hash = [ 1, 2 ]; |
Validation¶
This Field Type validates the input, verifying if all selected options exist in the Field definition and checks if multiple selections are allowed in the Field definition.
If any of these validations fail, a ValidationError
is thrown, specifying the error message. When option validation fails, a list with the invalid options is also presented.
Settings¶
Name | Type | Default value | Description |
---|---|---|---|
isMultiple |
boolean |
false |
Used to allow or prohibit multiple selection from the option list. |
options |
hash |
[] |
Stores the list of options defined in the Field definition. |
1 2 3 4 5 6 7 8 | // Selection Field Type example settings use eZ\Publish\Core\FieldType\Selection\Type; $settings = [ "isMultiple" => true, "options" => [1 => 'One', 2 => 'Two', 3 => 'Three'] ]; |
TextBlock Field Type¶
The Field Type handles a block of multiple lines of unformatted text. It is capable of handling up to 16,777,216 characters.
Name | Internal name | Expected input type |
---|---|---|
TextBlock |
eztext |
string |
PHP API Field Type¶
Input expectations¶
Type | Example |
---|---|
string |
"This is a block of unformatted text" |
Value object¶
Properties¶
The Value class of this Field Type contains the following properties:
Property | Type | Description |
---|---|---|
$text |
string |
This property will be used for the text content. |
String representation¶
A TextBlock's string representation is the $text
property's value, as a string.
Constructor¶
The constructor for this Value object will initialize a new Value object with the value provided. It accepts a string as argument and will import it to the $text
attribute.
Validation¶
This Field Type does not perform any special validation of the input value.
Settings¶
Settings contain only one option:
Name | Type | Default value | Description |
---|---|---|---|
textRows |
integer |
10 |
Number of rows for the editing box in the back-end interface. |
TextLine Field Type¶
This Field Type makes possible to store and retrieve a single line of unformatted text. It is capable of handling up to 255 characters.
Name | Internal name | Expected input type |
---|---|---|
TextLine |
ezstring |
string |
PHP API Field Type¶
Value object¶
Properties¶
The Value class of this Field Type contains the following properties:
Property | Type | Description |
---|---|---|
$text |
string |
This property will be used for the text content. |
String representation¶
A TextLine's string representation is the $text
property's value, as a string.
Constructor¶
The constructor for this Value object will initialize a new Value object with the value provided. It accepts a string as argument and will import it to the $text
attribute.
Validation¶
The input passed into this Field Type is subject to validation by the StringLengthValidator
. The length of the string provided must be between the minimum length defined in minStringLength
and the maximum defined in maxStringLength
. The default value for both properties is 0, which means that the validation is disabled by default.
To set the validation properties, the validateValidatorConfiguration()
method needs to be inspected, which will receive an array with minStringLength
and maxStringLength
like in the following representation:
1 2 3 4 5 | Array ( [minStringLength] => 1 [maxStringLength] => 60 ) |
Time Field Type¶
This Field Type represents time information.
Date information is not stored.
What is stored is the number of seconds, calculated from the beginning of the day in the given or the environment timezone.
Name | Internal name | Expected input type |
---|---|---|
Time |
eztime |
mixed |
PHP API Field Type¶
Input expectations¶
If input value is of type string
or integer
, it will be passed directly to the PHP's built-in \DateTime
class constructor, therefore the same input format expectations apply.
It is also possible to directly pass an instance of \DateTime
.
Type | Example |
---|---|
string |
"2012-08-28 12:20 Europe/Berlin" |
integer |
1346149200 |
\DateTime |
new \DateTime() |
Value object¶
Properties¶
The Value class of this Field Type contains the following properties:
Property | Type | Description |
---|---|---|
$time |
integer|null |
Holds the time information as a number of seconds since the beginning of the day. |
Constructor¶
The constructor for this Value object will initialize a new Value object with the value provided. It accepts an integer representing the number of seconds since the beginning of the day.
String representation¶
String representation of the date value will generate the date string in the format "H:i:s" as accepted by PHP's built-in date()
function.
Character | Description | Example |
---|---|---|
H | Two digit representation of an hour, 24-hour format, range 00 to 23 | 12 |
i | Two digit representation of minutes, range 00 to 59 | 14 |
s | Two digit representation of seconds, range 00 to 59 | 56 |
Example: "12:14:56"
Hash format¶
Value in hash format is an integer representing a number of seconds since the beginning of the day.
Example: 36000
Validation¶
This Field Type does not perform validation of the input value.
Settings¶
The Field definition of this Field Type can be configured with several options:
Name | Type | Default value | Description |
---|---|---|---|
useSeconds |
boolean |
false |
Used to control displaying of seconds in the output. |
defaultType |
Type::DEFAULT_EMPTY Type::DEFAULT_CURRENT_TIME |
Type::DEFAULT_EMPTY |
The constant used here defines default input value when using back-end interface. |
1 2 3 4 5 6 | // Time Field Type example settings use eZ\Publish\Core\FieldType\Time\Type; $settings = [ "defaultType" => DateAndTime::DEFAULT_EMPTY ]; |
Template rendering¶
The template called by the ez_render_field()
Twig function while rendering a Date Field has access to the following parameters:
Parameter | Type | Default | Description |
---|---|---|---|
locale |
string |
n/a | Internal parameter set by the system based on current request locale or, if not set, calculated based on the language of the Field. |
Example:
1 | {{ ez_render_field(content, 'time') }} |
URL Field Type¶
This Field Type makes it possible to store and retrieve a URL. It is formed by the combination of a link and the respective text.
Name | Internal name | Expected input |
---|---|---|
Url |
ezurl |
string |
PHP API Field Type¶
Input expectations¶
Type | Description | Example |
---|---|---|
string |
Link content provided to the value. | "http://www.ez.no" |
string |
Text content that represents the stored link. | "eZ Systems" |
Value object¶
Properties¶
The Value class of this Field Type contains the following properties:
Property | Type | Description |
---|---|---|
$link |
string |
This property stores the link provided to the value of this Field Type. |
$text |
string |
This property stores the text to represent the stored link provided to the value of this Field Type. |
1 2 3 4 | // Value object content example $url->link = "http://www.ez.no"; $url->text = "eZ Systems"; |
Constructor¶
The Url\Value
constructor initializes a new Value object with the provided value. It expects two comma-separated strings, corresponding to the link and text.
1 2 3 4 | // Constructor example // Instantiates an Url Value object $UrlValue = new Url\Value( "http://www.ez.no", "eZ Systems" ); |
Hash format¶
Key | Type | Description | Example |
---|---|---|---|
link |
string |
Link content. | "http://ez.no" |
text |
string |
Text content. | "eZ Systems" |
1 2 3 4 5 | // Example of the hash value in PHP $hash = [ "link" => "http://ez.no", "text" => "eZ Systems" ]; |
Validation¶
This Field Type does not perform validation.
Settings¶
This Field Type does not have settings.
User Field Type¶
This Field Type validates and stores information about a user.
Name | Internal name | Expected input |
---|---|---|
User |
ezuser |
ignored |
PHP API Field Type¶
Value Object¶
Property | Type | Description | Example |
---|---|---|---|
hasStoredLogin |
boolean |
Denotes if user has stored login. | true |
contentId |
int|string |
ID of the Content item corresponding to the user. | 42 |
login |
string |
Username. | john |
email |
string |
The user's email address. | john@smith.com |
passwordHash |
string |
Hash of the user's password. | 1234567890abcdef |
passwordHashType |
mixed |
Algorithm user for generating password hash as a PASSWORD_HASH_* constant defined in eZ\Publish\Core\Repository\Values\User\User class. |
User::PASSWORD_HASH_MD5_USER |
maxLogin |
int |
Maximum number of concurrent logins. | 1000 |
Available password hash types¶
Constant | Description |
---|---|
eZ\Publish\Core\Repository\Values\User\User::PASSWORD_HASH_MD5_PASSWORD |
MD5 hash of the password, not recommended. |
eZ\Publish\Core\Repository\Values\User\User::PASSWORD_HASH_MD5_USER |
MD5 hash of the password and username. |
eZ\Publish\Core\Repository\Values\User\User::PASSWORD_HASH_MD5_SITE |
MD5 hash of the password, username and site name. |
eZ\Publish\Core\Repository\Values\User\User::PASSWORD_HASH_PLAINTEXT |
Passwords are stored in plaintext, should not be used for real sites. |
XmlText Field Type¶
The XmlText Field Type isn't officially supported by eZ Platform. It can be installed by requiring ezsystems/ezplatform-xmltext-fieldtype
. PlatformUI does not support WYSIWYG editing of Fields of this type.
This Field Type validates and stores formatted text using the eZ Publish legacy format, ezxml.
Name | Internal name | Expected input |
---|---|---|
XmlText |
ezxmltext |
mixed |
Input expectations¶
Type | Description | Example |
---|---|---|
string |
XML document in the Field Type internal format as a string. | See the example below. |
eZ\Publish\Core\FieldType\XmlText\Input |
An instance of the class implementing the Field Type's abstract Input class. |
See the example below. |
eZ\Publish\Core\FieldType\XmlText\Value |
An instance of the Field Type's Value object. |
See the example below. |
Example of the Field Type's internal format¶
1 2 3 4 5 6 7 | <?xml version="1.0" encoding="utf-8"?> <section xmlns:custom="http://ez.no/namespaces/ezpublish3/custom/" xmlns:image="http://ez.no/namespaces/ezpublish3/image/" xmlns:xhtml="http://ez.no/namespaces/ezpublish3/xhtml/"> <paragraph>This is a paragraph.</paragraph> </section> |
For XHTML Input¶
The eZ XML output uses <strong>
and <em>
by default, respecting the semantic XHTML notation.
Learn more about <strong>
, <b>
, <em>
, <i>
:
Input object API¶
Input
object is intended as a vector for different input formats. It should accept input value in a foreign format and convert it to the Field Type's internal format.
It should implement the abstract eZ\Publish\Core\FieldType\XmlText\Input
class, which defines only one method:
Method | Description |
---|---|
getInternalRepresentation |
The method returns the input value in the internal format. |
At the moment there is only one implementation of the Input
class, eZ\Publish\Core\FieldType\XmlText\Input\EzXml
, which accepts input value in the internal format, and therefore only performs validation of the input value.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 | // Example of using the Input object ... use eZ\Publish\Core\FieldType\XmlText\Input\EzXml as EzXmlInput; ... $contentService = $repository->getContentService(); $contentTypeService = $repository->getContentTypeService(); $contentType = $contentTypeService->loadContentTypeByIdentifier( "article" ); $contentCreateStruct = $contentService->newContentCreateStruct( $contentType, "eng-GB" ); $inputString = <<<EZXML <?xml version="1.0" encoding="utf-8"?> <section xmlns:custom="http://ez.no/namespaces/ezpublish3/custom/" xmlns:image="http://ez.no/namespaces/ezpublish3/image/" xmlns:xhtml="http://ez.no/namespaces/ezpublish3/xhtml/"> <paragraph>This is a paragraph.</paragraph> </section> EZXML; $ezxmlInput = new EzXmlInput( $inputString ); $contentCreateStruct->setField( "description", $ezxmlInput ); ... |
Value object API¶
eZ\Publish\Core\FieldType\XmlText\Value
offers the following properties:
Property | Type | Description |
---|---|---|
xml |
DOMDocument |
Internal format value as an instance of DOMDocument . |
Validation¶
Validation of the internal format is performed in the eZ\Publish\Core\FieldType\XmlText\Input\EzXml
class.
Settings¶
Following settings are available:
Name | Type | Default value | Description |
---|---|---|---|
numRows |
int |
10 |
Defines the number of rows for the online editor in the back-end interface. |
tagPreset |
mixed |
Type::TAG_PRESET_DEFAULT |
Preset of tags for the online editor in the back-end interface. |
Tag presets¶
Following tag presets are available as constants in the eZ\Publish\Core\FieldType\XmlText
class:
Constant | Description |
---|---|
TAG_PRESET_DEFAULT |
Default tag preset. |
TAG_PRESET_SIMPLE_FORMATTING |
Preset of tags for online editor intended for simple formatting options. |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | // Example of using settings in PHP ... use eZ\Publish\Core\FieldType\XmlText\Type; ... $contentTypeService = $repository->getContentTypeService(); $xmltextFieldCreateStruct = $contentTypeService->newFieldDefinitionCreateStruct( "description", "ezxmltext" ); $xmltextFieldCreateStruct->fieldSettings = [ "numRows" => 25, "tagPreset" => Type::TAG_PRESET_SIMPLE_FORMATTING ]; ... |