Pull and Display Related Content   [$dotcontent.pullRelated]documentation for the dotCMS Content Management System

The pullRelated methods on the ContentTool ($dotcontent.pullRelated()) allow you to retrieve content which is related to another specified piece of content.


The pullRelated method can be called in the following ways, each of which requires different arguments, and modifies the search in some ways:

Method CallDescriptionJavadocs Link
pullRelated(String relationshipName, String contentletIdentifier, boolean pullParents, int limit)Pulls all related content, using the default sort order.Javadocs
pullRelated(String relationshipName, String contentletIdentifier, boolean pullParents, int limit, String sort)Pulls all related content, sorting the results as specified by the sort parameter.Javadocs
pullRelated(String relationshipName, String contentletIdentifier, String condition, boolean pullParents, int limit, String sort)Pulls content which is both related and matches the condition parameter, sorting as specified by the sort parameter.Javadocs


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

Relationship Name

You must specify the relationship name of the relationship you wish to use. The relationship name can be found by viewing the relationship in the Relationships tab.

Contentlet Identifier

You must specify the identifier of the contentlet for which related items will be returned. For example, if you wish to find all parent of a specific document, you must supply the identifier of that document. 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.


The condition field allows you to specify query terms; only content items which match the condition and which are related to the specified contentlet will be returned.


Each relationship specifies a parent-child relationship between content items. The pullParents argument specifies whether or not to pull the parent items of to the specified content. If it is set to "true", all parents of the specified item will be retrieved; if it is set to "false", all children of the specific content will be pulled instead.


Specifies the maximum number of content items to return.


The sort argument takes a string which specifies which field or fields to sort on, and the order of the sort (“asc”, which is the default, or “desc”).


Example 1: Pull Child Items

The following example gets the relationships for a piece of content with Identifier “asbd-asd-asda-asd” and requests return of 10 of the related items. The pullParents argument is set to "false", so the call returns the child items. Since no sort order is specified, the returned items will be ordered by their order on the relationship tab.

#foreach($content in $dotcontent.pullRelated("relationshipName","identifier",false,10))     

Example 2: Pull 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"))

For more information regarding the pullRelated method, please see the ContentTool Javadocs.