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.

Usage

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( String contentletIdentifier, String fieldVarName, String condition )Pulls all related content which matches the condition, using the default sort order.
Sort ResultspullRelatedField( String contentletIdentifier, String fieldVarName, String condition, String sort )Pulls all related content which matches the condition, sorting as specified by the sort.
Limit ResultspullRelatedField( String contentletIdentifier, String fieldVarName, String condition, String sort, int limit )Pulls at most limit related content items which match the condition, sorting as specified by the sort.
Page ResultspullRelatedField( String contentletIdentifier, String fieldVarName, String condition, String sort, int limit, int offset )Pulls at most limit related content items starting from the specified offset, which match thecondition, sorting as specified by thesort`.

Relationship Names (Legacy Relationships)

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

Parameters

The following arguments are required by different versions of the pullRelated method.

ParameterDescriptionNotes
Relationship NameThe name of the Relationship.The Relationship Name can be found by viewing the Relationship in the Relationships tab.
Contentlet IdentifierThe identifier 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.
ConditionLucene 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.
PullParentsSpecifies 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.
LimitThe maximum number of content items to return. 
SortHow 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.

Pulling Related Content Using a Lucene Query

When using a Relationships Field, you may also pull child content using a normal Lucene query (when using the standard $dotcontent.pull() method, when performing a query via the REST API, or anywhere else a Lucene query can be used. To pull children related to a parent, you perform a pull of the child Content Type, and specify the Identifier of the parent item as a value to the Relationship field on the child Content Type.

Please note that this method is limited in several ways:

  1. It only works for Relationship Fields.
    • It does not work for Legacy Relationships (using Relationship Names).
  2. It only allows pulling children related to a specific parent (or a list of specific parents, separated by a Lucene OR operator).
    • It does not allow pulling parent related to a specific child.
  3. It will only work if the child Content Type has a Relationships Field pointing to the parent.
    • If the parent Content Type has a Relationships field, but the child Content Type does not, this method will not work.
  4. It will only work if the Relationships Field on the child Content Type is set to be User Searchable.
    • Searchable Relationships Field

Because of these limitations, it is recommended that whenever possible you use the $dotcontent.pullRelatedField method instead of a Lucene query (since the pullRelatedField method does not have these limitations).

Examples

Examples Using Relationship Fields

The following examples show how to use the $dotcontent.pullRelatedField() method to pull related content which uses Relationship Fields.

Example 1: 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 “employees”. 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).

#foreach($content in $dotcontent.pullRelatedField("relationshipName","784bebeb-ce31-414f-b7e8-41653ea9f195",false,10))
          $content.title
#end

Example 2: pullRelatedField 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.

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

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 3: 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).

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

Example 4: 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.

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

Example Using a Lucene Query

Example 5: Searching for Related Children Using a Lucene Query

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>Employees Listing (One Related Location)</h2>
#foreach($employee in $dotcontent.pull("+contentType:Employee +(conhost:48190c8c-42c4-46af-8d1a-0cd5db894797 conhost:SYSTEM_HOST) +Employee.location:784bebeb-ce31-414f-b7e8-41653ea9f195",3,"modDate desc"))
    #editContentlet($employee.inode)
    <h3>$!{employee.firstName} $!{employee.lastName}</h3>
    Location: $employee.location.title
#end

<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($list = $!{location.employees})
    Employee(s): 
    #foreach($relatedEmployee in $list)
        $relatedEmployee.firstName $relatedEmployee.lastName#if($foreach.hasNext), #end
    #end
#end

The results of this code are shown below:

Searchable Relationships Field