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

Name	Type	Description	Required
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.
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.
as_object	boolean	If TRUE (or omitted), an array of "ezcontentobjecttreenode" objects will be fetched. Otherwise, an array of arrays will be returned.	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. 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. But instead of the class/attribute syntax, you can also 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.

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(
                                  array( 'owner',
                                   '=',
                                  $current_user.contentobject_id ) ) ) )}
 
{foreach $nodes as $node}
    {$node.name|wash}<br />
{/foreach}
 
{undef $nodes}

This example demonstrates how to do filtering on a non-attribute. Instead of specifying the identifier of the class and the attribute, "owner" is used. Only the nodes/objects that are created by the current user will be included in the result.

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.

---