reverse_related_objects

Written by Balazs Halasy, 04/04/2005 Updated 11/18/2009 by Graham Brookins Maintainers: Balazs Halasy, Svitlana Shatokhina, Ester Heylen

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

Name	Type	Description	Required
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 Exponential 4.1 which enables you to fetch an exact number of items	No.
offset	integer	A new parameter since Exponential 4.1 which enables you to define an offset.	No.
as_object	boolean	A new parameter since Exponential 4.1 which enables you to fetch the items as objects.	No.
load_data_map	boolean	A new parameter since Exponential 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>

Contributors

Balazs Halasy Author 04/04/2005 Maintainer
Ester Heylen Maintainer
Svitlana Shatokhina Maintainer
eric lundberg Commenter 10/14/2005
Xavier dutoit Commenter 11/17/2005
Marc Boon Commenter 03/13/2006
P. Renaud Commenter 02/22/2007
Mickael ROBIN Commenter 04/07/2009
Pike Commenter 11/12/2009
Tom Commenter 09/19/2009
Adrien Commenter 10/08/2008
Anders Berre Commenter 11/27/2008

Comments (13 historical)

Written by readers of the earlier documentation sites, kept as they were.

using in overrides

eric lundberg · 10/14/2005 11:26 pm

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

xavier dutoit · 11/17/2005 05:32 pm

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

Marc Boon · 03/13/2006 04:02 pm

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!
1. Re: Attribute filtering/sorting
  
  Marc Boon · 03/15/2006 01:06 pm
  
  I created a extended_attribute_filter to be able to fetch reverse related objects with filtering and sorting: http://ez.no/community/contribs/template_plugins/objectrelationfilter
Limit ?

P. Renaud · 02/22/2007 12:10 pm

Is there a reason why there is no limit to such a fetch ? What if there is a great number of related objects ?
1. Bump : Limit ?
  
  Mickael ROBIN · 04/07/2009 08:59 am
  
  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 :-)
  1. Re: Bump : Limit ?
    
    pike · 09/09/2009 02:48 pm
    
    Quick and dirty workaround here:
    http://ez.no/developer/forum/developer/relatedobjectsslice#msg192075
    note, this still needs to be solved for real, meaning "eZContentObject::relatedObjects" should implement offset, limit at a sql level.
2. Re: Limit ?
  
  Tom · 09/19/2009 10:39 am
  
  Limit/Offset has been implemented in 4.1, the documentation hasn't been updated to reflect it yet.
inheritance

Adrien · 10/08/2008 01:42 pm

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

Adrien · 10/20/2008 04:54 pm

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

Anders Berre · 11/27/2008 10:29 am

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.
1. Re: Doesnt work on attributes
  
  pike · 11/12/2009 12:46 pm
  
  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

pike · 11/12/2009 10:53 am

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

Comments

Add a comment