Pulling and Displaying Content   [$dotcontent.pull] - Documentation topics on: content pull,dotcontent tool,dynamic pull,pulling and displaying content,.

This documentation is a static copy for this version. For current documentation, see: http://dotcms.com/docs/latest

Pulling and Displaying Content   [$dotcontent.pull]

Protip - use the “show query” button on the content search screen to display and build your dynamic content queries

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 tool, which allows you to perform Lucene queries of your content store and access and display all the individual content items returned by the query.

When you perform a content pull, each individual content item in the query results is presented to the developer 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 “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 $object.myTitle. This works for any field of a Content Type, including but not limited to Text, Select, Category, Tag, File, Image, and Binary.

In the case of the Image, Binary, and File fields - $contentMap.myImage returns a special object to make it easy to get at different properties of the field. ie… $contentMap.myFile.uri or $contentMap.myImage.width. For Binary a BinaryMap Object is returned. For Image and File a FileMap object is returned. For a Category field a list of Categories is returned.
In addition to the file, image and category fields there are other fields which return helper objects for you. They are Tag, Host, Multi, Select, and Radio. On the host you can always do a $con.host.

NOTE: All these objects can be split to the screen when developing showing you what can be accessed. ie… $contentMap.myFile

NOTE: All Queries passed to the $dotcontent tool will get the language, live, working, and deleted options set if you do not pass them in. For example in EDIT MODE +working:true would be appended unless you specifically pass in live or working. Same with deleted and the languageId

Methods

You can call the standard $dotContent.pull() method in the following ways:

MethodReturn ValueDescription
$dotcontent.pull()$list()Array list of all content retrieved by the pull

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:

MethodDescription
$dotcontent.pullPerPage()Paginated content pulls.
$dotcontent.pullRelated()Pull content based on relationships.
$dotcontent.pullPersonalized()Pull content lists personalized for individual users.
$dotcontent.find()Find an individual content item by identifier.

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",3,"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",3,"modDate desc") )
    <h3>$news.title</h3>
    <p><b>Tags: </b>
    #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",3,"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  

dotcontent.query VS dotcontent.pull

You can use the exact same syntax as the pull example replacing pull with query. This will return to you a List of ContentletSearch Objects. The Objects only have a reference to the Inode and Identifier of the search results. This is useful when you don't need to display data but only query the Content Repository to test if a query returns any results or the number of results.

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

The query returns to you a List of Objects with the inode and identifier represented as Strings.

Getting a Content Count

An easy way to get a count (as oppossed to the example above), would be to use the helper method count(String query) on the dotcontent tool. The count method returns an integer

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

Pulling One piece of Content by Identifier or Inode

You can also use the content tool to look up a piece of content by either its identifier or inode. Using the dotcontent.find method rather than a query will be more performant, as the dotcontent.find method pulls the correct inode from a cache, rather than hitting the index. Ths $dotcontent.find method takes either the inode or identifier of the content object. Consider the below example where a piece of content has an identifier of 48190c8c-42c4-46af-8d1a-0cd5db894797 and an inode of 98683629-e1eb-4b3f-a5a6-5a084c6b0209. Both would return the exact same content.

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

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