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( 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, sort, limit )Pulls at most limit related content items which match the condition, sorting as specified by the sort.
Page ResultspullRelatedField( contentletIdentifier, relationshipFieldVar, condition, sort, limit, offset )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

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

ParameterTypeDescriptionNotes
relationshipNameStringName of the Relationship.The Relationship Name can be found by viewing the Relationship in the Relationships tab.
relationshipFieldVarStringVelocity variable name of the Relationship field.
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

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 “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).

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

Example 2: pullRelatedField with Condition and Sort

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

#foreach($content in $dotcontent.pullRelatedField("784bebeb-ce31-414f-b7e8-41653ea9f195","product","+productName:*laptop*","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

(Deprecated) 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 related to a list of specific parents, separated by a Lucene OR operator).
    • It does not allow pulling parents 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).