Path

ez.no / documentation / ez publish / technical manual / 4.x / reference / modules / content / fetch functions / reverse_related_objects


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     ]
           [ 'limit',                limit                 ]
           [ 'offset',               offset                ]
           [ 'as_object',            as_object             ]
           [ 'load_data_map',        load_data_map         ] ) )

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.
limit integer A new parameter since eZ Publish 4.1 which enables you to fetch an exact number of items No.
offset integer A new parameter since eZ Publish 4.1 which enables you to define an offset. No.
as_object boolean A new parameter since eZ Publish 4.1 which enables you to fetch the items as objects. No.
load_data_map boolean A new parameter since eZ Publish 4.1 which enables you to load the data_map array. 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".

Example 4

fetch('content', 'reverse_related_objects', hash(..., 'limit', '10', offset, '0', 'as_object', true(), 'load_data_map', false()))</pre>

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

Ester Heylen (18/11/2009 2:30 pm)

Balazs Halasy, Svitlana Shatokhina, Ester Heylen


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 ?
    • Bump : Limit ?

      Please add a LIMIT parameter to this fetch and the "related_objects" fetch.
      Limiting in the fetch instead of within a foreach loop would save so much processing!!!

      => thanks in advance for any quick'n'dirty hack till this is not natively improved :-)
    • Re: Limit ?

      Limit/Offset has been implemented in 4.1, the documentation hasn't been updated to reflect it yet.
  • inheritance

    eZ and its contributors seems to have difficulties with attributes shared by different content classes. There is no way to fetch and sort all objects of different classes sharing the same attribute (which should be linked by inheritance of a same meta-class but as you know inheritance is saddly not featured) in eZpublish release or in its contributions.
  • ignore_visibility

    Why this fetch is the only one to have ignore_visibility default value set to TRUE when others got a logical FALSE?
  • Doesnt work on attributes

    This only works when you add a relation in the bottom of the content/edit and not on attributes.

    If you makes an objectrelation-attribute they will appear in the details view of an object, but you wont get them from this fetch.

    Maybe its common knowledge, but I was using some time to find out this.
    • Re: Doesnt work on attributes

      I think thats what 'all_relations' does ? Pass true() to get all of them, including attributes.

      I dont think its completely documented, though. From doxygen, I read:

      true - return ALL relations, including attribute-level
      false - return object-level relations - DEFAULT
      >0 - bit mask of EZ_CONTENT_OBJECT_RELATION_* values

      $2c,
      *-pike
  • ignores read permissions

    According to this issue
    http://issues.ez.no/IssueView.php?Id=12097

    fetching reverse_related still ignores can_read permissions, and I can confirm that on 4.0.3

    $2c,
    *-pike