deliteful/list/PageableList

The PageableList widget extends the deliteful/list/List widget and adds paging capabilities to it.

Note that version 0.3.0 of this widget is not supported on IE10.

A pageable list does not load and display all its content all at once, but only loads and displays a subset of the content while providing user controls to load and display more data.

Its custom element tag is d-pageable-list.

Next Page Loader Example

Element Instantiation
Element Configuration
Element Styling
User Interactions
Mixins
Element Events
Enteprise Use

Element Instantiation

See delite/Widget for full details on how instantiation lifecycle is working.

Declarative Instantiation

<!-- A pageable list of categorized items that uses the default item renderer, -->
<!-- mapping the sales property of items to righttext, and using the -->
<!-- region property as the item category -->
<d-pageable-list height="100%" righttextAttr="sales" categoryAttr="region">
    <d-list-store>
        <!-- Add the following items to the list store -->
        { "label": "France", "sales": 500, "profit": 50, "region": "EU" },
        { "label": "Germany", "sales": 450, "profit": 48, "region": "EU" },
        { "label": "UK", "sales": 700, "profit": 60, "region": "EU" },
        { "label": "USA", "sales": 2000, "profit": 250, "region": "America" },
        { "label": "Canada", "sales": 600, "profit": 30, "region": "America" },
        { "label": "Brazil", "sales": 450, "profit": 30, "region": "America" },
        { "label": "China", "sales": 500, "profit": 40, "region": "Asia" },
        { "label": "Japan", "sales": 900, "profit": 100, "region": "Asia" }
    </d-list-store>
  </d-list>

Programmatic Instantiation

require(["dstore/Memory", "delite/list/PageableList", "dojo/domReady!"], function (Memory, PageableList) {
  // Create a memory store for the list and initialize it
  var dataStore = new Memory({idProperty: "label", data:
    [
      { label: "France", sales: 500, profit: 50, region: "EU" },
      { label: "Germany", sales: 450, profit: 48, region: "EU" },
      { label: "UK", sales: 700, profit: 60, region: "EU" },
      { label: "USA", sales: 2000, profit: 250, region: "America" },
      { label: "Canada", sales: 600, profit: 30, region: "America" },
      { label: "Brazil", sales: 450, profit: 30, region: "America" },
      { label: "China", sales: 500, profit: 40, region: "Asia" },
      { label: "Japan", sales: 900, profit: 100, region: "Asia" }
  ]});
  // A pageable list of categorized items from dataStore, that uses the default item renderer,
  // mapping the sales property of items to righttext and using the region property
  // as the item category.
  var list = new PageableList({store: dataStore, righttextAttr: "sales", categoryAttr: "region"});
  list.style.height = "100%";
  list.placeAt(document.body);
  list.startup();
});

Element Configuration

See also deliteful/list/List configuration for the element configuration inherited from the deliteful/list/List widget.

Table of content

Defining the length of pages
Defining the maximum number of pages to display at once
Hiding the list while it is busy loading and displaying a page of items
Other properties

Defining the length of pages

When started, a pageable list will load and display only one page of data, and will provide user controls to load and display more pages of data (if there is more data).

The pageLength property of a pageable list defines the number of items in a page of data. Note that this number is a maximum, and that a page may contain less items.

If this property is set to 0 or less, the list will load and display all the items from the store (as a non pageable list does).

Here is an example of setting a pageLength of 100 items:

        require([
            "deliteful/list/PageableList",
            "requirejs-domready/domReady!"
        ], function (PageableList) {
            var pageableList = new PageableList();
            pageableList.pageLength = 100;
            ...
            this.ownerDocument.body.appendChild(pageableList);
            pageableList.startup();
        });

Here is the same example using markup:

<head>
    ...
    <script>
        require([
            "delite/register",
            "deliteful/list/PageableList",
            "requirejs-domready/domReady!"
        ], function (register, PageableList) {
            register.parse();
        });
    </script>
</head>
<body>
    <d-pageable-list store="..." pageLength="100">
    </d-pageable-list>
</body>

In this example, the list will load (up to) the first 100 items from the store, display them, and provide user controls to load another page of (up to) 100 items if there are more items in the store.

