Pull and Display Related Content

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).
  • If you wish to filter or sort the related content, please use the Content Tool Velocity methods instead.

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

Relationship Names (Legacy Relationships)

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.

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</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 the same Employees for a given location, using a $dotcontent.pullRelated() method call. The Identifier of the Location is passed in directly as a Velocity variable from the $location object. Since no sort order is specified, the returned items will be returned in the default order (the same order they are displayed in the list of related content, when viewing each Location in the content editing screen).

#foreach( $location in $dotcontent.pull( "+contentType:Location", 3, "title asc" ) )
    <h3>$location.title</h3>
    <h4>Employee(s):</h4>
    <ul>
        #foreach( $content in $dotcontent.pullRelatedField( "$location.identifier", "Location.employee", "*" ) )
            <li>$content.firstName $content.lastName</li>
        #end
    </ul>
#end

Example 3: pullRelatedField with Condition and Sort

The following example builds on the previous example by adding both a condition (which limits restults to only sales employees), and a sort order ("Employee.lastName") to sort the returned items by last name:

#foreach( $location in $dotcontent.pull( "+contentType:Location", 3, "title asc") )
    <h3>$location.title</h3>
    <h4>Employee(s):</h4>
    <ul>
        #foreach( $content in $dotcontent.pullRelatedField( "$location.identifier", "Location.employee", "Employee.function:sales", "Employee.lastName" ) )
            <li>$content.firstName $content.lastName</li>
        #end
    </ul>
#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 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>