Object relations
Summary
Stores relations to other content objects.Properties
| Name | Internal name | Searchable | Information 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.
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).
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).
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).
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).
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).
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)
Comments