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:
Parameter | Description |
---|---|
query | The Lucene query string. |
pagenum | The 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. |
offset | The 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. |
limit | The maximum number of search results (content items) to return. |
sort | The 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:
Property | Type | Description |
---|---|---|
previousPage | Boolean | True if there is a page of results prior to the page retrieved. |
nextPage | Boolean | True if there is a page of results following the page retrieved. |
totalPages | Integer | The total number of pages in the query results. |
totalResults | Integer | The 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).- For more information, please see the Editing Pulled Content documentation.
- The appropriate URL is constructed by retrieving the URI of the current page using the
getRequestURI()
method of the $request object.- For more information, please see the Request, Response and Session documentation.
- The appropriate page numbers are calculated using the MathTool Velocity Viewtool.
- For more information, please see the MathTool documentation.