Intermediate

Paging

Paging helps present numerous items from the dataset dividing them into groups to display on separate pages. It is used in conjunction with data-presenting components like dataview, datatable and list.

Pager can be initialized as

  • separate ui-related component (should be linked to a component to enable paging);
  • as property of the component it is used for.

In both cases pager can be placed into its own HTML container different from that of the associated component.

Main properties of a pager object:

  • size - the number of records per page;
  • group - the number of pages (numbered squares for paging);
  • page - sets the page that will be shown initially (zero-based numbering).

If a component container is too small to display the number of items specified by size, a scrollbar appears.

Related sample:  Paging animation

Paging and Dynamic Loading

With dynamic loading, only part of the stored records are loaded into the component during initialization. Each time you page through the component, a data request is sent to server to load the next portion of data.

Related sample:  Dynamic paging. Loading from DB

Read more about dynamic loading.

Pager as separate view

In this case pager is initialized as separate component in layout and is linked to the datatable by ID.

webix.ui({
    rows:[
        { 
            view:"datatable",
            columns:[ ...],
            pager:"pagerA", //linking to a pager
        },
        {
            view:"pager", id:"pagerA",
            size:50,
            group:5
        }
    ]
})

Related sample:  Visible Pager in Layout

In this case when pager is a standalone view size property can be combined with either limit or count property to set the total values for the pager, namely:

  • limit - the total number of pages in pager. The number of records will be calculated automatically.
  • count - the total number of records the pager will process. The number of pages will be calculated automatically.

You can as well use Webix pager as a separate entity without master component and provide fully custom login for it - go to the end of the article for details.

Pager as component property

Here pager object appears to be the property of a datatable and includes two parameters of its own.

webix.ui({
    view:"datatable",
    columns:[...],
    pager:{
        size:50,
        group:5
    }
});

Related sample:  Visible pager

Several Pagers per Component

If you want more than one pager for the component, for instance the ones above and below the view, there should be two containers in HTML layout, or two views with pager instances. The two pagers must be linked to each other with the help of the clone method.

You can clone both standalone pagers and those included into the component constructor.

Cloning a standalone pager

//an identical pager
$$("pagerA").clone($$("pagerB")); 
 
//a pager with some properties of its own
$$('pagerA').clone({
    container:"pagingB_here",
    size:50,
    group:5
});

Related sample:  Two-area pager

With a component pager you need to get the pager object with the getPager() method:

Cloning a component pager

grida.getPager().clone({
    container:"paging_here_too",
    size:10,
    group:5
});

Related sample:  Defining several pagers on a page

Cloned pagers will change their values simultaneously!

Invisible pager

Paging can be implemented through an invisible pager, which gives you an ability to control the process by custom functions and create your own "Next/Previous Page", "Jump to Start/End" buttons, etc. instead of a standard pager.

For these needs you should include apiOnly parameter with true value into the pager constructor, whether it is initialized as a separate view or as a component's property.

Datatable with Invisible Pager

view:"datatable",
...
pager:{
    id:"pagerA",
    apiOnly:true, //makes pager invisible
    size:50,
    group:5
}

In this case, dedicated buttons will help us page:

Next Page Button

<input type='button' value='next page' onclick='next_page()'>
...
function next_page(){
    $$("pagerA").select("next");
}

Related sample:  Not-visible pager

The select() function can take the index of the desired pager (zero-based numbering,) or its order ("next", "prev", "first", "last").

Custom Templates for Paging

By default, pager looks as numbered squares accompanying the component . But at the same time you can change the pattern with the help of a custom template:

Template elements may include the following elements:

  • {common.prev()} - 'less-than' sign, directs to previous page;
  • {common.first()} - double 'less-than' sign, directs to the first page;
  • {common.next()} - 'greater-than' sign, directs to the next page;
  • {common.last()} - double 'greater-than' sign, directs to the last page;
  • {common.page()} - displays the number of the current page (starting from 1);
  • {common.pages()} - displays a set of numbered squares;
  • pager data elements (e.g. '#limit#' to display the total number of pages);
  • standard text.
pager: {
    template: "{common.prev()}{common.next()}Page {common.page()} from #limit#"
}

