Pull and Display Related Content documentation for the dotCMS Content Management System

The ContentTool ($dotcontent) contains several methods which allow you to retrieve content which is related to another specified piece of content. In addition, for Content Types with a Relationships Field, you can reference the relationship field directly to pull related content.

Usage

Direct Access to Relationship Fields

You can directly reference Relationships Fields in content by specifying the name of the Relationship Field from the content item:

<ul>
#foreach( $relation in $contentItem.fieldVarName )
    <li>$relation.title</li>
#end
</ul>

This is the simplest way to access related content, as no Velocity method call is required. Note that when using this approach:

  • All related content will be returned.
  • Related content will always be returned in the order the related content was saved (the same order the related content shows when viewing the content item in the back-end UI).

Content Tool Velocity Methods

The way the pullRelated method is called depends on whether you're pulling content using Relationship Fields or Relationship Names (for legacy Relationships).

Relationship Fields

TypeMethod CallDescription
Default PullpullRelatedField( contentletIdentifier, relationshipFieldVar, condition )Pulls all related content which matches the condition, using the default sort order.
Sort ResultspullRelatedField( contentletIdentifier, relationshipFieldVar, condition, sort )Pulls all related content which matches the condition, sorting as specified by the sort.
Limit ResultspullRelatedField( contentletIdentifier, relationshipFieldVar, condition, limit, sort )Pulls at most limit related content items which match the condition, sorting as specified by the sort.
Page ResultspullRelatedField( contentletIdentifier, relationshipFieldVar, condition, limit, offset, sort )Pulls at most limit related content items starting from the specified offset, which match the condition, sorting as specified by the sort.

Relationship Names (Legacy Relationships)

TypeMethod CallDescription
Limit ResultspullRelated( relationshipName, contentletIdentifier, pullParents, limit)Pulls at most limit related content items, using the default sort order.
Sort ResultspullRelated( relationshipName, contentletIdentifier, pullParents, limit, sort)Pulls at most limit related content items, sorting the results as specified by the sort parameter.
Filtered ResultspullRelated( relationshipName, contentletIdentifier, condition, pullParents, limit, sort)Pulls at most limit related content items which match the condition parameter, sorting as specified by the sort parameter.

Parameters

You may only pass parameters when pulling related content using the Velocity methods; when pulling content by directly accessing the Relationships Field, the related content will always all be returned, and will always be returned in the order the related content was saved (the same order the related content shows when viewing the content item in the back-end UI).

The following arguments are required by different versions of both the pullRelated() and pullRelatedField() methods.

ParameterTypeDescriptionNotes
relationshipNameStringName of the Relationship.
(pullRelated() only)
The Relationship Name can be found by viewing the Relationship in the Relationships tab.
relationshipFieldVarStringVelocity variable name of the Relationship field.
(pullRelatedField() only)
Note: The full field specification must be provided, including the variable name of the Content Type and Field (e.g. contentTypeVar.fieldVar).
 
contentletIdentifierStringIdentifier of the contentlet for which related items will be returned.The contentlet identifier is passed as a string, and may be found by returning the id field of a content object returned by any other content pull method, or by viewing the “History” tab in the content editing screen.
conditionStringLucene query terms which limit the returned results.Only content items which match the condition and which are related to the specified contentlet will be returned.
pullParentsBooleanSpecifies whether to pull parents or children of the specified content item.If true, the Contentlet Identifier is a child, and the method will pull Parents.
If false, the Contentlet Identifier is a parent, and the method will pull children.
sortStringHow to sort the results.Takes a list of field variable names, in the order they will be used.
In addition each field may be followed by a space and asc or desc specifying the sort order for that field. If no sort order is specified, asc is used.
limitIntegerMaximum number of content items to return. 
offsetIntegerIndex of the first item to return (for pagination of results). 

Examples Using Relationship Fields

Example 1: Pulling Related Content by Direct Field Access

The following code shows how to display a single related child content item (Employee Listing), or how to set up a secondary #foreach loop to iterate over multiple related child content items (Locations Listing).

Note that for this example, the Employee Content Type has a Relationship Field with the Velocity variable name “location”, and this field is configured as Many to One in the Employee Content Type (and configured as One to Many in the Location content type).

<h2>Locations Listing (Many Related Employees)</h2>
#foreach($location in $dotcontent.pull("+contentType:Location",3,"modDate desc"))
    #editContentlet($location.inode)
    <h3>$location.title</h3>
    #set($employeeList = $!{location.employees})
    <h4>Employee(s):</h4>
    <ul>
        #foreach($relatedEmployee in $employeeList)
            <li>$relatedEmployee.firstName $relatedEmployee.lastName</li>
        #end
    </ul>
#end

Example 2: Simple pullRelatedField Method Call

The following example retrieves up to 10 related content items for a content item with Identifier “784bebeb-ce31-414f-b7e8-41653ea9f195”, through the Relationship Field with the Velocity variable name “product”. Only related content which matches the lucene query "+productName:*laptop*" will be returned. Since no sort order is specified, the returned items will be returned in the default order (the same order they are displayed in the legacy Relationships field).

<ul>
#foreach($content in $dotcontent.pullRelatedField("784bebeb-ce31-414f-b7e8-41653ea9f195","product","+productName:*laptop*"))
    <li>$content.title</li>
#end
</ul>

Example 3: pullRelatedField with Condition and Sort

The following example adds a sort order ("modDate") to sort the returned items by modification date:

<ul>
#foreach($content in $dotcontent.pullRelatedField("784bebeb-ce31-414f-b7e8-41653ea9f195","product","+productName:*laptop*","modDate"))
    <li>$content.title</li>
#end
</ul>

Examples Using Relationship Names (Legacy Relationships)

The following examples show how to use the $dotcontent.pullRelated() method to pull related content using Relationship Names (legacy Relationships fields).

Example 4: Simple pullRelated Method Call (Legacy Relationship)

The following example retrieves up to 10 related content items for a content with Identifier “784bebeb-ce31-414f-b7e8-41653ea9f195”. The pullParents argument is set to "false", so the identifier is for a parent item, and the items returned are children of the Relationship. Since no sort order is specified, the returned items will be returned in the default order (the same order they are displayed in the legacy Relationships field).

<ul>
#foreach($content in $dotcontent.pullRelated("relationshipName","784bebeb-ce31-414f-b7e8-41653ea9f195",false,10))
    <li>$content.title</li>
#end
</ul>

Example 5: pullRelated (Legacy Relationship) with Condition and Sort

The following example adds a query condition ("someField:someValue") and a sort order ("modDate") to sort the returned items by modification date.

<ul>
#foreach($content in $dotcontent.pullRelated("relationshipName","identifier","+someField:someValue",false,10,"modDate"))
    <li>$content.title</li>
#end
</ul>