4. Pagination

Pagination, by definition and usage in this context, is the division of the whole set of data into subsets called pages and loading the data into the TableView page-by-page and not the whole data directly. This is useful if you have a large amount of data to be displayed.

Steps to implement pagination functionality into TableView

Creating views to control the Pagination

Depending on your preference, you may not follow the following and create your own implementation.

1. Create a layout with the following components: Two Button views to control next and previous page, a Spinner if you want to have a customized number of pagination (e.g. 10, 20, 50, All), an EditText to have a user input on which page s/he wants to go to, a TextView to display details (e.g. Showing page X, items Y-Z)
2. Asign the views with the controls and methods which are discussed below.

Implementation of the pagination

1. Create a Pagination instance passing the created TableView.

    ...
    private TableView   tableView;
    private Pagination  mPagination;
    ...    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        ...
        tableView = setUpTableView();
        mPagination = new Pagination(mTableView);
        ...
    }
    ...

• The Pagination class has three possible constructors: (1) passing the TableView instance only, (2) TableView and the initial ITEMS_PER_PAGE and (3) TableView, initial ITEMS_PER_PAGE and the OnTableViewPageTurnedListener. By default, if no ITEMS_PER_PAGE specified, the TableView will be paginated into 10 items per page.

    /**
     * Basic constructor, TableView instance is required.
     *
     * @param tableView The TableView to be paginated.
     */
    public Pagination(ITableView tableView) { ... }
    
    /**
     * Applies pagination to the supplied TableView with number of items per page.
     *
     * @param tableView    The TableView to be paginated.
     * @param itemsPerPage The number of items per page.
     */
    public Pagination(ITableView tableView, int itemsPerPage) { ... }
    
    /**
     * Applies pagination to the supplied TableView with number of items per page and an
     * OnTableViewPageTurnedListener for handling changes in the TableView pagination.
     *
     * @param tableView    The TableView to be paginated.
     * @param itemsPerPage The number of items per page.
     * @param listener     The OnTableViewPageTurnedListener for the TableView.
     */
    public Pagination(ITableView tableView, int itemsPerPage, OnTableViewPageTurnedListener listener) { ... }

2. Loading the next page of items into the TableView using the nextPage() method. You can assign this to your implementation of nextPageButton onClick action:

    ...
    public void nextTablePage() {
        mPagination.nextPage();
    }
    ...

2. Loading the previous page of items into the TableView using the previousPage() method. You can assign this to your implementation of previousPageButton onClick action:

    ...
    public void previousTablePage() {
        mPagination.previousPage();
    }
    ...

3. You can navigate through the pages by going to a specific page directly using the goToPage(int page) method. You can assign this to the EditText field TextChanged action (using TextWatcher):

    ...
    public void goToTablePage(int page) {
        mPagination.goToPage(page);
    }
    ...

4. You can customize and set the number of items to be displayed per page of the TableView using the setItemsPerPage(int itemsPerPage) method. You can assign this to your Spinner with the number of items per page list:

    ...
    public void setTableItemsPerPage(int itemsPerPage) {
        mPagination.setItemsPerPage(itemsPerPage);
    }
    ...

5. Advanced usage: A listener interface (Pagination.OnTableViewPageTurnedListener) can also be implemented if you want to do something everytime a page is turned (e.g. previous, next, goToPage or change items per page action is called):

    ...
        mPagination = new Pagination(mTableView);
        mPagination.setOnTableViewPageTurnedListener(onTableViewPageTurnedListener);
    ...
    
    private Pagination.OnTableViewPageTurnedListener onTableViewPageTurnedListener =
            new Pagination.OnTableViewPageTurnedListener() {
                /**
                 * Called when the page is changed in the TableView.
                 *
                 * @param numItems   The number of items currently being displayed in the TableView.
                 * @param itemsStart The starting item currently being displayed in the TableView.
                 * @param itemsEnd   The ending item currently being displayed in the TableView.
                 */
                @Override
                public void onPageTurned(int numItems, int itemsStart, int itemsEnd) {
                    // Do something here...
                    // You can update a TextView to display details (e.g. Showing page X, items Y-Z)
                }
            };
    ...

Pagination notes

1. Other methods which can be used from Pagination:

    /**
     * Removes the OnTableViewPageTurnedListener for this Pagination.
     */
    void removeOnTableViewPageTurnedListener();
    
    /**
     * @return The current page loaded to the table view.
     */
    int getCurrentPage();
    
    /**
     * @return The number of items per page loaded to the table view.
     */
    int getItemsPerPage();
    
    /**
     * @return The number of pages in the pagination.
     */
    int getPageCount();
    
    /**
     * @return Current pagination state of the table view.
     */
    boolean isPaginated();

2. Pagination and Filtering works seamlessly: Filter action <---> Paginate action, e.g. You filter for all "Boy" then paginate by 50 items per page OR You paginate by 25 items per page and go to a specific page and then filter all "Sad", etc.