dotCMS logodotCMS logo

Paginated Pull and Display of Contents — $dotcontent.pullPerPage

The $dotcontent.pullPerPage() method enables you to pull contents using a Lucene query, specifying a limit to the number of results returned and an offset into the results. This allows you to create a paginated list, pulling a single specific page of results from the query each time a user displays the page.

Usage#

The pullPerPage method can be called in the following two ways:

$dotcontent.pullPerPage( query, pagenum, limit [, sort] )
$dotcontent.pullPagenated( query, limit, offset [, sort] )

Where:

ParameterDescription
queryThe Lucene query string.
pagenumThe page of items to return; The first item returned will be item number equal to (((page-1) * limit) + 1).
i.e., if limit is 10, then 1 = Start with the first item, 2 = Start with item #11, etc.
Note: If you enter a number less than 1 for the page, page 1 will be retrieved.
offsetThe offset of the first search result to return; The first item returned will be item number (offset + 1).
i.e., 0 = Start with the first item, 10 = Start with item #11, etc.
limitThe maximum number of search results (content items) to return.
sortThe field(s) used to sort the results.

Note:

  • Both methods perform a paginated pull.
    • They do the same thing but one works from the perspective of contents per page while the other just takes an offset and limit.
  • However it is usually easier to use the pullPerPage() method, since:
    • It eliminates the possibility of accidentally miscalculating the offset for the appropriate page of results.
    • It provides properties which give additional information about the number of items and pages in the results.

###Usage Example {#UsageExample}

The following example retrieves the 3rd page of results, when displaying 10 items per page:

    #foreach($content in $dotcontent.pullPerPage("+contentType:News", 3, 10, "modDate"))
        <h2>$content.title</h2>
    #end

Examples#

The following additional examples demonstrate additional capabilities of the pullPerPage() method, and show more complete examples of how to use the method to create a fully working paginated content list page.

Example: Display Pagination Status#

If you set the direct output of the pullPerPage() method to a variable, you can also retrieve the following values from the variable (in addition to the list of content items that match the query): nextPage, previousPage, totalPages, and totalResults:

PropertyTypeDescription
previousPageBooleanTrue if there is a page of results prior to the page retrieved.
nextPageBooleanTrue if there is a page of results following the page retrieved.
totalPagesIntegerThe total number of pages in the query results.
totalResultsIntegerThe total number of items in the query results (on all pages).
#set($results = $dotcontent.pullPerPage("+contentType:webPageContent", 3, 20, "modDate desc"))
<div>
     <p>$results</p>
</div>
<h2>Navigation Values:</h2>
<ul>
    <li>previousPage: $results.previousPage</li>
    <li>nextPage: $results.nextPage</li>
    <li>totalPages: $results.totalPages</li>
    <li>totalResults: $results.totalResults</li>
</ul>
#foreach($content in $results)
    <h2>$content.title</h2>
    <h4>$content.inode</h4>
    <h4>$content.identifier</h4>
    <p>$content</p>
#end

Example: Previous Page and Next Page Links#

The following example performs full page handling, including:

  • Checking to see if a "page" parameter has been set in the page URL.
  • Setting the value of a $page parameter to specify what page of results to display.
  • Pulling and displaying the paginated contents.
  • Displaying Previous Page and Next Page buttons.
    • The values of the previousPage and nextPage properties are checked to ensure that these links are only displayed if there is a previous or next page of results available.
#set($page = 1)
#if($request.getParameter("page"))
    #set($page = $page.parseInt($!request.getParameter("page")))
#end

#set($results = $dotcontent.pullPerPage("+contentType:JmtMovies", $page, 10, "title"))

#foreach($content in $results)
    #editContentlet($content.inode)
    <h2>$content.title</h2>
#end

<p>Page $page of $results.totalPages ($results.totalResults results)</p>
<h4>
#if($results.previousPage)
    <a href="$!request.getRequestURI()?page=$math.sub($page,1)">Previous</a>
#end
#if($results.nextPage)
    <a href="$!request.getRequestURI()?page=$math.add($page,1)">Next</a>
#end
</h4>

Notes:

  • The #editContentlet() macro allows content editors to edit the returned content items inline while viewing the page (without having to return to the Content Search screen).
  • The appropriate URL is constructed by retrieving the URI of the current page using the getRequestURI() method of the $request object.
  • The appropriate page numbers are calculated using the MathTool Velocity Viewtool.
    • For more information, please see the MathTool documentation.