ibexa

Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.

list

Summary

Fetches the children of a node or a collection of nodes.

Usage

fetch( 'content', 'list',
 hash( 'parent_node_id',            parent_node_id,
     [ 'sort_by',                   sort_by,                   ]
     [ 'offset',                    offset,                    ]
     [ 'limit',                     limit,                     ]
     [ 'attribute_filter',          attribute_filter,          ]
     [ 'extended_attribute_filter', extended_attribute_filter, ]
     [ 'class_filter_type',         class_filter_type,         ]
     [ 'class_filter_array',        class_filter_array,        ]
     [ 'only_translated',           only_translated,           ]
     [ 'language',                  language,                  ]
     [ 'main_node_only',            main_node_only,            ]
     [ 'as_object',                 as_object,                 ]
     [ 'depth',                     depth,                     ]
     [ 'limitation',                limitation                 ]
     [ 'ignore_visibility',         ignore_visibility          ] ) )

Parameters

NameTypeDescriptionRequired
parent_node_id mixed The ID number(s) of the parent node(s). Yes.
sort_by array The sorting mechanism that should be used. No.
offset integer The offset to start at. No.
limit integer The number of nodes that should be fetched. No.
attribute_filter mixed The attribute level filter logic. No.
extended_attribute_filter mixed The extended attribute level filter logic. No.
class_filter_type string The type of class filtering (include/exclude). No.
class_filter_array array The classes that should be filtered. No.
group_by array DEPRECATED No.
only_translated boolean Translation filtering (on/off). No.
language string The translations that should be fetched. No.
main_node_only boolean Type of nodes that should be fetched (all or main nodes only). No.
as_object boolean If TRUE (or omitted), an array of "ezcontentobjecttreenode" objects will be fetched. Otherwise, an array of arrays will be returned. No.
depth integer The maximum level of depth that should be explored (1 by default). No.
limitation array Limitation array (emtpy array = access override). No.
ignore_visibility boolean Makes it possible to fetch hidden nodes. No.

Returns

An array of ezcontentobjecttreenode objects or FALSE.

Description

This function fetches the children of a single node or a collection of nodes. The parent node(s) must be specified using the "parent_node_id" parameter. This parameter can either be the ID number of a single node or an array containing several node ID numbers. The function will fetch the nodes that are directly under the specified parent node(s). The collection is returned as an array of ezcontentobjecttreenode objects. If no nodes are found or if an error occurs, the function will return FALSE. The optional "group_by" parameter (grouping on a date/time basis) is deprecated since this functionality is not supported by Oracle and PostgreSQL.

Sorting

The "sort_by" parameter makes it possible to sort the result in different ways. This parameter must be provided as an array. The first element of the array must be the desired sorting method. The second element of the array must be the sorting direction, it can be either true() or false() - ascending or descending. The following table shows the sorting methods that can be used.

Sorting method

Description

attribute

The nodes are sorted according to the value of a specific attribute.

class_identifier

The nodes are sorted by the class identifiers of the objects.

class_name

The nodes are sorted by the class names of the objects.

depth

The nodes are sorted by their depth in the content tree.

modified

The nodes are sorted by the modification time of the objects.

name

The nodes are sorted by the names of the objects.

path

The nodes are sorted by their node ID path strings (/1/2/43/56).

path_string

The nodes are sorted by their virtual path strings (/company/about).

priority

The nodes are sorted by their priority.

published

The nodes are sorted by the creation time of the objects.

section

The nodes are sorted by the section IDs of the objects.

It is possible to combine different sorting methods. For example, it is possible to sort the nodes alphabetically and by their publish date/time at the same time.

Sorting on the attribute level is supported for the following datatypes:

  • Checkbox
  • Date
  • Date and time
  • E-mail
  • Integer
  • Selection (will not work when used as multiple selector)
  • Text line
  • Time

The syntax for doing attribute level sorting is almost the same as for normal sorting. The only difference is that the ID number or the identifier of the target attribute must be specified. If the identifier is used then both the identifier of the class and the attribute must be specified (separated by a slash, like this: "my_class/my_attribute"). Attribute sorting can only be used if the returned collection contains the same type of nodes.

