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
| 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. |
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".
Contributors
- Balazs Halasy Maintainer
- Svitlana Shatokhina Updated Maintainer
- eric lundberg Commenter
- Xavier dutoit Commenter
- Marc Boon Commenter
- P. Renaud Commenter
- Luc Commenter
Comments (8 historical)
Written by readers of the earlier documentation sites, kept as they were.
using in overrides
eric lundberg ·
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 ·
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 ·
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!
Re: Attribute filtering/sorting
Marc Boon ·
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 ·
Is there a reason why there is no limit to such a fetch ? What if there is a great number of related objects ?
Group_by_attribute, false() not working
Luc ·
The source code says that the group_by_attribute defaults to FALSE but the this documentation says it defaults to TRUE. In any case setting it to false() causes it to fail to return anything.
// Fetches reverse related objects array $FunctionList['reverse_related_objects'] = array( 'name' => 'object', 'operation_types' => array( 'read' ), 'call_method' => array( 'include_file' => 'kernel/content/ezcontentfunctioncollection.php', 'class' => 'eZContentFunctionCollection', 'method' => 'fetchReverseRelatedObjects' ), 'parameter_type' => 'standard', 'parameters' => array( array( 'name' => 'object_id', 'type' => 'integer', 'required' => true ), array( 'name' => 'attribute_identifier', 'type' => 'string', 'required' => false ), array( 'name' => 'all_relations', 'type' => 'boolean', 'required' => false, 'default' => false ), array( 'name' => 'group_by_attribute', 'type' => 'boolean', 'required' => false, 'default' => false ), array( 'name' => 'sort_by', 'type' => 'array', 'required' => false, 'default' => array() ), array( 'name' => 'ignore_visibility', 'type' => 'boolean', 'required' => false, 'default' => null ) ) );Re: Group_by_attribute, false() not working
Luc ·
However kernel/classes/ezcontentobject.php actually defaults this to FALSE
function &relatedContentObjectList( $fromObjectVersion = false, $fromObjectID = false, $attributeID = 0, $groupByAttribute = false, $params = false ) {New Sort Options?
Luc ·
3.9.2 lists these as Available Sort options.
function fetchAvailableSortFieldList() { return array( 'result' => array( '6' => ezi18n( 'kernel/content', 'Class identifier' ), '7' => ezi18n( 'kernel/content', 'Class name' ), '5' => ezi18n( 'kernel/content', 'Depth' ), '3' => ezi18n( 'kernel/content', 'Modified' ), '9' => ezi18n( 'kernel/content', 'Name' ), '1' => ezi18n( 'kernel/content', 'Path String' ), '8' => ezi18n( 'kernel/content', 'Priority' ), '2' => ezi18n( 'kernel/content', 'Published' ), '4' => ezi18n( 'kernel/content', 'Section' ) ) ); }