Plugin: pagination
| Other versions of this plugin may exist. Please ensure you are viewing the documentation for the version that you are currently using. If you are not running the latest version of your plugin we recommend upgrading. See: list of all available versions of this plugin. |
Purpose
This plugin assists with the customization of search results pagination elements by adding relevant pagination links and labels to the search data model.
The plugin removes the need to write custom logic to generate the links required for the previous and next search results pages and also provides a number of configurable items such as the labels that should be associated with the links.
This makes it very easy to provide a customized pagination element in a search results page, regardless of which endpoint is being accessed. This means that you can integrate with the JSON or XML endpoint and not have to perform custom logic to enable a pagination element.
Usage
Enabling the plugin
Enable the pagination plugin on your results page from the Extensions screen in the administration dashboard or add the following results page configuration to enable the plugin.
plugin.pagination.enabled=true
plugin.pagination.version=1.0.1| The plugin will take effect as soon as it is enabled. |
Plugin configuration options
The following options can be set in the results page configuration to configure the plugin:
-
plugin.pagination.config.first.label: Defines the label of the first page button. Default isFirst. -
plugin.pagination.config.previous.label: Defines the label of the next page button. Default isPrev. -
plugin.pagination.config.next.label: Defines the label of the previous page button. Default isNext. -
plugin.pagination.config.pages.show: Defines the number of pagination pages which should be displayed. Default is5.
The above can be applied at either the search package or results page level. Any option that set at the search package level will be defined on all child results pages unless overridden.
|
Details
Once enabled, the pagination plugin generates a pagination object with the response.customData element of the search data model:
{
"response": {
"customData": {
"stencils": {
"pagination": {
"first": {
"label": "First",
"url": "<url>"
},
"previous": {
"label": "Prev",
"url": "<url>"
},
"next": {
"label": "Next",
"url": "<url>"
},
"pages" : [
{
"label": "1",
"url": "<url>",
"selected": false
},
...
{
"label": "5",
"url": "<url>",
"selected": true
}
]
}
}
}
}
}The number of response.customData.stencils.pagination.pages sub-elements is determined by the plugin.pagination.config.pages.show configuration option.
If you are using the FreeMarker templated html, this provides the ability to use a simple macro to present the pagination control. This macro removes the business logic (which calculated the previous/nexct links) contained in the default pagination macro.
<#--
Display paging controls
-->
<#macro Paging>
<!-- base.Paging -->
<section class="pagination">
<nav class="pagination__nav" role="navigation" aria-label="Pagination navigation">
<#-- Previous page -->
<#if (response.customData.stencils.pagination.previous)??>
<div class="pagination__item pagination__item-navigation pagination__item-previous">
<a class="pagination__link"
rel="prev"
href="${(response.customData.stencils.pagination.previous.url)!}">
<span class="sr-only">
Go to the
</span>
<span class="pagination__label">
${(response.customData.stencils.pagination.previous.label)!"Prev"}
</span>
<span class="sr-only">
page
</span>
</a>
</div>
</#if>
<#-- Sibling pages -->
<#if (response.customData.stencils.pagination.pages)!?has_content &&
response.customData.stencils.pagination.pages?size gt 1>
<ul class="pagination__pages-list">
<#list response.customData.stencils.pagination.pages as page>
<#if page.selected>
<li class="pagination__item pagination__item--active" aria-current="page">
<span class="pagination__current">
<span class="pagination__label">${page.label}</span>
</span>
</li>
<#else>
<li class="pagination__item">
<a class="pagination__link" href="${page.url}">
<span class="sr-only">
Go to page
</span>
<span class="pagination__label">${page.label}</span>
</a>
</li>
</#if>
</#list>
</ul>
</#if>
<#-- Next page -->
<#if (response.customData.stencils.pagination.next)??>
<div class="pagination__item pagination__item-navigation pagination__item-next">
<a class="pagination__link"
rel="next"
href="${(response.customData.stencils.pagination.next.url)!}">
<span class="sr-only">
Go to the
</span>
<span class="pagination__label">
${(response.customData.stencils.pagination.next.label)!"Next"}
</span>
<span class="sr-only">
page
</span>
</a>
</div>
</#if>
</nav>
</section>
</#macro>Similar logic can be applied to build a pagination control when accessing the search results JSON or XML endpoints.
Examples
Change the labels
plugin.pagination.config.first.label=<<
plugin.pagination.config.previous.label=<
plugin.pagination.config.next.label=>will result in the following being returned in the data model:
{
"response": {
"customData": {
"stencils": {
"pagination": {
"first": {
"label": "<<",
"url": "<url>"
},
"previous": {
"label": "<",
"url": "<url>"
},
"next": {
"label": ">",
"url": "<url>"
},
"pages" : [
{
"label": "1",
"url": "<url>",
"selected": false
},
...
{
"label": "5",
"url": "<url>",
"selected": true
}
]
}
}
}
}
}Decrease the number of pages to show
plugin.pagination.config.pages.show=2will result in the following being returned in the data model:
{
"response": {
"customData": {
"stencils": {
"pagination": {
"first": {
"label": "First",
"url": "<url>"
},
"previous": {
"label": "Prev",
"url": "<url>"
},
"next": {
"label": "Next",
"url": "<url>"
},
"pages" : [
{
"label": 1,
"url": "<url>",
"selected": false
},
{
"label": 2,
"url": "<url>",
"selected": true
}
]
}
}
}
}
}