Fetching subsets

By making use of the "offset" and "limit" parameters, it is possible to fetch only a subset of the collection that would have been returned if these parameters were omitted. While the "offset" parameter defines the start of the subset, the "limit" parameter defines the length (number of elements/nodes) of the subset. These parameters are processed at the final stage. In other words, it is possible to do advanced sorting/filtering and grab only a specific chunk of from the sorted/filtered/etc. collection.

Class filtering

The class filter mechanism is controlled by the "class_filter_type" and "class_filter_array" parameters. The "class_filter_type" parameter tells eZ Publish to include or exclude specific node types. This parameter must be either "include" or "exclude". It is not possible to include one set and to exclude another at the same time. The value of the "class_filter_array" parameter specifies the type of nodes that should be included or excluded. This parameter must be an array of class ID numbers or class identifier strings.

Attribute filtering

The attribute filter mechanism is controlled by the "attribute_filter" parameter. Attribute filtering makes it possible to fetch a set of nodes where an attribute (or several attributes) contains some specific data. Filtering on the attribute level is supported for the following datatypes:

  • Checkbox
  • Date
  • Date and time
  • E-mail
  • Integer
  • Object relation
  • Selection (will not work when used as multiple selector)
  • Text line
  • Time

The "attribute_filter" parameter must be an array. The first element may be set to either "and" or "or" - this controls how the matching specified in the upcoming elements should be carried out. If this parameter is omitted, the system will default to "and". The rest of the elements are arrays, each array specifies a match. The elements in this array are:

  1. Attribute ID
  2. Match type
  3. Match value

The attribute ID can be specified either as the ID number of the attribute or as a string that contains the identifier of the class and the identifier of the attribute separated by a slash. (Note that it is also possible to specify one of the pre-defined strings in order to do filtering on a non-attribute.) The ID number of the attribute or the identifier of the class and the attribute can be found when viewing/editing content classes.

The match type tells how eZ Publish should try to match the values. The match value is the data that should be matched. The following match types can be used:

Type

Description

=

Equal

!=

Not equal

<

Less than

>

Greater than

<=

Less than or equal to

>=

Greater than or equal to

in

Matches one of the array values

not_in

Does not match any of the array values

between

Is a part of the range determined by the start and end values

not_between

Is outside the range determined by the start and end values

like

Matches the wildcard string (the wildcard character is '*')

It is not possible to filter on attributes of different classes, for example it is not possible to filter on both "article/show_comments" and "folder/show_comments" in the same filter.

Filtering on a non-attribute

Instead of the class/attribute syntax, you can use "published" and "priority" as "AttributeID". It is also possible to use "owner" as "AttributeID" which refers to the owner's identifier of the content object. This can for instance be used to find all objects of a given user.

There are also some other pre-defined strings that can be used as "AttributeID" (refer to the following table). When one of these strings is used as "AttributeID", filtering is based on template object attributes (not on content object attributes). This means that if you use f.ex. "priority" as "AttributeID", the system will check the value of the "priority" attribute of the "ezcontentobjecttreenode" objects that represent information about content nodes.

The following table describes the pre-defined strings and corresponding attributes.

Name

Description

class_identifier

The identifier of the class which the object encapsulated by the node is an instance of.

class_name

The name of the class which the object encapsulated by the node is an instance of.

depth

The depth of the node within the content node tree.

modified

A UNIX timestamp pinpointing the exact date/time when the object encapsulated by the node was last modified (the "modified" attribute of the corresponding "ezcontentobject" object).

modified_subnode

A UNIX timestamp pinpointing the exact time a sub node was changed.

name

The name of the object the node encapsulates.

owner

The ID number of the object representing the user who initially created the object (the "owner_id" attribute of the corresponding "ezcontentobject" object).

path

The node's path string (the "path_string" attribute).

priority

The node's priority.

published

A UNIX timestamp pinpointing the exact date/time when the object was published for the first time (the "published" attribute of the corresponding "ezcontentobject" object).

section

The ID number of the section that the object belongs to (the "section_id" attribute of the corresponding "ezcontentobject" object).

Extended attribute filtering

The "extended_attribute_filter" parameter can be used to do advanced attribute filtering. It is for expert/experienced users. This mechanism makes it possible to introduce additional SQL conditions within the fetch. It allows filtering based on values in custom tables and/or special filtering within the "ezcontentobject_attribute" table.

The mechanism must be configured using a configuration override for "extendedattributefilter.ini". This file allows the site administrator to set up different custom filters. Each filter must be a named collection of configuration settings. The name of a filter is the name of the configuration block under which the filter's settings are defined. The following text shows an example that demonstrates the setup of a filter called "MyFilter".

#The name of the filter.
[MyFilter]
 
#The name of the extension where the filtering code is defined.
ExtensionName=myextension
 
#The name of the filter class.
ClassName=eZMyExtendedFilter
 
#The name of the method which is called to generate the SQL parts.
MethodName=createSqlParts
 
#The file which should be included (extension/myextension will automatically be prepended).
FileName=classes/ezmyextendedfilter.php

The function defined by the "MethodName" setting must return an associative array containing two strings:

array( 'tables' => '...', 'joins' => '...' );

The contents of "tables" must start with a comma. The rest of the string should contain a comma separated list of other tables that should be included in the query. The contents of "joins" will be added inside the "WHERE" section of the query. This string must start with a space and contain an "AND" and an additional space at the end.

The example below shows a solution that filters the content based on values within an additional/custom table. This table is joined with the node table (by object ID and object version). The additional/custom table would most likely be maintained by a special/custom datatype.

class eZMyExtendedFilter
{
    /*!
     Constructor
    */
    function eZMyExtendedFilter()
    {
        // Empty...
    }
 
    function createSqlParts( $params )
    {
        $sqlTables= ', ezmyfiltertable ';
 
        $sqlJoins = ' ezcontentobject_tree.contentobject_id = ezmyfiltertable.contentobject_id AND ezcontentobject_tree.contentobject_version = ezmyfiltertable.version AND ';
 
        if ( isset( $params['value1'] ) )
        {
             $value1 = $params['value1'];
        }
        else
        {
             $value1 = "10";
        }
        if ( isset( $params['value2'] ) )
        {
             $value2 = $params['value2'];
        }
        else
        {
             $value2 = "10";
        }
 
        $sqlCondArray = array();
 
        $sqlCondArray[] = 'ezmyfiltertable.my_cond1 = ' . $value1;
 
        $sqlCondArray[] = 'ezmyfiltertable.my_cond1 = ' . $value2;
 
        $sqlCond = implode( ' or ', $sqlCondArray );
 
        $sqlCond = ' ( ' . $sqlCond . ' ) AND ' . $sqlJoins . ' ';
 
        return array( 'tables' => $sqlTables, 'joins'  => $sqlCond );
 
    }
}

The following template code shows how the extended attribute filter (see the PHP code above) can be used within a fetch.

{fetch( 'content', 'list',
        hash( 'parent_node_id', 2,
              'sort_by', array( 'priority', false() ),
              'limit', 15,
              'extended_attribute_filter',
                            hash( 'id', 'MyFilter',
                                          'params', hash( 'value1', 15,
                                                        'value2', 30 ) ),
              'depth', 10,
              'main_node_only', true() ) )}

There is an additional example at the bottom of this page: Example 19.

Fetching main nodes only

The "main_node_only" parameter can be used to tell eZ Publish that it should only fetch main nodes (nodes that are main locations for content objects). This parameter is optional and can be set to either true() or false(). When set to true(), the fetch function will only return main nodes. This functionality can be used to avoid duplicates (different nodes but same objects) in the result.

Fetching translated objects only

In some multi-language scenarios, not all objects are translated into other/all languages. When the "only_translated" parameter is set to "true()" the system will only fetch objects that have been translated into the language used by the siteaccess (the current language). The "language" parameter can be used to control which translations that should be fetched. The value of this parameter must be a valid locale string, for example "ger-DE".

Access override

The "limitation" parameter makes it possible to instruct the system to use an alternate set of access limitations instead of the ones that belong to the current user. This is typically useful when there is a need to fetch nodes that the current user does not have access to. All permission checking can be skipped by providing an empty array. It is also possible to provide arrays that dictate the access limitations of other users and/or virtual sets of limitations. The array follows an internal structure that will be documented in the future.

Visibility override

The "ignore_visibility" parameter makes it possible to fetch hidden nodes. It can be set to either "true()" or "false()". If set to "true()", the fetch will ignore the visibility flags of nodes and thus it will return all nodes regardless of their visibility status. In other words, this parameter overrides the "ShowHiddenNodes" configuration directive for a specific fetch operation in a template.

Examples

Example 1

{def $nodes=fetch( 'content', 'list',
        hash( 'parent_node_id', 42,
              'depth', 3 ) )}
 
{foreach $nodes as $node}
    {$node.name|wash} <br />
{/foreach}

This example demonstrates how to fetch nodes which are until the third level under the parent node number 42. Outputs the names of all these nodes.

Example 2

{fetch( 'content', 'list',
        hash( 'parent_node_id', 42,
              'sort_by',        array( 'published', false() ) ) )}

This example demonstrates how to fetch all nodes that are the children of node number 42. The nodes are sorted by the time they were created; the most recently created node will be the first element in the collection.

Example 3

