Relationships - Documentation topics on: relating content,relating structures,relationships,.

Relationships

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 “Player” Content Type, you might require a mandatory relationship to a content item of the “Team” Content Type so that no player can be entered into dotCMS without being related to a team. This scenario would be best handled by establishing a relationship.

Adding a Relationship between Two Content Types

To add a Relationship between Content Types:

1. Select the Content Types Tab.
2. Click on the drop down arrow on the right of the +Add New Content Type button.
3. Select Add New Relationship.

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 “Team” and “Player” Content Types from above, the “Team” would be the parent and the “Player” the child because players “belong to” (or are assigned to) a team.

5. (Optional) Enter the Parent Relation Name and Child Relation Name.

These two fields are combined with a dash between them to form the name of the relationship (for example, “Team-Player”). By default, the Parent Relation Name and Child Relation Name fields will be set to the names of the selected parent and child Content Types, but you may change these in order to change the name of the relationship.

Relating Two Content Types

6. Choose a Relation.

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.

8. Save the New Relationship.

Relationships Field

9. 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.

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.

To add a Relationships Field to a Content Type:

  1. Edit the Content Type.
  2. Click the +Add New Field button.
  3. Set Display Type to Relationships Field.
  4. Enter a Label for the field.
    • The Label will be displayed on the content editing screen, above the list of Relationships.

Relate Child Content to Parent

Viewing Relationships

To view the Relationships that exist on your dotCMS site:

  1. Open the Content Types screen (click on the Content Types tab or select Content Types from the menu).
  2. Click the down arrow on the right side of the Add New Content Type button.
  3. Select View all Relationships.

View Relationships

Deleting a Relationship

To delete a Relationship between two Content Types:

  1. Display the Relationships screen.
  2. Click the red X under the Action column to the left of the name of 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.