Relationshipsdocumentation for the dotCMS Content Management System

You can add Relationships between Content Types when the two Content Types require a relationship between each other or when the one Content item will be used in dynamic pulls to display one or more content items of the other Content Type.

For example, when adding a content item of an “Employee” Content Type, you might require a mandatory relationship to a content item of the “Department” Content Type so that no employee can be entered into the system without being related to a department. This scenario would be best handled by establishing a relationship between the two content types.

Adding a Relationship between Two Content Types

To add a Relationship between Content Types:

1. Select Content Types undeer Types & Tags.
2. Edit one of the two Content Types that you'd like to relate.
3. Select the Relationships tab.

Add New Relationship

4. Select the Parent and Child Content Types.

In the Add/Edit Relationship window, choose which Content Type will be the Parent Content Type and which will be the Child Content Type. In the example of “Department” and “Employee” Content Types from above, the “Department” would be the parent and the “Employee” the child because Employees “belong to” (or are assigned to) a Department.

Relating Two Content Types

6. Choose a Relationship Cardinality.

You may choose either “One to Many” or “Many to Many” to limit how many pieces of Content can be related to each other on each side of the Relationship. For example, in the case of a “Team-Player” relationship a “One to Many” Relation could be used if each player is allowed to belong to only one team at a time. However if it's possible for a player to be assigned to multiple teams, you could instead choose a “Many to Many” Relation.

7. Specify Relationship Requirements.

The Is a Parent Required and Is a Child Required checkboxes allow you to require that any new (or updated) content item be related to another content item in order for it to be saved.

If you select the Is a Parent Required checkbox, then any time a content item of the Child Content Type is added or updated, that content item must be related to a content item of the Parent Content Type. Similarly, if you select the Is a Child Required checkbox, then any time a content item of the Parent Content Type is added or updated, that content item must be related to a content item of the Child Content Type. Saving the newly added relationship will allow content editors to relate different pieces of content to each other.

8. Relate Individual Content Items

Once the Relationship has been created, you can relate individual content items of the two Content Types to each other. For more information on creating related content, please see the Relating Content documentation.

Adding a Relationships Field to a Content Type

By default, when a Content Type is related to another Content Type, a new Relationships tab is displayed when editing any content item of either Content Type; your content contributors must select this tab to add new relationships between content items.

Relate Child Content to Parent

However with the relationships in a separate tab, content contributors may not recognize that they can (or need to) add a Relationship when adding or editing a content item. To make the Relationship more obvious to your content contributors, you can add a Relationships Field to one or both of the Content Types; the Relationships Field removes the Relationships tab, replacing it with a field which displays in the main Content tab with all other fields of the Content Type.

Note:

  • If either relationship is required, it is strongly recommended that you add a Relationship Field to the Content Type that requires a relationship, to make it clear to your Content Contributors that they must relate new content items.
    • If the Is a Parent Required option is checked, add a Relationships Field to the child Content Type.
    • If the Is a Child Required option is checked, add a Relationships Field to the parent Content Type.
  • When you add a Relationships Field to a Content Type, all relationships that the Content Type is a part of are displayed (and can be modified) from the Relationships Field.
    • You can not create a Relationships Field to display only some of the Relationships the Content Type is a part of.

Relate Child Content to Parent

To add a Relationships Field to a Content Type:

  1. Edit the Content Type.
  2. Drag a “Relationships Field” to add it to the list of fields on the Content Type.
  3. Enter a Label for the field.

Label the Relationship

Viewing Relationships

To view the Relationships that exist on your dotCMS site:

  1. Click on Types & Tags and then edit one of the related Content Types.
  2. Click on the Relationships tab to see all of the relationships for the Content Type

View Relationships

Deleting a Relationship

To delete a Relationship between two Content Types:

  1. Display the Relationships screen.
  2. Click the trash can icon next to the Relationship that you wish to Delete.

Important Notes:

  • Deleting a Relationship can not be un-done.
    • When you delete a Relationship, 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.
  • A full re-index and cache flush from the maintenance portlet is recommended after deleting relationships.
    • The system will not allow you to create a new Relationship with the same name until the cache clear and re-index have completed.