{fetch( 'content', 'list',
        hash( 'parent_node_id', 42,
              'sort_by',        array( array( 'name',      false() ),
                                      array( 'published', false() ) ) )}

This example demonstrates how to combine different sorting methods. The fetch function will fetch the child nodes of node number 42. The fetched nodes will be sorted by their name and the time they were created.

Example 4

{fetch( 'content', 'list',
        hash( 'parent_node_id', 42,
              'sort_by',        array( 'attribute',
                                      false(),
                                      107 ) ) )}

This example demonstrates attribute sorting by using the ID number of the attribute.

Example 5

{fetch( 'content', 'list',
        hash( 'parent_node_id', 42,
              'sort_by',        array( 'attribute',
                                      false(),
                                      'person/last_name' ) ) )}

This example demonstrates attribute sorting by using the string notation to pinpoint the identifier of the class and the attribute.

Example 6

{fetch( 'content', 'list',
        hash( 'parent_node_id',     42,
              'class_filter_type',  'include',
              'class_filter_array', array( '13' ) ) )}

This example demonstrates how to use class filtering to fetch only nodes that reference objects that are instances of class number 13.

Example 7

{fetch( 'content', 'list',
        hash( 'parent_node_id',     42,
              'class_filter_type',  'include',
              'class_filter_array', array( 'folder' ) ) )}

This example demonstrates how to use class filtering to fetch only nodes that reference folder objects.

Example 8

{fetch( 'content', 'list',
        hash( 'parent_node_id',     42,
              'class_filter_type',  'exclude',
              'class_filter_array', array( 'article',
                                          'comment' ) ) )}

This example demonstrates how to use class filtering to exclude articles and comments from a fetch.

Example 9

{fetch( 'content', 'list',
        hash( 'parent_node_id',   42,
              'attribute_filter', array( 'or',
                                        array( 152, '=', 'abc' ),
                                        array( 153, '=', '42' ) ) ) )}

This example demonstrates how to do attribute filtering. Only nodes that have attributes number 152 and 153 set to "abc" and 42 respectively will be included in the result.

Example 10

{fetch( 'content',
        'list',
        hash( 'parent_node_id',   42,
              'attribute_filter', array( array( 'article/title',
                                        'like',
                                        '*story*' ) ) ) )}

This example demonstrates how to do attribute filtering. Instead of specifying the ID number of the attribute (as in the previous example), the identifier of the class and the attribute is used. Only article nodes that contain the text "story" in their title attribute will be included in the result.

Example 11

{fetch( 'content',
        'list',
        hash( 'parent_node_id',   42,
              'attribute_filter', array( array( 'article/image',
                                        '=',
                                        87 ) ) ) )}

This example demonstrates how to do attribute filtering using an attribute of the "Object relation" datatype. Only article nodes that store relation to the specified content object (object ID = 87) in their "image" attribute will be included in the result.

Example 12

{fetch( 'content',
        'list',
        hash( 'parent_node_id',   42,
              'attribute_filter', array( array( 'review/rating',
                                        'between',
                                        array( 0, 2 ) ) ) ) )}

This example demonstrates how to do attribute filtering using an attribute of the "Selection" datatype. Only review nodes that contain "Very good", "Good" or "Ok" (options 0, 1 or 2) in their "rating" attribute will be included in the result.

Example 13

{fetch( 'content',
        'list',
        hash( 'parent_node_id',   42,
              'attribute_filter', array( array( 'bug/priority',
                                        'in',
                                        array( 1, 4 ) ) ) ) )}

Fetches bugs with priority 1 and 4 (i.e. bug nodes that have their priority attribute set to 1 or 4).

Example 14

{fetch( 'content',
        'list',
        hash( 'parent_node_id',   42,
              'attribute_filter', array( array( 'bug/priority',
                                        'between',
                                        array( 2, 4 ) ) ) ) )}

Fetches bugs with priority 2, 3 and 4 (i.e. bug nodes that have their priority attribute value between 2 and 4).

Example 15

{fetch( 'content', 'list',
        hash( 'parent_node_id',   42,
              'attribute_filter', array( 'and',
                                        array( 'priority', '>', '20' ),
                                        array( 'article/title', '=', 'abc' ) ) ) )}

This example demonstrates how to do filtering on a non-attribute. Instead of specifying the identifier of the class and the attribute, "priority" is used. Only article nodes that have their title attribute set to "abc" and have a priority greater than 20 will be included in the result.

Example 16

{def $nodes=fetch( 'content', 'list',
        hash( 'parent_node_id', 42,
              'attribute_filter', array( 'and',
                             array( 'owner',
                              '=',
                             $current_user.contentobject_id ),
                             array( 'class_identifier', '=', 'folder' ) ),
              'depth', 3 ) )}
 
{foreach $nodes as $node}
    {$node.name|wash}<br />
{/foreach}
 
{undef $nodes}

Fetches folder nodes which are until the third level under the parent node number 42 and are created by the current user.

Example 17

{fetch( 'content', 'list',
        hash( 'parent_node_id',  2,
              'only_translated', true() ) )}

This example demonstrates how to fetch only nodes that reference objects that have been translated into the current language (the language that the siteaccess is using).

Example 18

{fetch( 'content', 'list',
        hash( 'parent_node_id',  2,
              'limit',           3,
              'only_translated', true(),
              'language',        'ger-DE' ) )}

This example demonstrates another way to fetch translated objects. The fetch will return nodes that reference objects which have been translated into the German language.

Example 19

{fetch( 'content', 'list',
        hash( 'parent_node_id', 2,
              'sort_by', array( 'priority', false() ),
              'limit', 15,
              'extended_attribute_filter',
                            hash( 'id', 'MyFilter',
                            'params', hash( 'value1', 'text1',
                                          'value2', 'text2' ) ) ) )}

This example demonstrates how the extended attribute filter can be used. The template code above will fetch objects that match the following condition: any object using the ezstring datatype containing either "text1" or "text2". The necessary PHP implementation is shown in the example below.

class eZMyExtendedFilter
{
    /*!
     Constructor
    */
    function eZMyExtendedFilter()
    {
        // Empty...
    }
 
    function createSqlParts( $params )
    {
        $sqlTables= ', ezcontentobject_attribute as myfilter_alias ';
 
        $sqlJoins = ' ezcontentobject_tree.contentobject_id = myfilter_alias.contentobject_id AND ezcontentobject_tree.contentobject_version = myfilter_alias.version AND myfilter_alias.data_type_string = "ezstring"  AND';
 
        if ( isset( $params['value1'] ) )
        {
             $value1 = $params['value1'];
        }
        else
        {
             $value1 = 'fooo';
        }
        if ( isset( $params['value2'] ) )
        {
             $value2 = $params['value2'];
        }
        else
        {
             $value2 = 'boooo';
        }
 
        $sqlCondArray = array();
 
        $sqlCondArray[] = 'myfilter_alias.data_text = "' . $value1 . '"';
        $sqlCondArray[] = 'myfilter_alias.data_text = "' . $value2 . '"';
 
        $sqlCond = implode( ' or ', $sqlCondArray );
 
        $sqlCond = ' ( ' . $sqlCond . ' ) AND ' . $sqlJoins . ' ';
 
        return array( 'tables' => $sqlTables, 'joins' => $sqlCond );
 
    }
}

Example 20

{fetch( 'content', 'list', hash( 'parent_node_id', 2,
                                'ignore_visibility', true() ) )}

This example demonstrates how to fetch nodes regardless of their visibility status. The operation above will return both visible and hidden nodes that are directly below node #2.

Example 21

{def $nodes=fetch( 'content', 'list', hash( 'parent_node_id', 2,
                                'as_object', false() ) )}
 
The result is an array of arrays. The first inner array reveals information about the node "{$nodes[0].name|wash}": <br /> {$nodes[0]|attribute( show, 1 )}

This example demonstrates the behavior when the "as_object" parameter is set to FALSE. The following output will be produced:

The result is an array of arrays. The first inner array reveals information about the node "Multiprice products":

Attribute

Type

Value

contentclass_id

string

1

current_version

string

1

id

string

61

initial_language_id

string

2

is_published

string

 

language_mask

string

3

modified

string

1161682117

name

string

'Multiprice products'

owner_id

string

14

published

string

1161682117

remote_id

string

'f3f9d3443e61498e01523e3016ca136b'

section_id

string

1

status

string

1

contentobject_id

string

61

contentobject_is_published

string

1

contentobject_version

string

1

depth

string

2

is_hidden

string

 

is_invisible

string

 

main_node_id

string

63

modified_subnode

string

1161682290

node_id

string

63

parent_node_id

string

2

path_identification_string

string

'multiprice_products'

path_string

string

'/1/2/63/'

priority

string

 

sort_field

string

2

sort_order

string

 

class_name

string

'Folder'

class_identifier

string

'folder'

real_translation

string

'eng-GB'

Balazs Halasy (06/02/2004 12:07 pm)

Svitlana Shatokhina (16/04/2007 7:53 am)

Svitlana Shatokhina, Balazs Halasy


Comments

  • like filter

    like is case sensitive when using postgresql

    would be nice to have ilike for case insensitive like.
  • limitation

    When 'limitation' is explained, it is refered to "limitations" witch is wrong.
  • Syntax for sorting by multiple attributes should be specified

    Example 3 should be complemented by an outline of the syntax for sorting by multiple attributes. For instance, replace the sentence

    "It is possible to combine different sorting methods. For example, it is possible to sort the nodes alphabetically and by their publish date/time at the same time."

    with

    "To combine several sorting methods, put the sort arrays in an outer array. See Example 3."
  • Sort by price datatype seems works as well

    Sorting on attribute level seems to work for the price datatype too. I assume that it works for all datatypes that have some content in the sort key string, so generally just try it out.
  • Multiple attribute sorting ?

    Seems not possible.

    Is it ?
  • Undocumented feature

    There is a undocumented parameter named 'depth_operator'

    it works like that :
    fetch(content, list, hash('parent_node_id', [node_id],
    'depth_operator', [operator like '<', '=', '>', ....]
    'depth', [depth] ) )

    You will get all the node from the specified depth params.
    • Re: Undocumented feature

      > There is a undocumented parameter named 'depth_operator'

      Thanks for the tip.

      > 'depth_operator', [operator like '<', '=', '>', ....]

      In 3.9.1 you should replace
      '<' with 'le'
      '>' with 'gt'
      '=' with 'eq'