ez.no / exponential / documentation / reference / data fetching / content / list
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, ]
[ 'group_by', group_by, ]
[ 'only_translated', only_translated, ]
[ 'language', language, ]
[ 'main_node_only', main_node_only, ]
[ 'as_object', as_object ] ) )
| Name | Type | Description | Required |
|---|---|---|---|
| parent_node_id | integer or array | ID number of the parent node (or array of). | Yes. |
| sort_by | array | The type of sorting mechanism(s) to use. | No. |
| offset | integer | Offset to start at. | No. |
| limit | integer | Max number of nodes to fetch. | No. |
| attribute_filter | mixed | Filter logic for attribute level filtering. | No. |
| extended_attribute_filter | mixed | Filter logic for extended attribute level filtering. | No. |
| class_filter_type | string | Type of class filtering. | No. |
| class_filter_array | array | Classes to include/exclude. | No. |
| group_by | array | Grouping on a date/time basis. | No. |
| only_translated | boolean | Fetch only translated objects. | No. |
| language | string | Language to use for translated objects. | No. |
| main_node_only | boolean | Fetch all or main nodes only. | No |
| as_object | boolean | Return result as object or array. | No |
Collection of nodes either as array or object.
This fetch function gets and returns a collection of nodes that are the children of the node(s) which is(are) specified using the "parent_node_id" parameter. Multiple parent nodes can be specified as an array. Only nodes that are directly under this(these) node(s) will be fetched. By default, the collection is returned as an array of nodes (ezcontentobjecttreenodes). It is possible to change the return type to a single object by setting the "as_object" parameter to true(). The most simple fetch carried out by this function is fetching all the child nodes of a specific node. This is demonstrated in example 1. However, this function can be used to do a lot more than just that. By using a combination of the optional parameters, it is possible to do sorting, filtering, limitation, sub-selection, etc. These techniques are described below.
Sorting
The "sort_by" parameter makes it possible to sort a collection of nodes by:
The "sort_by" parameter must be an array. The first element of the array is the type of sort. This must be one of the strings that are encapsulated in parenthesis in the list above (name, published, depth, etc.). The second element of the array is the way the sorting is to be done. This element must be set to either true() or false(). True means ascending, false means descending. Example 2 demonstrates the basic use of sorting.
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. Example 3 demonstrates how to do this. Note the array-in-an-array technique that is used to combine multiple sorting methods.
A collection of nodes can be sorted on the attribute level. This means that it is possible to sort a bunch of nodes (of the same type) by one of the attributes; for example sort nodes that contain information about people on the attribute that contains the nickname. The following datatypes support sorting on attribute level:
The syntax for doing attribute level sorting is almost the same as for normal sorting. The only difference is that the ID of the attribute that sorting should be done by must be specified. This 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 frontslash (/). The ID number of the attribute or the identifier of the class and the attribute can be found when viewing/editing content classes. Examples 4 and 5 demonstrate the different attribute sorting methods.
Note that it is not possible to do attribute sorting for a collection of nodes that are of different types since each attribute is a unique entity. Attribute sorting was added in version 3.2.
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. The offset parameter defines the start of the subset, the limit parameter defines the length of the subset. The offset and limit parameters are interpreted in the last stage. This means that it is possible to do advanced sorting/filtering and grab only a specific chunk of from the sorted/filtered/etc. collection. For example, these parameters are used by the navigator mechanism in order to show only a subset of the nodes that were fetched. The parameters can be used together or individually. By default, the offset it zero and the limit is unlimited.
Filtering
The collection of nodes that are to be returned by the fetch function can be filtered in different ways. Currently it is possible to do filtering on two levels:
Class level filtering makes it possible to include or exclude different types of nodes (nodes that contain objects of different classes) in the result that is being returned. For example, we can fetch only the articles from within a folder that contains subfolders, articles and comments; or we can fetch everything but comments. Attribute level filtering makes it possible to filter the result based on the values in the object attributes.
Class filtering
The class filter mechanism is controlled by the "class_filter_type" and "class_filter_array" parameters. The "class_filter_type" parameter tells Exponential if we want to include or exclude specific node types. This parameter must be set to a string that reads either 'include' or 'exclude'. Note that it is not possible to include one set and to exclude another at the same time. The value of the "class_filter_array" parameter reveals the type of nodes that should be included or excluded. This parameter must be an array of class ID numbers or class identifier strings. Class filtering is demonstrated in examples 6, 7 and 8.
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. Attribute filtering is supported by the following datatypes:
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 desired match. The elements in this array are:
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 frontslash (/). 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 Exponential should try to match the values. The match value is the data that should be matched. The following match types can be used:
=���-�equal !=��-�not�equal�(requires�3.2-3,�3.3�or�higher) <���-�less�than >���-�greater�than <=��-�less�than�or�equal�to >=��-�greater�than�or�equal�to
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".
Please refer to examples 9, 10 and 11 for a demonstration of attribute filtering.
Attribute filtering was added in version 3.2.
Extended attribute filtering
The "extended_attribute_filter" parameter can be used to do advanced attribute filtering. This parameter is still under construction, it will be documented in the near future. The extended attribute filter mechanism was added in version 3.3 and can only be used with the list fetch function.
Fetching main nodes only
The content structure of Exponential makes it possible to publish the same content in different locations within the content node tree. Actual content is placed in the objects. The nodes that make up the content node tree point to the objects. An object can be pointed to by several nodes, resulting in that the object appears at several different locations within the content tree. One of the nodes is the actual main location for the object within the tree. Although an object may be pointed to by several nodes, it can only have one main node.
The "main_node_only" parameter can be used to tell Exponential 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 only main nodes. This functionality can be used to avoid duplicate fetching of the same content.
Fetching translated objects only
All objects have a default translation. A multilingual site typically has translations for all objects but occasionally only important objects such as news items are translated into all languages. As of version 3.5.1 it is possible to fetch only objects that have been translated into the current language.
The 'only_translated' parameter switches on this functionality if its value is set to 'true()'.
If the 'language' parameter is specified it is possible to define which language to return. If it is not set the current language is used instead. The value for the language parameter must be a valid locale string known to your system, for example 'ger-DE', 'fre-FR' and so on.
Example 1
This example demonstrates the most basic list-fetch possible. It simply fetches all the child nodes of a specific node (in this case node number 42). The array of nodes returned from the fetch function is assigned to a variable called "nodes". The section function is used to loop through the array in order to display the name of each and every node that was returned by the fetch.
{*�Fetch�all�the�child�nodes�of�node�42.�*} {let�nodes=fetch(�'content',�'list',�hash(�'parent_node_id',�42�)�}<P> {*�Loop�through�the�children,�display�node�names.�*} {section�loop=$nodes} ����{$item.name}<br�/> {/section}<P>{/let}
Example 2
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 published; the most recent node will be the first element in the collection.
{fetch(�'content',� ��������'list',� ��������hash(�'parent_node_id',�42, ��������������'sort_by',��������array(�'published',�false()�)�)�)}
Example 3
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 published.
{fetch(�'content',� ��������'list',� ��������hash(�'parent_node_id',�42, ��������������sort_by,���������array(�array(�name,������false()�), �������������������������������array(�published,�false()�)�)�)}
Example 4
This example demonstrates attribute sorting by using the ID number of the attribute.
{fetch(�'content',�'list',�hash(�'parent_node_id',�42, ���������������������������������'sort_by',��������array(�'attribute',� ����������������������������������������������������������false(),� ����������������������������������������������������������107�)�)�)}
Example 5
This example demonstrates attribute sorting by using the string notation to pinpoint the identifier of the class and the attribute.
{fetch(�'content',�'list',�hash(�'parent_node_id',�42, ���������������������������������'sort_by',��������array(�'attribute',� ����������������������������������������������������������false(),� ����������������������������������������������������������'person/last_name'�)�)�)}
Example 6
This example demonstrates how to use class filtering to fetch nodes that point to objects which are instances of class number 1 (the folder class). In other words: only folders will be fetched.
{fetch(�'content',� ��������'list',� ��������hash(�'parent_node_id',�����42, ��������������'class_filter_type',��'include', ��������������'class_filter_array',�array(�1�)�)�)}
Example 7
This example demonstrates how to use class filtering to only fetch nodes that are articles. Instead of specifying the ID number of the class (as in the previous example), the identifer of the class is used.
{fetch(�'content',� ��������'list',� ��������hash(�'parent_node_id',�����42, ��������������'class_filter_type',��'include', ��������������'class_filter_array',�array(�'article'�)�)�)}
Example 8
This example demonstrates how to use class filtering to exclude articles and comments from a fetch operation.
{fetch(�'content',� ��������'list',� ��������hash(�'parent_node_id',�����42, ��������������'class_filter_type',��'exclude', ��������������'class_filter_array',�array(�'article',�'comment'�)�)�)}
Example 9
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.
{fetch(�'content',� ��������'list',� ��������hash(�'parent_node_id',���42, ��������������'attribute_filter',�array(�'or', �����������������������������������������array(�152,�'=',�'abc'�), �����������������������������������������array(�153,�'=',�'42'�)�)�)�)}
Example 10
This example demonstrates how to do attribute filtering. Instead of specifying the ID number of the attribute (as in the previous example), the identifer of the class and the attribute is used. Only article-nodes that have their title attribute set to "abc" will be included in the result.
fetch(�'content',� �������'list',� �������hash(�'parent_node_id',���42,� �������������'attribute_filter',�array(�array(�'article/title',� �����������������������������������������������'=',� �����������������������������������������������'abc'�)�)�)�)}
Example 11
In addition to example 10, this example demonstrates how to do filter on a non-attribute too. Instead of specifying the identifer of the class and the attribute, we use "priority" here. Only article-nodes that have their title attribute set to "abc" and are have a priority greater than 20 will be included in the result.
fetch(�'content',� �������'list',� �������hash(�'parent_node_id',���42,� �������������'attribute_filter',�array(�'and', ����������������������������������������array(�'priority',�'</font></font></font>>',�20'�),� ����������������������������������������array(�'article/title',�'=',�'abc'�)�)�)�)}
Example 12
This example demonstrates how to fetch only translated objects. This simple fetch will examine all objects beneath the root node, 2, and return up to 3 objects which have been translated.
Example 13
This example demonstrates another way to fetch translated objects. This simple fetch will examine all objects beneath the root node, 2, and return up to 3 objects which have been translated into the German language.
Log in or create a user account to comment.
Comments