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 returns all related objects regardless of their relation type (attributes using the "Object relation" or "Object relations" datatype or standard object-level relations).

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. This parameter is not required and the default value is FALSE.

The "group_by_attribute" parameter can only be used when the "all_relations" parameter has been set to TRUE. 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.