Related sample:  Custom Pager Template

HTML Custom Pager

You can use HTML elements as a base for a custom pager that includes both HTML tags and pager properties in its template.

Properties of the component pager are stored in the data object, pager templates reside in the common object:

  • data.page - the index of the current page(zero-based numbering);
  • data.size - the number of data records per page (either set manually, or calculated on the base of component size)
  • data.limit - the number of record processed. Equals to the number of records in the connected component.
  • common.next(), common.prev(), common.first(), common.last() - page order signs.

Custom 'select' pager

pager:{ 
    template:function(data, common){
        var current = data.page + 1;
        var html = "<select onchange='grida.setPage(this.value)' style='text-align:center; width:150px'>";
        for (var i=1; i<=data.limit; i++)
            html+="<option "+(i == current?"selected='true'":"")+">"+i+"</option>";
        html+="</select> from "+data.limit;
        return html;
    },
    container:"paging_here",
    size:10,
    group:5
}

Related sample:  Custom pagers

Pager Localization

By default, pager uses recognizable signs to display order buttons (first, last, prev, next).

Default Locale

webix.locale.pager = {
    first: " &lt;&lt; ",
    last: " &gt;&gt; ",
    next: " &gt; ",
    prev: " &lt; "
};

Pager localization allows using words of any language for these buttons:

Custom Locale

webix.locale.pager = {
    first: "First",
    last: "Last",
    next: "Next",
    prev: "Prev"
};

Related sample:  Pager localization

Animation during Paging

Animation it switched on by animate property. Set to true, it allows scrolling through the view in X or Y mode, depending on the scroll value of the main component.

Animation can take various effects when they are stated in the animate constructor through type, subtype and direction parameters.

pager: {
    animate:{
        direction:"top",
        type:"flip"
    }
}

Related sample:  Paging animation types

Learn more about animation types and subtypes in the corresponding chapter of the manual.

Page and Component Size

Here we treat two tasks:

1 . How to ensure that the number of records per page equals to the number of records the component can display?

The number of records per page is stated by the size:(number) parameter of a pager.

At the same time, the number of records can be limited in the component itself by the following parameters:

  • yCount (number) - the number of items in a vertical mode;
  • xCount(number) - the number of items in the horizontal mode (typical of dataview and x-list).

All you need is to make these two parameters the same:

rows:[
    {
        view:"pager", 
        id:"pagerA",
        size:10
    },
    {   
        view:"datatable",
        columns:[...],
        pager:"pagerA",
        yCount:10
    }
]

Related sample:  Adjusting Component Size to Page

2 . How to adjust component size to page size?

To adjust the number of records shown per page to the size of parent HTML container and, hence, to the component's height, you should let pager autosize.

<div id="testA" style='height:600px; width:300px;'></div>
...
webix.ui({
    rows:[
        {
            view:"pager", 
            id:"pagerB",
            autosize:true,
            group:5
        },
        {
            view:"list",
            pager:"pagerB",
            container:"testA"
        }
    ]
});

Related sample:  Adjusting Page Size to Component Size

Paging Methods

Getting Pager Object

$$("datatable1").getPager();

Getting Current Page

Note that you'll get page index (zero-based numbering), so add 1 to get the actual page number.

$$("datatable1").getPage(); 
 
//or, using the pager object
$$("pagerA").config.page;

Setting (Opening) Page

To switch to the necessary page, specify the page's index within the dedicated method:

$$("datatable1").setPage(2); // makes the third page visible

..or select the needed page:

$$("datatable1").getPager().select(2); // -> selects the third page

Standalone Pager

Pager can be used without master component for creating custom logic. To render such pager, the following code should be used:

webix.ui({
  view: 'pager',
  template: '{common.prev()} {common.pages()} {common.next()}',
  master:false,
  size: 50,
  group: 5,
  count: 1000,
  on: {
      onItemClick: function(id, e, node) {
          //..some custom logic..
      }
  }
});

Template parameter can be omitted in favor of default template.

Related sample:  Standalone pager

Note that count and size parameters should be used anyway, count divided by size equals to the total number of pages.

Back to top