ibexa

Path

ez publish / technical manual / 4.x / reference / datatypes / object relations

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

Object relations

Summary

Stores relations to other content objects.

Properties

NameInternal nameSearchableInformation collector
Object relations ezobjectrelationlist Yes. No.

Description

This datatype makes it possible to store relations to multiple objects. It allows users to browse the node tree and select objects that should be related; in addition, it makes it possible to create new objects and automatically relate them to the one that is being edited. The following screenshot shows the class attribute edit interface for this datatype.

Please note that this datatype takes care of object relations only, and doesn't consider any particular existing permissions or visibility states. If you intend to filter relations considering existing roles and permissions we recommend the use of fetch functions within view templates. This way permissions and visibility will be considered.

Class attribute edit interface for the "Object relations" datatype.

Class attribute edit interface for the "Object relations" datatype.

The "Selection method" dropdown list makes it possible to set which browse interface should be used when the node tree is being explored by users (from within the object edit interface). There are seven selection methods in total. Three of them allow the selection of one object at a time. The remaining four make it possible to select multiple objects at the same time.

The following selection methods only allow the addition of one related object at a time:

  •  Dropdown list
  •  List with radio buttons
  •  Template based, single

The following selection methods allow the addition of multiple related objects at the same time:

  •  Browse (default)
  •  List with check boxes
  •  Multiple selection list
  •  Template based, multi

By default, the "Browse" selection method is used, which means that the system will bring up a standard browse interface for adding related objects. It is possible to specify the start-location for browsing. This is controlled by the "Default location" section. If any other selection method is used, the system will display a list of nodes as part of the object edit interface. In these cases, the list is automatically limited to one subtree, according to the specified default location. The template based selection methods ("Template based, multi" and "Template based, single") make use of the "objectrelationlist.tpl" template located in the "templates/node/view/" directory of the standard design. By creating a template override, you can customize the look and feel for these selection methods.

Note that if a related object is moved to the trash, the relation will still exist. The related object itself will not be shown when the object which it is related to is displayed. This behavior can be changed by overriding the default templates. If the "Browse" selection method is used in the object edit interface, the "Published" column of the corresponding related object will read "No".

The "Type" dropdown list is no longer in use. It is only available if the backwards compatibility mode is enabled. This is controlled by the "AdvancedObjectRelationList" setting located in the "[BackwardCompatibilitySettings]" section of the "settings/site.ini" configuration file or an override. Due to some problems with the old implementation, this setting is disabled by default. This documentation page provides the description of the datatype assuming that the "AdvancedObjectRelationList" setting is disabled.

The "Allowed classes" menu makes it possible to control which types of objects that users should be allowed to select while browsing the node tree.

In addition to allowing relations to existing objects, this datatype makes it possible to create new objects and automatically relate them to the one that is being edited. Note that this currently works with all selection methods except the "Browse" method. In order to use this feature, you need to specify which type of object that should be created and where the newly created objects should be placed. This can be done by making use of the "Object class" dropdown list in the "New objects" section and the "Default location" section. If the "Object class" dropdown is set to "none", it will not be possible to create new objects from within the object edit interface.

As previously mentioned, the "Default location" section can be used to limit the list of nodes to the specified subtree (for any selection method except "Browse"). For example, if you use the "Media" folder as the default location and specify "List with check boxes" as the selection method in the class edit interface, the system will display nodes which are located under the "Media" node (only the ones which are directly below it) along with checkboxes for making selections right in the object edit interface. If no default location is specified, the list of nodes will only contain the top level nodes.

Object attribute edit interface

The look and feel of the object attribute edit interface for this datatype varies depending on which selection method that is specified at the class level. Note that the "Create new" button will not be available unless a default location and a class for newly created objects are specified.

Browse

The following screenshot shows the object attribute edit interface for this datatype in a case where the "Browse" selection method is used.

Object attribute edit interface for the "Object relations" datatype (default selection method).

Object attribute edit interface for the "Object relations" datatype (default selection method).

Objects relation order

In the "Browse" selection method, the order set in the "Order" column let you set an number to organize your content. The numbers are used for ordering content and are relative to others numbers.

Note: If a related content object is deleted, the order won't be update to let the editor know that some content was removed. It can lead to non-sequential set of values This is the intended behaviour. If the object is republished, the order will updated in a sequential way.

List with check boxes

