Pulling and Displaying Content — $dotcontent.pull

All your dotCMS content can be accessed and reused either individually or by dynamically pulling content from the content store. Dynamic content pulls are accomplished using various different methods of the $dotcontent viewtool, which allows you to perform Lucene queries of your content store and access and display all the individual content items returned by the query.

Note that while this page details the use of this general tool, in most cases it is recommended to use one of the three built-in content objects instead, for convenience and simplicity.

Methods

Standard Content Pull

You can call the standard $dotContent.pull() method as follows:

Additional Methods

In addition, the $dotContent tool provides many other methods which allow you to pull content in different ways. Please see the documentation on each of the following types of content pulls for more information:

Results of a Content Pull

When you perform a content pull, each individual content item in the query results is returned as a ContentMap object. The object holds a reference to the value of each field defined by the Content Type for the given content object. Each individual field is accessible from the resulting object as a property with the name of the Variable Name assigned to the field in the Content Type.

For example, if a Content Type has a field named “My Title” with a Variable Name myTitle, then when you perform a content pull of items of this Content Type, you can access the “My Title” field with a reference of the form $resultObject.myTitle. This works for any field of a Content Type, including but not limited to Text, Select, Category, Tag, File, Image, and Binary.

For Image, Binary, and File fields, the value of the field in the content object (e.g. $resultObject.myImage) is a special object that makes it easy to get at different properties of the image or file (e.g. $resultObject.myFile.uri or $resultObject.myImage.width).

• For Binary fields, a BinaryMap Object is returned.
• For Image and File fields, a FileMap object is returned.
• For Category fields, a list of Categories is returned.
• For Tag fields, a list of strings is returned (one string for each Tag).
• For Host, Multi-select, Select, Checkbox, and Radio Button fields, appropriate objects are returned to allow you to access properties of the objects (including, for various types of selection fields, both lists of all possible selections and the selections that were made for the particular content object which was returned).

NOTE:

• All returned content objects can be output directly to the Page when developing.
  • Objects output directly are displayed as JSON objects, with all fields broken out, so you can see what fields of the object can be accessed.
  • Example: <p>$contentMap.myFile</p>
    
• All queries passed to the $dotcontent tool will have default value set for the language ID, and live, working, and deleted flags if you do not explicitly include those in your query.
  • The languageId parameter will be set appropriately for whatever language has been set when the Page is viewed. To set it manually, include an explicit argument such as +languageId:1.
  • The live, working, and deleted flags will be set appropriately for whatever mode you are viewing the content in.
    • For example in EDIT MODE +working:true will be appended automatically unless you specifically include the live or working fields in your query.

Examples

The following examples demonstrate how to use the $dotcontent.pull() method. For examples on how to perform content pulls using other $dotcontent methods, please see the documentation for the appropriate methods.

Simple Sorted Content Pull

The following code pulls and displays the headers of the 10 content items of the “News” Content Type that were most recently modified. The query ("+contentType:News") specifies the Content Type, the sort parameter ("modDate desc") specifies that content items should be sorted by last modification date, in descending order, and the number (10) specifies that only the first 10 (sorted) items should be returned.

#foreach( $news in $dotcontent.pull("+contentType:News",10,"modDate desc") )
    <h3>$news.title</h3>
    <p>$news.tags</p>
#end  

Pull and Display Categories

In this example headline is a field on the news. We can display the category on news within the loop this way. $con.newsType where newsType is a Category field. The output would be:

[com.dotmarketing.portlets.categories.model.Category@69942395[categoryName=Press Release,description=,key=pr,sortOrder=0,active=true,keywords=,categoryVelocityVarName=categoryType11]]

This shows an Array of Categories. We can then use a #foreach loop to iterate over them and display information about each category, such as the categoryName.

Displaying the Contents of a Field Type

When you display Text fields and Text Area fields, the value of the field is returned as a text string which can be displayed directly. However when you access the value of other fields (such as Select, Radio and Checkbox fields), the values are not simple text strings, since these fields have structured formats that include additional information.

Since content items are returned as content maps, any time you want to find out what values are available for any field you may just display the field itself; all the properties available for the field will be displayed as a content map, which you can then use to determine which property of the field you wish to access.

For example, the following code displays the contents of a query against the “News” Content Type contained in the dotCMS starter site, and displays the contents of the “Tags” field:

