Back

paginationLinks()

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

Name	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.
prependOnAnchor	boolean	No	true	Whether or not to prepend the prependToPage string on the anchors.
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.
appendOnAnchor	boolean	No	true	Whether or not to append the appendToPage string on the anchors.
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).
pageNumberAsParam	boolean	No	true	Decides whether to link the page number as a param or as part of a route. (The default behavior is true).
encode	any	No	true	Use this argument to decide whether the output of the function should be encoded in order to prevent Cross Site Scripting (XSS) attacks. Set it to `true` to encode all relevant output for the specific HTML element in question (e.g. tag content, attribute values, and URLs). For HTML elements that have both tag content and attribute values you can set this argument to `attributes` to only encode attribute values and not tag content.

//--------------------------------------------------------------------
// Example 1: List authors page by page, 25 at a time

// Controller code
param name="params.page" type="integer" default="1";
authors = model("author").findAll(page=params.page, perPage=25, order="lastName");

// View code
<ul>
    <cfoutput query="authors">
        <li>#EncodeForHtml(firstName)# #EncodeForHtml(lastName)#</li>
    </cfoutput>
</ul>

<cfoutput>#paginationLinks(route="authors")#</cfoutput>


//--------------------------------------------------------------------
// Example 2: Using the same model call above, show all authors with a
// window size of 5

// View code
<cfoutput>#paginationLinks(route="authors", windowSize=5)#</cfoutput>


//--------------------------------------------------------------------
// Example 3: If more than one paginated query is being run, then you
// need to reference the correct `handle` in the view

// Controller code
authors = model("author").findAll(handle="authQuery", page=5, order="id");

// View code
<ul>
    <cfoutput>
        #paginationLinks(
            route="authors",
            handle="authQuery",
            prependToLink="<li>",
            appendToLink="</li>"
        )#
    </cfoutput>
</ul>


//--------------------------------------------------------------------
// Example 4: Call to `paginationLinks` using routes

// Route setup in config/routes.cfm
mapper()
    .get(name="paginatedCommentListing", pattern="blog/[year]/[month]/[day]/[page]", to="blogs##stats")
    .get(name="commentListing", pattern="blog/[year]/[month]/[day]", to="blogs##stats")
.end();

// Controller code
param name="params.page" type="integer" default="1";
comments = model("comment").findAll(page=params.page, order="createdAt");

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