Defining the maximum number of pages to display at once

The property maxPages defines the maximum number of pages to display at the same time, allowing to keep the size of the DOM under control when using very large lists of items.

When a pageable list loads and displays a new page of data, it makes sure not to display more pages than the maximum number of pages allowed by unloading some other pages.

Here is an example that illustrates the unloading mechanism, using a pageable list on a store of 1000 items, with a page length of 50 and a maximum number of 2 pages displayed at the same time:

Initially, the list loads and displays the 50 first items of the store (index 0 to 49), and creates a user control to load the following page;
When the user control is activated, the following 50 items (index 50 to 99) are loaded from the store and appended to the list (the list now displays the 100 first items from the store);
When the user control is activated once again:
1. the following 50 items (index 100 to 149) are loaded from the store and appended to the list;
2. the first page of items (index 0 to 49) is removed from the DOM, and a user control is created to load the previous page.

If the maxPages property is set to 0 or less, there is no maximum number of pages (pages are never unloaded).

Hiding the list while it is busy loading and displaying a page of items

The pageable list provides the options to hides its content when loading a page of data. This is activated by setting the hideOnPageLoad property to true.

Other properties

See the User Interactions section for the other available properties of a pageable list.

Element Styling

Supported themes

This widget provides default styling for the following delite themes:

bootstrap

CSS Classes

See also deliteful/list/List styling for the element styling inherited from the deliteful/list/List widget.

The CSS class of a page loader is d-list-loader.

When a page is currently loading, the CSS class d-loading is added to the page loader.

The progress indicator that is displayed when a page is loading can also be styled using CSS. See Progress indicator styling for more details.

The following example demonstrate how to customize the progress indicator using CSS, so that both the progress indicator and the text are displayed in red:

.d-list-loader {
    color: red;
}
.d-list-loader.d-loading {
    color: red;
}
.d-list-loader.d-loading .d-progress-indicator-lines {
    stroke: red;
}

User Interactions

See also deliteful/list/List user interactions for the user interactions inherited from the deliteful/list/List widget.

The list provides up to two user controls to load and display more data:

A user control to load the next page of data from the store. It is only present if there is more data to load from the store.
A user control to load the previous page of data from the store. It is only present if there is previous data to load from the store.

The user controls can be activated using one of the following interactions, as described in the next sections:

Activation with a mouse click / the keyboard SPACE key
Activation by scrolling

Activation with a mouse click / the keyboard SPACE key

The user controls for loading pages are clickable (or activable using the SPACE key when navigating the list using the keyboard).

If there is a next page of data in the store, the user control is displayed at the end of the list:

Next Page Loader Example

The message that is displayed by the control can be customized using the loadNextMessage of a pageable List (see the API documentation for more information).

When the user control is activated, its appearance changes while the list is busy retrieving data from the store and displaying it:

Next Page Loading Example

The message that is displayed when the list is busy can also be customized, using the loadingMessage property of a pageable list.

When the new page of items is displayed, the first new item gains the focus and the user control is either deleted (if there is no more data in the store) or moved to the end of the list:

Next Page Loaded Example

The user control to load the previous page of data follows the same pattern, except that it is displayed at the top of the list rather than at the end of the list, and that the property loadPreviousMessage defines what it displays:

Previous Page Loader Example

Activation by scrolling

The user controls, when they exist, can be automatically activated when the user scrolls to the top of the bottom of the list.

To activate this behavior, the autoPaging property must be set to true on the pageable list.

Mixins

See also deliteful/list/List mixins for the mixins provided for the inherited deliteful/list/List widget.

No specific Mixin is currently provided for this widget.

Element Events

See also deliteful/list/List element events for the element events inherited from the deliteful/list/List widget.

No specific event is emitted by this widget.

Enterprise Use

See also deliteful/list/List enterprise use for the enterprise use inherited from the deliteful/list/List widget.

Globalization

deliteful/list/PageableList provides an internationalizable bundle that contains only one message, with the key default-load-message. This is the message displayed by page loaders. This message supports the keyword ${pageLength}, that is replaced by the current value of the pageLength property of the widget.