The following screenshot shows the object attribute edit interface in a case where the "List with check boxes" selection method is used while both the default location (in this case the "Media" folder) and the type of newly created objects are specified.

Object attribute edit interface for the "Object relations" datatype (list with checkboxes).

Object attribute edit interface for the "Object relations" datatype (list with checkboxes).

Multiple selection list

The following screenshot shows the object attribute edit interface in a case where the "Multiple selection list" selection method is used and the "Media" folder is specified as the default location.

Object attribute edit interface for the "Object relations" datatype (multiple selection list).

Object attribute edit interface for the "Object relations" datatype (multiple selection list).

Dropdown list

The following screenshot shows the object attribute edit interface in a case where the "Dropdown list" selection method is used and the "Media" folder is specified as the default location.

Object attribute edit interface for the "Object relations" datatype (dropdown list).

Object attribute edit interface for the "Object relations" datatype (dropdown list).

List with radio buttons

The following screenshot shows the object attribute edit interface in a case where the "List with radio buttons" selection method is used and the "Media" folder is specified as the default location.

Object attribute edit interface for the "Object relations" datatype (list with radio buttons).

Object attribute edit interface for the "Object relations" datatype (list with radio buttons).

Raw output

The ".content" of an ezcontentobjectattribute object using this datatype returns a hash containing one element called "relation_list". This element can be either an empty array (if there are no relations) or an array of hashes. If there are related objects, each element will contain information about a specific object. The hash-structure of the elements is given in the table below.

Key

Type

Description

priority

string

The node's priority (positive or negative integer).

contentobject_id

string

The ID number of the content object.

contentobject_version

string

The version number of the published version at the time when the relation was modified.

node_id

string

The ID number of the node at the time when the relation was modified.

parent_node_id

string

The ID number of the parent node at the time when the relation was modified.

contentclass_id

string

The ID number of the content class which the object is an instance of at the time when the relation was modified.

contentobject_remote_id

string

The remote id of the related content object at the time when the relation was modified.

identifier

boolean

Reserved for future use.

is_modified

boolean

Not in use (needed for backwards compatibility).

As the intention of this data is to provide meta information about state when relation was created, you should instead of using this rather fetch the object using its contentobject_id for front-end needs like listing locations, needing to know current version and so on.

Changing/Deleting a related-object main location/node

When relating an object using a relation_list, if the related-object main location is changed and then deleted, the relation_list node_id-reference is not updated to reflect the related-objects changed main location/node.

Since the information provided in relation_list is the original one, you might have to use an object-fetch method to retrieve up-to-date information.

Example:

{foreach $item.data_map.authors.content.relation_list as $author_relation}

{set $person=fetch(content,object, hash(object_id, $author_relation.contentobject_id))}

{/foreach}

Balazs Halasy (21/02/2005 2:41 pm)

Sarah Haïm-Lubczanski (16/04/2014 10:00 am)

Balazs Halasy, Andrea Melo, Ricardo Correia, Sarah Haïm-Lubczanski, André R.

Comments

  • Use undocumented site.ini setting to make it work like it used to

    Thursday 24 November 2005 11:20:10 am

    Daniel Staver

    I just spent three hours trying to figure out why this function no longer allows you to upload new objects and edit existing ones after upgrading a large site for a client... Turns out it was changed on purpose and that there's an undocumented site.ini setting to make it work like it used to:

    [BackwardCompatibilitySettings]
    AdvancedObjectRelationList=enabled

  • INI-based limitations for browse selection method

    Wednesday 18 January 2006 9:24:02 am

    Kristof Coomans

    If you choose the selection method "browse", you can configure which browse type has to be used with an undocumented setting in content.ini:
    [ObjectRelationDataTypeSettings]
ClassAttributeStartNode[]
ClassAttributeStartNode[]=240;AddRelatedImageToDataType


    Where 240 is the class attribute id and AddRelatedImageToDataType is the browse type (this type can be configured in browse.ini).

    If for a specific class attribute no browse type has been specified, AddRelatedObjectListToDataType is used.

    The Object Relation datatype uses the same settings, but the default browse type is AddRelatedObjectToDataType.

  • Example code to fill an attribute of this datatype with PHP

    Wednesday 21 June 2006 6:25:50 pm

    Kristof Coomans

    See http://ez.no/community/forum/deve...n_attribute_type_within_a_php_script