Object Relationships
Content Repository : Developer GuideMany applications of the content repository require that content items be related to each other as well as to other classes of objects. Examples include:
- News stories may be linked to other stories on the same topic.
- An article may be linked to any number of photos or charts that are embedded in the article.
- A long article is divided into multiple sections, each of which is intended for separate display.
- Product reviews are linked to specific products.
- User portraits are linked to specific users.
The ACS kernel provides a standard, highly flexible data model and API for relating objects to other objects. If you have a highly specific problem and are developing your own user interface on the content repository, you can use the ACS relationships framework directly. The relationship framework in the content repository itself is simply intended as a convenience for handling common relationship situations involving content items.
Parent-Child Relationships
In many cases one content item may serve as a natural container for another item. An article divided into sections, or a news story with an associated photo are one example of this. These "parent-child" relationships are handled by the basic hierarchical organization of the content repository. Every item has a parent item, represented internally by the parent_id column in the cr_items table.
It is often desirable to constrain the number and content type of child items. For example, the specifications for a news story may only allow for a single photo. A structured report may have exactly three sections. Furthermore, it may be necessary to classify or identify child items of the same type. Clearly the sections of a report would have a logical order in which they would need to be presented to the user. The layout for a photo album may have a special position for a "featured" photo.
 |  |
The content repository accommodates these situations in the following ways:
- An API procedure, content_type.register_child_type, may be used to specify the minimum and maximum number of children of a particular content type that an item may have. You may optionally specify a "tag" for identifying child items of the same type. For example, you may want to allow only 1 image with the "featured" tag, and up to 8 other images without this.
- A Boolean API function, content_item.is_valid_child, which checks all registered child constraints on the content type of an item and returns true if it is currently possible to add an child of a particular type to tan item. Note that this function does not protect against concurrent transactions; it is only foolproof if you lock the cr_child_rels table beforehand.
- A mapping table, cr_child_rels, which contains two attributes, order_n and relation_tag, that may be used to characterize the parent-child relationship. Parent-child relationships are themselves treated as ACS Objects, so this table may be extended with additional attributes as required by the developer.
Note that there is no currently no explicit API to "add a child." You specify the parent of an item upon creating it. You can use the API procedure content_item.move to change the parent of an item.
Item-Object Relationships
In addition to the relationships to their parents and children in the content repository hierarchy, content items may be linked to any number of other objects in the system. This may include products, users or content items on related subjects.
The same need to constrain the possibilities for an item-object relationship, as described above for parents and children, also apply to items and objects in general. The content repository provides a data model and API for managing these constraints that parallels what is provided for parent-child relationships:
- An API procedure, content_type.register_relation_type, may be used to specify the minimum and maximum number of relations with a particular object type that an item may have. There is no limitation on the type of objects that may be related to content items. If you wish to relate content items to other content items, however, the object type should specify a content type (a subtype of content_revision) rather than simply content_item. As for parent-child relationship constraints, ou may optionally specify a "tag" for identifying related objects of the same type.
- A Boolean API function, content_item.is_valid_relation, which checks all registered constraints on the content type of an item and returns true if it is currently possible to relate an object of a particular type to an item.
- A mapping table, cr_item_rels, which contains two attributes, order_n and relation_tag, that may be used to characterize the item-object relationship. Item-object relationships are themselves treated as ACS Objects, so this table may be extended with additional attributes as required by the developer.
Extending Parent-Child and Item-Object Relationships
The simple relation mechanisms described above may not be sufficient for some applications. However, because both relationships defined by the content repository are themselves objects, you have the option to extend their types as you would for any other ACS object.
karlg@arsdigita.com
Last modified: $Id: object-relationships.html,v 1.2 2017/08/07 23:47:47 gustafn Exp $
