Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.
For 5.x documentation covering Platform see eZ Documentation Center, for difference between legacy and Platform see 5.x Architecture overview.

reverse_related_objects

Summary

Fetches reverse related 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               ]
           [ 'ignore_visibility',    ignore_visibility     ] ) )

Parameters

NameTypeDescriptionRequired
object_id integer The ID number of the target object. Yes.
attribute_identifier mixed The ID number or class/attribute identifier of the target attribute. No.
all_relations boolean Controls whether to fetch all types of relastions or not, default is FALSE. No.
group_by_attribute boolean Groups the result based on the attributes, default value is TRUE. No.
sort_by array The sorting mechanism that should be used. No.
ignore_visibility boolean Makes it possible to fetch hidden nodes (TRUE by default). No.

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.

Fetching hidden nodes

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.

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".

Balazs Halasy (04/04/2005 2:47 pm)

Svitlana Shatokhina (08/01/2007 1:16 pm)

Balazs Halasy, Svitlana Shatokhina


Comments

  • using in overrides

    If you are doing this on a node override, you will probably want to not use a hardcoded node id (since you want it to apply to all nodes of a given type) and you can instead use $node.contentobject_id to reference the reverse related objects of the specifc node you are overriding.

    If you want to look farther up the chain, and see the reverse related objects to the ones you just got, you can use the .id member of the objects you are looking at.
  • Enhanced object relation can be used too with this fetch

    the reverse_related_objects fetch works well with the enhanced object relation attribute too.

    http://ez.no/community/contribs/datatypes/enhanced_objectrelation
  • Attribute filtering/sorting

    It's really sucks that you can't do attribute filtering/sorting on this fetch!
    Am I supposed to fetch ALL reverse_related objects first, and then do filtering and/or sorting on the result set? Very inefficient!
  • Limit ?

    Is there a reason why there is no limit to such a fetch ? What if there is a great number of related objects ?
  • reverse_related ignores permissions

    Hi

    this fetch ignores read permissions.
    http://issues.ez.no/IssueView.php?Id=12097

    though it is not noted as a bug, I didn't expect this.
    just warning,
    *-pike
  • related objects of a translation

    How can I get the reverse related objects of a translation.
    When I do, I get of all the translations.
    Even though:
    ShowUntranslatedObjects=disabled