paginationLinks()

Description

Builds and returns a string containing links to pages based on a paginated query. Uses linkTo() internally to build the link, so you need to pass in a route name or a controller/action/key combination. All other linkTo() arguments can be supplied as well, in which case they are passed through directly to linkTo(). If you have paginated more than one query in the controller, you can use the handle argument to reference them. (Don't forget to pass in a handle to the findAll() function in your controller first).

Function Syntax

paginationLinks([ windowSize, alwaysShowAnchors, anchorDivider, linkToCurrentPage, prepend, append, prependToPage, prependOnFirst, appendToPage, appendOnLast, classForCurrent, handle, name, showSinglePage ])

Parameters

Parameter Type Required Default Description
windowSize numeric No 2 The number of page links to show around the current page.
alwaysShowAnchors boolean No true Whether or not links to the first and last page should always be displayed.
anchorDivider string No ... String to place next to the anchors on either side of the list.
linkToCurrentPage boolean No false Whether or not the current page should be linked to.
prepend string No String or HTML to be prepended before result.
append string No String or HTML to be appended after result.
prependToPage string No String or HTML to be prepended before each page number.
prependOnFirst boolean No true Whether or not to prepend the prependToPage string on the first page in the list.
appendToPage string No String or HTML to be appended after each page number.
appendOnLast boolean No true Whether or not to append the appendToPage string on the last page in the list.
classForCurrent string No Class name for the current page number (if linkToCurrentPage is true, the class name will go on the a element. If not, a span element will be used).
handle string No query The handle given to the query that the pagination links should be displayed for.
name string No page The name of the param that holds the current page number.
showSinglePage boolean No false Will show a single page when set to true. (The default behavior is to return an empty string when there is only one page in the pagination).

Examples

<!--- controller code --->
<cfparam name="params.page" default="1">
<cfset allAuthors = model("author").findAll(page=params.page, perPage=25, order="lastName")>

<!--- view code --->
<ul>
<cfoutput query="allAuthors">
<li>#firstName# #lastName#</li>
</cfoutput>
</ul>
<cfoutput>#paginationLinks(action="listAuthors")#</cfoutput>

<!--- view code --->
<cfoutput>#paginationLinks(action="listAuthors", windowSize=5)#</cfoutput>


<!--- controller code --->
<cfset allAuthors = model("author").findAll(handle="authQuery", page=5, order="id")>

<!--- view code --->
<ul>
<cfoutput>#paginationLinks(action="listAuthors", handle="authQuery", prependToLink="<li>", appendToLink="</li>")#</cfoutput>
</ul>


<!--- route setup in config/routes.cfm --->
<cfset addRoute(name="paginatedCommentListing", pattern="blog/[year]/[month]/[day]/[page]", controller="theBlog", action="stats")>
<cfset addRoute(name="commentListing", pattern="blog/[year]/[month]/[day]", controller="theBlog", action="stats")>

<!--- controller code --->
<cfparam name="params.page" default="1">
<cfset comments = model("comment").findAll(page=params.page, order="createdAt")>

<!--- view code --->
<ul>
<cfoutput>#paginationLinks(route="paginatedCommentListing", year=2009, month="feb", day=10)#</cfoutput>
</ul>