Relationship Field

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 (in Content Model -> Content Types), drag Relationships Field from the FIELDS list to the Content Type.

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, Many to One, 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.

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 the showFields property to a Content Type

When a Content Type has a relationship field a user can chose what relationship information is shown when editing a content with that Content Type. This is done with the showFields property. The showFields property is a field that takes a comma separated list of the fields you want to display. To achieve this follow the steps below:

1. Go to the Content Type that is displaying the Relationships field, and edit it.
2. Click the FIELD VARIABLES tab.
3. The showFields property contains a comma-separated list of the Velocity Variable Names of each column that will be displayed. For example, if the child Content Type has two fields: Name, and Department, the property will look like this: – Key = showFields – Value = name,department

Notice that the value MUST NOT be enclosed in any character. They're just the Velocity Var Names separated by a comma.

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:

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.

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.

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.

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:

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.

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.

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.

Parent and Child Relationship

Parent Child relationships are a unique type of relationship that have unique challenges.

Identifying the Parent and Child Content Type Respectively

It can sometimes be difficult to identify which Content Type is the child and which is the parent in a relationship. The best way to find out which is which is to do the following:

1. Go to the content type for one of the pieces of content in the relationship
2. Find the relationship field where that Content Type is related to the other Content Type you are typing to identify the relationship for.
   
3. Click on the pencil to edit the relationship
4. The relationship field will show up and show a diagram identifying the parent and child
   

Finding the Related Content Item in Content Search

Due to the structure of the parent child relationship you can not always find the related content item in all the typical ways. The table below defines how the parent/child content item can be found based on the relationship of the starting content item.