Advanced Pagination

Category: Widgets
Subcategory: Buttons

Overview

Reusable widget to encapsulate the math required to manually do pagination. Most useful when getting data from an API that allows pagination (e.g. https://facebook.com/me/feed?limit=25&offset=50).

Tip: Need sorting too? Check out Advanced Sorting. (GitHub) (Mendix Marketplace)

Documentation

Demo urlhttps://widgettesting105-sandbox.mxapps.io/p/advanced-listview-controls

Advanced Pagination

Reusable widget to encapsulate the math required to manually do pagination. Most useful when getting data from an API that allows pagination (e.g. https://facebook.com/me/feed?limit=25&offset=50).

Tip: Need sorting too? Check out Advanced Sorting. (GitHub) (Mendix Marketplace)

Overview

Features

  • Offers 2 styles of pagination. Navigation (first 2 above) and Per Page (last 2 above)
  • Ability to configure most aspects inside the widget settings (text, color, alignment etc.)
  • Accepts Page and Result Count from a parent Data View and calculates the rest for you
  • Uses default Mendix classes to easily copy brand specific styles (e.g. mx-text, btn-primary)
  • Automatically correct the current page number if it is outside the range

Limitations

  • Data source must return an integer of the total number of records available (needed to calculate the total number of pages)

Usage

The following steps will create a Custom Grid that looks like the image below. Be aware that the text boxes are not required. page web

  1. Create a non-persistent entity called Pagination with Page, PageSize, and ResultTotal. Ideally this should be in it's own module for easier importing and exporting to new projects!
    pagination entity
  2. Create a non-persistent entity specific to your grid (i.e. AsyncListViewPagination), have it inherit Pagination and give it an association to System.Session
    inheritance
  3. Create a Microflow called ACT_RefreshPagination with a Pagination parameter, add a change object activity, and set the change object activity to refresh in client
    ACT refresh pagination
  4. Create a Microflow called DS_CreateRetrieve_{SpecificEntityName} that will check the System.Session for an existing {Specific Entity Name} object. If an object is found, return it; otherwise create a new one (don't forget to set the $currentSession in the Create Object activity)
    DS create retrieve specific entity
  5. Setup your page similar to how you see below
    page_mendix
  6. In the Advanced Pagination widgets, setup to Attributes tab using Page, PageSize, and ResultTotal.
    configuration attributes
  7. In the Advanced Pagination widgets, setup the Refresh Action with ACT_RefreshPagination
    refresh action
  8. In your API call Microflow, calculate the Offset and Amount using the Pagination object. In my example, I'm using a retrieve from database action, but you should pass these as variables into your API call.
    calculate offset
  9. In your API Call Microflow, set the Pagination's ResultTotal attribute as the total count from the API Call. In my example, this is $Count from a database aggregate, but you would likely need to get this value from the API's return structure.
    after API change object
  10. Run the project and see what it looks like! Adjust the settings in the Advanced Pagination's general tab to your liking.

Configuration Details

For configuration outside of the widget (e.g. how to setup your project) change the Usage section first.
 

Settings on Both Modes

Format - Which style of pagination should be displayed in this location? In the overview image, the first 2 examples are the 'Navigation' style and the last 2 are the 'Per Page' style.
Total Caption Alignment - Where should the 'Total Caption' text be shown relative to the buttons?
Total Caption - Text that tells the user how many results exist. (default '{ResultTotal} results').
Button Alignment - Where should the entire widget be displayed inside of it's parent's container?
Render Mode - Should the buttons contain padding and a border or only an icon?
Button Style - Which Mendix brand class should be applied (i.e. text-primary, btn-danger etc.)? These can be easily overridden with a CSS class (.widget-pagination .btn ...)
Auto Correct? - Adjust the page number if the current page is outside the range? (i.e. If showing page 4 of 3 = auto change the page to 1)
Auto Correct To - The page set when auto correcting. With First, it will set to page 1. With Last, it will set page as the total number of pages

Navigation Mode

Navigation mode
Include End Buttons? - Should the user be able to skip to the last page or back to the first page?
Page Display - Text shown in the middle of the buttons (default 'Page {Page} of {PageTotal}').

Per Page Mode

Per page mode
Include Arrows? - Should the user be able to navigate between the page with arrows or only be able to click the specific numbers?
Page Offset - The number of pages from the current page to display. For example, Page Offset is 1, Page is 5, and there are 10 pages, then the widget will show Pages 1, 4, 5, 6, and 10.

It will include more pages at the beginning and the end of the range. For example, Page Offset is 1, Page is 1, and there are 10 pages, then it will show pages 1, 2, 3, 4, and 10. This is because if the user were to go to page 3, then they would see pages 1, 2, 3, 4, and 10 anyway. Likewise, when the user goes to page 10, they will see pages 1, 7, 8, 9, and 10.

It will also check if the user would be displayed all possible pages should they click on any specific page. For example, Page Offset is 2 and there are 7 pages. The widget will show all pages 1 through 7, because if the user were to go to page 4, they would see all pages anyway.
Page Break - What should be in between pages when there is a gap? For example, the widget is showing 1, 2, 3, 4, and 10. What should be between 4 and 10?

Demo project

https://widgettesting105-sandbox.mxapps.io/p/advanced-listview-controls

Issues, suggestions and feature requests

Got any ideas for different styles of pagination? Submit an issue below! https://github.com/bsgriggs/mendix-advanced-pagination/issues

Development and contribution

Benjamin Griggs

Releases

Version: 1.2.0
Framework Version: 9.0.5
Release Notes: - Added auto-correct mode: if the widget is showing a page outside the range (i.e. page 4 of 3), it will automatically change the page number based on the developer's setting to either page 1 or 3
Version: 1.1.1
Framework Version: 9.0.5
Release Notes: - added multi-language support for Total Caption and Page Display
Version: 1.1.0
Framework Version: 9.0.5
Release Notes: - added support for multiple languages
Version: 1.0.0
Framework Version: 9.0.5
Release Notes: initial release