ibexa

Caution: This documentation is for eZ Publish legacy, from version 3.x to 5.x.

related_objects

Summary

Fetches related objects.

Usage

fetch( 'content', 'related_objects',
        hash( 'object_id',            object_id,
            [ 'attribute_identifier', attribute_identifier, ]
            [ 'all_relations',        boolean,              ]
            [ 'group_by_attribute',   boolean,              ]
            [ 'sort_by',              sort_by               ] ) )

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

Returns

An array of ezcontentobject objects or a two-dimensional array if 'group_by_attribute' is TRUE. If no objects are found, the function will return FALSE.

Description

This function fetches the objects that have been related to an object specified by the "object_id" parameter. It returns all related objects regardless of their relation type (attributes using the "Object relation" or "Object relations" datatype or standard object-level relations).

The "attribute_identifier" parameter makes it possible to specify either an ID number or an identifier string (class/attribute - for example "my_class/my_attribute") of an attribute. This parameter is not required. The default value is zero, which makes the function return only objects that are related on an object level, not at the attribute level. This behavior is similar to 'related_contentobject_array' functional attribute of a content object. When the parameter is used, the system will return objects that have been related using an attribute that is based on either the "Object relation" or "Object relations" datatype.

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 $related=fetch( 'content', 'related_objects',
hash( 'object_id', $node.object.id,
      'all_relations', true(),
      'group_by_attribute', true(),
      'sort_by', array( array( 'class_name', true() ),
                        array( 'name', true() ) ) ) )}

Returns all relations grouped in arrays by attribute ID, then sorted by
class name and by object's name in ascending order.

Balazs Halasy (07/03/2006 11:35 am)

Julia Shymova (28/07/2008 9:14 am)

Balazs Halasy, Julia Shymova


Comments

  • Sample

    Fetching Related objects in the pagelayout
    {let related_objects=fetch( 'content', 'related_objects',
    		hash( 'object_id', $module_result.content_info.object_id ) )}
     
    	{section loop=$related_objects var=related_object}
    		
    		URL: {$related_object.item.main_node.url_alias|ezurl} <br />
    		Name: {$related_object.item.name} <br />
    		
    		{node_view_gui view=line content_node=$related_object}
    		
    	{/section}
    
    • Re: Sample

      Thanks for the exemple, but there is a little error in your statement:

      {node_view_gui view=line content_node=$related_object}

      has to be replaced with

      {node_view_gui view=line content_node=$related_object.main_node}

      as node_view_gui requires an ezcontentobjecttreenode object for content_node:

      -->http://ez.no/doc/ez_publish/techn...unctions/visualization/node_view_gui

      Hope this help others.

      Marc
  • Pagination

    Because there is no offset and limit parameter, this fetch can hardly be used with pagination. You'll have to use a
    fetch('content', 'list', ...)
    
    with adequate parameters to do that.
  • attribute_identifier not working for me.

    I'm using the following code, trying to show related items of from folder/related_organisations only, but it doesn't seem to work.

    I've tried using the attribute id, adding/removing the quotation marks, changing the order of the rules... I can make it fetch all related objects, and I can make it fetch none - but I can't get it to only fetch the ones I want.

    Can anyone see a reason why it wouldn't be working? I'm using 3.86.


    {def $relations=fetch( 'content', 'related_objects',
    hash( 'object_id', $node.object.id,
    'all_relations' , true(),
    'attribute_identifier', 'folder/related_organisations'
     ))}
    
    • Re: attribute_identifier not working for me.

      {def $relations=fetch( 'content', 'related_objects',
      hash( 'object_id', $node.object.id,
      'all_relations' , false(),
      'attribute_identifier', 'folder/related_organisations'
       ))}
      


      as I see you had 1 mistake: you have to set all_relations to false.