Paginated Pull and Display of Contents   [$dotcontent.pullPerPage]

Last Updated: Jun 3, 2020
documentation for the dotCMS Content Management System

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.


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

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


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.


  • 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

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"))


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:

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"))
<h2>Navigation Values:</h2>
    <li>previousPage: $results.previousPage</li>
    <li>nextPage: $results.nextPage</li>
    <li>totalPages: $results.totalPages</li>
    <li>totalResults: $results.totalResults</li>
#foreach($content in $results)

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)
    #set($page = $page.parseInt($!request.getParameter("page")))

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

#foreach($content in $results)

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


  • 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.

On this page


We Dig Feedback

Selected excerpt: