Relationships documentation for the dotCMS Content Management System

Add a Relationship field on any Content Type to relate content created to another different type of content in the system (e.g., Employee to Department or Promotion to Product, etc.).

For example, when adding a content item of an “Movie” Content Type, you might want to add a relationship from the “Movie” contentlet to a “Movie Staff” type of content so that dynamic page listings can show pulls of Movies that show a listing of the cast, and conversely, actor/actress/director detail pages that show listings of all the movies they have worked on. Any type of content can be related to another using relationship fields. Content Types can also be related to the same content type. The dotCMS documentation site, for example, utilizes a single content type, and documentation content is related to other documentation content at several levels and are organized and pulled entirely by their relationship to each other.

Adding a Relationship Field to a Content Type

When editing a Content Type (under “Types & Tags”) drag Relationships Field from the FIELDS list to the Content Type.

Add New Relationship Field

After dragging a relationships field to your Content Type, a model displays the Relationships Field properties:

  • Relationship field name
  • Whether the relationship is a new relationship or an existing relationship
  • The Content Type to relate to using the field
  • The cardinality of the relationship (One to One, One to Many, or Many to Many)
  • A required checkbox to require the related content
  • A checkbox to allow searching for content by relationship

After saving the properties of the relationship, related content can be added when editing content.

Relate Existing Content

Relationship fields can be used to add multiple relationships between the same two Content Types as needed. If the same name is used for another relationship field (although not recommended), the velocity variable name for the field will add a 1, 2, 3… to the end of the velocity variable name automatically and sequentially to ensure programatic uniqueness between the fields.

Adding an Existing Relationship Field to a Content Type

To add related content from either side of the relationship, edit the second content type, again adding a Relationships Field, but this time click the “Existing” radio button on the field properties, then click “Select Relationship” and choose the existing relationship so that both content types are properly paired when adding related content from either side of the relationship.

Adding an Relationship Field with Existing Relationship

Relating Existing Content

When editing content that has a relationships field, content contributors can either choose Relate to relate existing content or choose Relate New Content to add new content that should be related to the content currently being edited. The image below shows both options:

Relate Existing Content

If the Relate option is chosen, content contributors can then search and choose one or more existing contentlets (using checkboxes) to relate the selected content to the current content being edited.

Search and Relate Multiple Contentlets

Clicking “Relate” button will establish the relationship between the content.

Relating New Content

When choosing to Relate New Content, make sure to save content before selecting the Relate New Content option since this will exit editing the current contentlet to add the new content.

Relate New Content

After choosing Relate New Content, the content contributor can add the new content to relate to the original content and then Save the new content.

Adding New Related Content

When relating content in this way, content contributors can return to the originally edited contentlet by clicking on the “Return to {content title}” option as shown below:

Returning to Original Content

Search for Related Content

From the Content Search Manager, choose a Content Type that has a searchable relationships field and click “Advanced” to show all the searchable fields. In the relationship field type the title of the related content OR type the content identifier of the related contentlet. If related content exists, matching titles will appear and MUST be clicked to then filter the list of content by the related data. For example, after choosing the actor's name from the list, the only movies that will display in the list are movies the actor is already related to.

Searching for Content by Relationship

Deleting a Relationship

To delete a Relationship between two pieces of content, click the trash can icon to the right of the related content in the relationship field.

Deleting a Relationship between Content

Important Notes:

  • Deleting a Relationship can not be un-done.
    • When you delete a Relationship Field on a Content Type, all relationships between individual content items that are part of that Relationship will be permanently removed and cannot be restored without manually relating all individual content items again.
    • Therefore it is strongly recommended that you have recent backups of your data before deleting a Relationship Field from a Content Type.
  • A full re-index and cache flush from the maintenance portlet is recommended after deleting relationships.
    • The system may not allow you to add a new Relationship Field with the same name until the cache clear and re-index have completed.