Skip to main content

Pagination

info
  • HTML tag name: <builderius-pagination>
  • Implements 3rd-party script: none
  • Allowed children modules: Template
  • Available since: 0.9.7 PRO

Description​

This module allows creating pagination for the Collection module.

How it works​

The module creates <builderius-pagination> custom HTML tag. It is a modular self contained instance of custom JS script.

tip

Since <builderius-pagination> is a custom HTML element, its default behavior is equal to inline element, not block; it can be changed any time with display CSS property.

The Collection module is a perfect solution for displaying a set of data, like related posts or comments etc. However, there might be a huge amount of data, like 50 or 150 posts etc. The Pagination module helps splitting items rendered by the Collection into pages. This leads to easier navigation and better UX.

First, the Pagination module should be placed outside the Collection module. Second, the connection between these two could be established by adding data-subscribe-pagination-selector attribute to the Collection module. The value of this attribute must be a CSS selector for the Pagination module. Third, we should configure the Pagination module itself. We use data-settings attribute with a stringified JSON object - example {"perPage":5} - to set the number of items which must be displayed per each page. Next, we add the Template module and set up the desired template. It could be an unordered list or just anchors etc. Our example uses the unordered list. The Pagination module that works in conjunction with a specific Collection is always aware of the total number of items of the Collection. Next, the Pagination module’s script creates an internal array of data that looks like this:

{
    items: [
        {page: 1},
        {page: 2, active: true},
        {page: 3}
    ]
}

Based on this knowledge we build our template accordingly. In order to display the page number we write {{page}} inside the GenericInline module (again, this explanation is based on our example; the specific module name is not that important here as it could be a different one!). Now we have a list of pages rendered. However, clicking on these items does nothing yet!

info

In order to make the page navigation work and change the page we have to add an attribute data-page with value {{page}} to our GenericInline module!

Hooray! The page navigation works now! There is only one small but important thing - how to detect the current active page we are on? Again, we should use an attribute data-page-active with the value {{{active ? true : false}}}. Now, all items have these attributes, but they are also set to falseexcept the current one. So we use a custom CSS selector [data-page-active=”true”] for the page navigation element and style it differently.

API​

Attributes for Collection​

data-subscribe-pagination-selector (required)​

This attribute expects a valid CSS selector to the Pagination module

Attributes for Pagination​

data-settings (required)​

This attribute expects a stringified JSON object with the key perPage with a numeric value.

Attributes for the page navigation module​

data-page (required)​

This attribute expects an expression equal to {{page}}.

Events​

ready (scope: element)​

builderius-pagination-ready (scope: window)​

This event is getting fired every time the component is being initiated/re-initiated. It also passes some data:

{ el }

Where el is the reference to the HTML element.

change (scope: element)​

builderius-pagination-change (scope: window)​

This event is getting fired every time the page is being changes both by click on the pagination element or programmatically by using goTo method. It also passes some data:

{ el, current, perPage}

Where el is the reference to the HTML element, current is the numeric value of the current page and perPage is the numeric value of the setting that is set for the module.

Methods​

reInit​

This method resets and initiates the component.

goTo​

This method accepts a numeric value. It can be used to change the page programmatically.

setTotalItems​

This method accepts a numeric value. It can be used to update the total numbers of items which must be paginated. This method triggers re-render of the component.

Demo​

Demo page