#foreach( $news in $dotcontent.pull("+contentType:News",10,"modDate desc") )
    <h3>$news.title</h3>
    <p>[
    #foreach( $tag in $news.tags )
        ${tag}#if( $foreach.hasNext() ), #end
    #end
    ]</p>
#end  

The code outputs the following on the page:

<h3>Find the 401k investing strategy for you</h3>
<p>[etfs, firsttimeinvestor, fund, investing]</p>

<h3>Why is your cable TV bill is going up?</h3>
<p>[firsttimeinvestor, retiree]</p>

<h3>Hidden Fees in ETFs can take a Bite out of your Wallet</h3>
<p>[etfs, firsttimeinvestor, investing]</p>

The result shows that the Tags field type contains a list of all the tags assigned to a piece of content. We can now change our code to list each of the tags in a more user-friendly format:

#foreach( $news in $dotcontent.pull("+contentType:News",10,"modDate desc") )
    <h3>$news.title</h3>
    <p><b>Tags:</b> 
    #foreach( $tag in $news.tags )
        ${tag}#if( $foreach.hasNext() ), #end
    #end
    </p>
#end  

This new code outputs the following on the page:

<h3>Find the 401k investing strategy for you</h3>
<p><b>Tags:</b> etfs, firsttimeinvestor, fund, investing</p>

<h3>Why is your cable TV bill is going up?</h3>
<p><b>Tags:</b> firsttimeinvestor, retiree</p>

<h3>Hidden Fees in ETFs can take a Bite out of your Wallet</h3>
<p><b>Tags:</b> etfs, firsttimeinvestor, investing</p>

Comments, Radio, Select, Host, and Mult-select Fields

The following code displays several different types of common fields used in Content Types. The Comments field is a Select Field. The Select, Radio, Multi Select and Checkbox all allow you to get at the possible options and values as well as the selected values. Again here the field is printed to the screen so you can see what is available to get at.

#foreach($con in $dotcontent.pull("+contentType:News",10,"modDate desc"))
     <p>COMMENTS : $con.comments</p>
##The host will return the actual contentMap of the host content.
     <p>HOST : $con.host</p>
     <p>MULTI : $con.multi</p>
     <p>HOST FIELD : $con.contentHost</p>
     <p>CHECKBOX : $con.checkbox</p>
#end  

Pulling Content Identifiers Without Content Objects

The $dotcontent.query() method allows you to pull lists of content that match a query, but returns strings of the content inode and identifier, rather than the entire content object. This may be useful to pull lists of content which don't need to be displayed immediately, such as by an external application pulling dotCMS content via REST API calls.

The $dotcontent.query() method uses the exact same syntax as the standard $dotcontent.pull() method](), only the name of the method changes. The query method returns a list of ContentletSearch Objects, which contain only the Inode and Identifier of the search results, each represented as strings.

#set($results =  $dotcontent.query("+contentType:News",10,"modDate desc"))
#if($results.size()>0)
    ...
#end

Counting Matching Content

You can get a count of content that matches a query without returning the content objects using the $dotcontent.count() method. The method takes only the Lucene query as a parameter, and returns an integer indicating the number of content items which match the query.

For example, the following will print the conditional block if more than one News Content Type in the default language exists in a draft state.

#if($dotcontent.count("+contentType:News +languageId:1 +working:true" > 0))
    $content.title
#end

Pulling Content by Identifier or Inode

You can use the $dotcontent.find() method to retrieve a single content item by either its inode or identifier.

The $dotcontent.find() method has better performance than a Lucene query (even when the Lucene query specifically uses the same inode or identifier), because the $dotcontent.find() method pulls the inode from a cache, rather than searching the index.

The $dotcontent.find() method can take either the inode or identifier of the content object, and will automatically determine whether it is an inode or an identifier (you do not need to specify which it is).

The following example retrieves the content object for a content item with an identifier of 48190c8c-42c4-46af-8d1a-0cd5db894797 and an inode of 98683629-e1eb-4b3f-a5a6-5a084c6b0209. Both calls return the exact same content object.

**Find By Identifier**
 $dotcontent.find('48190c8c-42c4-46af-8d1a-0cd5db894797')

 **Find by inode**
 $dotcontent.find('98683629-e1eb-4b3f-a5a6-5a084c6b0209')