View Helpers Link Functions string controller
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. | |
| addActiveClassToPrependedParent | boolean | No | false | |
| 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>