Summary

Usage

fetch( 'content', 'related_objects',
        hash( 'object_id',            object_id,
            [ 'attribute_identifier', attribute_identifier, ]
            [ 'all_relations',        boolean,              ]
            [ 'group_by_attribute',   boolean,              ]
            [ 'sort_by',              sort_by               ] ) )

Parameters

Returns

An array of ezcontentobject objects or a two-dimensional array if 'group_by_attribute' is TRUE. If no objects are found, the function will return FALSE.

Description

This function fetches the objects that have been related to an object specified by the "object_id" parameter. It is capable of returning all related objects regardless of their relation type (attributes using the "Object relation" or "Object relations" datatype or standard object-level relations classified as "Common", "XML linked" or "XML embedded").

The "attribute_identifier" parameter makes it possible to specify either an ID number or an identifier string (class/attribute - for example "my_class/my_attribute") of an attribute. This parameter is not required. The default value is zero, which makes the function return only objects that are related on an object level, not at the attribute level. This behavior is similar to 'related_contentobject_array' functional attribute of a content object. When the parameter is used, the system will return objects that have been related using an attribute that is based on either the "Object relation" or "Object relations" datatype.

The "all_relations" parameter makes it possible to fetch all types of relations (when set to TRUE). This parameter is not required and the default value is FALSE. In addition, the value of this parameter can also be an array. The array may consist of the following strings: "common", "xml_link", "xml_embed" and "attribute". Each of them correspond to a relation type. The types can be mixed and provided in any order, which means that it is possible to use this parameter to do basic filtering. Refer to the "Object relations" page of the "Concepts and basics" chapter for more information about the relation types.

The "group_by_attribute" parameter can only be used when the value of the "all_relations" parameter is non-FALSE (either TRUE or an array). When the "group_by_attribute" parameter has been set to TRUE, the function will return a two-dimensional array instead of just an array of objects. The following example shows how this structure is built up:

$related_objects_grouped = array(
 
0 => array( $object1, $object2 ... ),
 
     // Objects related on content object level
     attr_id_1 => array( $object1, $object2 ... ),
     attr_id_2 => array( $object1, $object2 ... ),
 
     ...
 
     // Objects related by attributes
);

The "sort_by" parameter makes it possible to sort the result in different ways. This parameter must be provided as an array of arrays that define the sorting methods. The first element of each 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). Please note that this parameter works in the very same way as the "sort_by" parameter of the list fetch function. However, it currently only supports the following sorting methods:

• class_identifier
• class_name
• modified
• name
• published
• section

Please note that using other sort methods will lead to an error.

Examples

Example 1

{def $related=fetch( 'content', 'related_objects',
hash( 'object_id', $node.object.id,
      'all_relations', true(),
      'group_by_attribute', true(),
      'sort_by', array( array( 'class_name', true() ),
                        array( 'name', true() ) ) ) )}

Returns all relations grouped in arrays by attribute ID, then sorted by
class name and by object's name in ascending order.