reverse_related_objects

Summary

Fetches reverse relates objects.

Usage

fetch( 'content', 'reverse_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 FALSE.

Description

This function makes it possible to fetch reverse related objects. The target object must be specified using the "object_id" parameter. The function will return an array of ezcontentobject objects which are using the target object through the conventional object relation mechanism. If no objects are found, the function will return FALSE.

Class attribute filtering

By making use of the "attribute_identifier" parameter, it is possible to fetch reverse related objects that make use of the target object by the way of an attribute. The attribute must use either the "Object relation" or the "Object relations" datatype. The "attribute_identifier" parameter can either be the ID number of the class attribute or a string that consists of the class identifier, a slash and the class attribute identifier (for example "my_class/my_attribute").

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 $objects=fetch( 'content', 'reverse_related_objects',
                     hash( 'object_id', 256 ) )}

{foreach $objects as $object}
    {$object.name|wash} <br />
{/foreach}

Outputs the names of the objects that make use of object number 256 through the conventional related objects mechanism.

Example 3

{def $objects=fetch( 'content', 'reverse_related_objects',
                     hash( 'object_id',            256,
                           'attribute_identifier', '4096' ) )}

{foreach $objects as $object}
    {$object.name|wash} <br />
{/foreach}

Outputs the names of the objects that make use of object number 256 through class attribute number 4096.

Example 3

{def $objects=fetch( 'content', 'reverse_related_objects',
                     hash( 'object_id',            256,
                           'attribute_identifier', 'my_class/my_attribute' ) )}

{foreach $objects as $object}
    {$object.name|wash} <br />
{/foreach}

Outputs the names of the objects that make use of object number 256 through an attribute called "my_attribute" that is a part of class "my_class".