Plugin: Search results pagination

Purpose

Use this plugin to when you wish to customize your pagination control in the search results.

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.

This plugin can be used with Freemarker templates as well as your own integrations with the search results data model.

Usage

Enable the plugin

  1. Select Plugins from the side navigation pane and click on the Search results pagination tile.

  2. From the Location section, select the results page to which you would like to enable this plugin from the Select a results page select list.

The plugin will take effect as soon as you finish running through the plugin setup steps.

Configuration settings

The configuration settings section is where you do most of the configuration for your plugin. The settings enable you to control how the plugin behaves.

The configuration key names below are only used if you are configuring this plugin manually. The configuration keys are set in the results page configuration to configure the plugin. When setting the keys manually you need to type in (or copy and paste) the key name and value.

Configuration key

plugin.pagination.config.first.label

Data type

string

Default value

First

Required

This setting is optional

Label to display for the first page control.

Configuration key

plugin.pagination.config.previous.label

Data type

string

Default value

Prev

Required

This setting is optional

Label to display for the previous page control.

Configuration key

plugin.pagination.config.next.label

Data type

string

Default value

Next

Required

This setting is optional

Label to display for the next page control.

Configuration key

plugin.pagination.config.pages.show

Data type

integer

Default value

5

Required

This setting is optional

Defines the number of direct page links which should be displayed in the pagination control.

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, the Freemarker template below provides the ability to use a simple macro to present the pagination control. This macro removes the business logic (which calculated the previous/next links) contained in the default pagination macro, and the template can easily be customized to match your requirements.

<#--
  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

Examples

Provide a pagination control with custom labels

This configuration will customize the pagination to provide customized labels:

Configuration key name Value

First page link label

<<

Previous page link label

<

Next page link label

>

The plugin will add the following to the customData element in the search 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
            }
          ]
        }
      }
    }
  }
}

To display a pagination control that only includes two direct page links similar to:

First Prev …​ 5 6 …​ Next

Add the following plugin configuration:

Configuration key name Value

Number of go to page links

2

This will 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
            }
          ]
        }
      }
    }
  }
}

Change log

[1.1.0]

Changed

  • Updated to the latest version plugin framework (Funnelback shared v16.20) to enable integration with the new plugin management dashboard.