Objects¶
Site API comes with it’s own set of entities and values. These are similar, but still different from their counterparts in eZ Platform’s Repository API. Main benefits they provide over them are:
- Content is available in a single translation, this voids the need for various helper services
- Additional properties otherwise available only through separate entities (like ContentType identifier, FieldType identifier and others)
- Additional properties and methods that enable simple traversal and filtering of the content model (relations, parent, siblings, children)
Note
Note that content traversal that is achievable through the objects is not complete. It aims to cover only the most common use cases. For more complex use cases Query Types should be used.
Note
In Twig templates methods beginning with get
and is
are also available with that prefix
removed. Also, parentheses can be omitted if there are no required arguments.
For example, method field.isEmpty()
is also available as field.empty()
or just
field.empty
, and method content.getLocations()
is available as content.locations()
or just content.locations
.
Content on this page:
Content
¶
The first difference from Repository Content is that it exist it a single translation only, meaning it contains the fields for only one translation. That will always be the translation to be rendered on the siteaccess. You won’t need to choose the field in the correct translation, manually or through some kind of helper service. The Content’s single translation is always the correct one.
Content fields are lazy-loaded, which means they are initially not loaded, but will be transparently loaded at the point you access them. This voids the need to have separate, lightweight version of Content (ContentInfo plays this role in Repository API). It also provides you with some additional properties and methods.
Example usage from Twig:
<h1>{{ content.name }}</h1>
<h2>Parent name: {{ content.mainLocation.parent.content.name }}</h2>
<h3>Number of Locations: {{ content.locations|length }}</h3>
{% for field in content.fields %}
{% if not field.empty %}
{{ ng_render_field(field) }}
{% endif %}
{% endfor %}
Methods¶
hasField
¶
Check if Content has a Field with the given $identifier
.
Parameters | string $identifier |
Returns | bool |
Example in PHP | if ($content->hasField('title')) {
// ...
}
|
Example in Twig | {% if content.hasField('title') %}
...
{% endif %}
|
getField
¶
Get the Field with the given $identifier
.
Note
This method can return null
if Field with the given $identifier
doesn’t exist.
Parameters | string $identifier |
Returns | Field instance or null |
Example in PHP | $field = $content->getField('title');
|
Example in Twig | {{ set field = content.field('title') }}
|
hasFieldById
¶
Check if Content has a Field with the given $id
.
Parameters | int|string $id |
Returns | bool |
Example in PHP | $content->hasFieldById(42);
|
Example in Twig | {{ content.hasFieldById(42) }}
|
getFieldById
¶
Get the Field with the given $id
.
Note
This method can return null
if Field with the given $id
doesn’t exist.
Parameters | string $id |
Returns | Field instance or null |
Example in PHP | $field = $content->getFieldById(42));
|
Example in Twig | {% set field = content.fieldById(42) %}
|
getFieldValue
¶
Get the value of the Field with the given $identifier
.
Note
This method can return null
if Field with the given $identifier
doesn’t exist.
Note
Returned value object depends of the FieldType. Best way to learn about the specific value format is reading the official FieldType reference documentation, or looking directly at code (for example the code of TextLine Value).
Parameters | string $identifier |
Returns | Value instance of the Field or null |
Example in PHP | $value = $content->getFieldValue('title'));
|
Example in Twig | {% set value = content.fieldValue('title') %}
|
getFieldValueById
¶
Get the value of the Field with the given $id
.
Note
This method can return null
if Field with the given $id
doesn’t exist.
Parameters | string $id |
Returns | Value instance of the Field or null |
Example in PHP | $value = $content->getFieldValueById(42));
|
Example in Twig | {% set value = content.fieldValueById(42) %}
|
getLocations
¶
Used to get Content’s Locations, limited by the $limit
. Locations will be sorted their path
string (a string with materialized IDs, e.g. /1/2/45/67/
).
Parameters | int $limit = 25 |
Returns | An array of Content’s Locations |
Sorting method | Location’s path string (e.g. /1/2/45/67/ ) |
Example in PHP | $locations = $content->locations(10));
|
Example in Twig | {% set locations = content.locations %}
|
filterLocations
¶
List a slice of Content’s Locations, by the $maxPerPage
and $currentPage
. Locations will be
sorted their path string (a string with materialized IDs, e.g. /1/2/45/67/
).
Parameters |
|
Returns | Pagerfanta instance with a slice of Content’s Locations |
Sorting method | Location’s path string (e.g. /1/2/45/67/ ) |
Example in PHP | $locations = $content->filterLocations(10, 2));
|
Example in Twig | {% set locations = content.filterLocations(10, 2) %}
|
getFieldRelation
¶
Used to get a single field relation from the Field with the given $identifier
.
Parameters | string $identifier |
Returns | Related Content or null if the relation does not exist |
Example in PHP | $relation = $content->getFieldRelation('author'));
|
Example in Twig | {% set relation = content.fieldRelation('author') %}
|
getFieldRelations
¶
Used to get $limit
field relations from the Field with the given $identifier
. Relations
will be sorted as is defined by the relation field.
Parameters |
|
Returns | An array of related Content items |
Sorting method | Sorted as is defined by the relation Field |
Example in PHP | $relations = $content->getFieldRelations('images', 10));
|
Example in Twig | {% set relations = content.fieldRelation('images') %}
|
filterFieldRelations
¶
Used to filter field relations from the Field with the given $identifier
.
Parameters |
|
Returns | Pagerfanta instance with related Content items |
Example in PHP | $relations = $content->filterFieldRelations(
'related_items',
['images', 'videos'],
10,
2
);
|
Example in Twig | {% set relations = content.fieldRelation(
'related_items'
['images', 'videos']
10,
2
) %}
|
Properties¶
Name | Type | Description |
---|---|---|
$id |
string|int |
ID |
$mainLocationId |
string|int|null |
Optional main Location ID |
$name |
string |
Name |
$languageCode |
string |
Translation language code |
$contentInfo |
ContentInfo | ContentInfo object |
$fields |
Field[] |
An array of Field instances, which can be accessed
in two different ways:
{{ set field = content.fields.title }}
{{ set field = content.fields['title'] }}
|
$mainLocation |
Location | Optional Location object |
$owner |
Content | Optional owner user’s Content object |
ContentInfo
¶
Site ContentInfo
object is similar to the Repository ContentInfo, additionally providing access
to
Properties¶
Name | Type | Description |
---|---|---|
$id |
string|int |
ID of the Content |
$contentTypeId |
string|int |
ID of the ContentType |
$sectionId |
string|int |
ID of the Section |
$currentVersionNo |
int |
Current version number |
$published |
bool |
Indicates that the Content is published |
$ownerId |
string|int |
ID of the owner user Content |
$modificationDate |
\DateTime |
Modification date
|
$publishedDate |
\DateTime |
Publication date |
$alwaysAvailable |
bool |
Indicates that the Content is always available in it’s
main translation
|
$remoteId |
string |
Remote ID of the Content |
$mainLanguageCode |
string |
Main translation language code |
$mainLocationId |
string|int |
ID of the main Location |
$name |
string |
Content’s name |
$languageCode |
string |
Language code of Content’s translation |
$contentTypeIdentifier |
string |
Identifier of the Content Type |
$contentTypeName |
string |
Name of the Content Type |
$contentTypeDescription |
string |
Description of the Content Type |
$mainLocation |
Location | Content’s main Location object |
$content |
Content | Content object |
Field
¶
Site Field
object is similar to the Repository Field, additionally providing access to the
field’s Content and properties that are otherwise available only through the corresponding
FieldDefinition object: name, description and FieldType identifier.
Properties¶
Name | Type | Description |
---|---|---|
$id |
string|int |
ID of the Field |
$fieldDefIdentifier |
string |
Identifier (FieldDefinition identifier, e.g. title ) |
$value |
Value object | Value object |
$languageCode |
string |
Translation language code |
$fieldTypeIdentifier |
string |
FieldType identifier (e.g. ezstring ) |
$name |
string |
ID of the Content |
$description |
string |
ID of the Content |
$content |
Content | ID of the Content |
Location
¶
Site Location
object is similar to the Repository Location, additionally providing methods and
properties that enable simple traversal and filtering of the Location tree (siblings, children,
parent, ancestors etc).
Methods¶
getChildren
¶
List children Locations.
Children will be sorted as is defined by their parent Location, which is the Location the method is
called on. The single optional parameter of this method is $limit
, which limits the number of
children returned and defaults to 25
.
Parameters | string $limit = 25 |
Returns | An array of first $limit children Locations |
Sorting method | As is defined by the Location |
Example in PHP | $children = $location->getChildren(10));
|
Example in Twig | {% set children = location.children(10) %}
|
filterChildren
¶
Filter and paginate children Locations.
This enables filtering of the children by their ContentType with $contentTypeIdentifiers
parameter and pagination using $maxPerPage
and $currentPage
parameters. The method returns
a Pagerfanta instance.
Parameters |
|
Returns | Pagerfanta instance with a slice of children Locations |
Sorting method | As is defined by the Location |
Example in PHP | $children = $content->filterChildren(['articles'], 10, 2);
|
Example in Twig | {% set relation = content.filterChildren(
['articles'],
10,
2
) %}
|
getSiblings
¶
List sibling Locations.
Siblings will be sorted as is defined by their parent Location, which is the parent Location of the
Location the method is called on. The single optional parameter of this method is $limit
, which
limits the number of siblings returned and defaults to 25
.
Parameters | string $limit = 25 |
Returns | An array of first $limit sibling Locations |
Sorting method | As is defined by the parent Location |
Example in PHP | $siblings = $location->getSiblings(10);
|
Example in Twig | {% set siblings = location.siblings(10) %}
|
filterSiblings
¶
Filter and paginate sibling Locations.
This enables filtering of the siblings by their ContentType with $contentTypeIdentifiers
parameter and pagination using $maxPerPage
and $currentPage
parameters. The method returns
a Pagerfanta instance.
Parameters |
|
Returns | Pagerfanta instance with a slice of filtered sibling Locations |
Sorting method | As is defined by the parent Location |
Example in PHP | $siblings = $location->filterSiblings(['articles'], 10, 2);
|
Example in Twig | {% set siblings = location.filterSiblings(
['articles'],
10,
2
) %}
|
Properties¶
Name | Type | Description |
---|---|---|
$id |
string|int |
ID of the Location |
$status |
int |
Constant defining status (published or draft) |
$priority |
int |
Priority |
$hidden |
bool |
Own hidden state |
$invisible |
bool |
Invisibility state (hidden by itself or by an ancestor) |
$remoteId |
string |
Remote ID |
$parentLocationId |
string|int |
Parent Location ID |
$pathString |
string |
Path with materialized IDs (/1/2/42/56/ ) |
$path |
int[] |
An array with materialized IDs ([1, 2, 42, 56] ) |
$depth |
int |
Depth in the Location tree |
$sortField |
int |
Constant defining field for sorting children Locations |
$sortOrder |
int |
Constant defining sort order for children Locations |
$contentId |
string|int |
ID of the Content |
$contentInfo |
ContentInfo | ContentInfo object |
$parent |
Location | Parent Location object (lazy loaded) |
$content |
Content | Content object (lazy loaded) |