DOCSEARCHbyAlgolia
Submit Docs

Pagination.js

repository·master·Indexed 21 days ago

https://github.com/superraytin/paginationjs

A jQuery plugin for providing simple and highly customizable pagination for web applications. Version 2.6.0 supports multiple data sources including arrays, objects, custom functions, and URLs via Ajax. It features flexible rendering options compatible with Handlebars and Underscore.js, extensive UI customization for navigation elements, and a comprehensive API for controlling pagination state and behavior.

Tokens
7K
Snippets
24
Records
28
Agent score
74%

What's inside paginationjs

  1. Use Hooks and Callbacks for Pagination Events

    master

    Pagination events can be handled in two ways:

    1. Callbacks: Defined directly in the initialization object.
    2. Hooks: Defined using the .addHook(eventName, callback) method. Hooks can be defined before or after initialization.

    Common Event Hooks

    • beforeInit / afterInit: Around instance creation.
    • beforeRender / afterRender: Around the rendering of the pagination bar. beforeRender receives an isForced boolean (true if triggered by pagination, false if by initialization).
    • beforePaging / afterPaging: Around the paging process.
    • beforeSizeSelectorChange / afterSizeSelectorChange: Around page size changes.
    • beforeDisable / afterDisable and beforeEnable / afterEnable.
    • beforePreviousOnClick / afterPreviousOnClick.
    • beforePageOnClick / afterPageOnClick.
    • beforeNextOnClick / afterNextOnClick.
    • beforeGoInputOnEnter / afterGoInputOnEnter.
    • beforeGoButtonOnClick / afterGoButtonOnClick.
    • afterIsFirstPage / afterIsLastPage.

    Note: Returning false from a before... hook will prevent the action from proceeding.

    // Method 1: Using Callbacks
$('#example1').pagination({
    afterRender: function() {
        console.log('Rendered!');
    }
});

// Method 2: Using Hooks
var container = $('#example2');
container.pagination({ dataSource: [1, 2, 3], pageSize: 1 });
container.addHook('afterRender', function() {
    console.log('Hook triggered!');
});

  2. Quick Start with paginationjs

    master

    To use paginationjs, initialize the plugin on a jQuery selector. You must provide a dataSource (an array of items) and a callback function. The callback function is executed whenever the page changes, receiving the current page's data and the pagination state object. Use the callback to render the data into your desired container.

    <div id="data-container"></div>
<div id="pagination-container"></div>

<script>
$('#pagination-container').pagination({
    dataSource: [1, 2, 3, 4, 5, 6, 7, ... , 195],
    callback: function(data, pagination) {
        // Use your own template method here
        var html = template(data);
        $('#data-container').html(html);
    }
})
</script>

  3. Apply Themes to Pagination.js

    master

    Pagination.js includes several default themes. Apply them by adding the theme class to the className option. Ensure you have linked pagination.css in your HTML.

    Available Themes:

    • paginationjs-theme-blue: Standard blue theme.
    • paginationjs-small: Smaller UI.
    • paginationjs-big: Larger UI.

    You can combine them (e.g., paginationjs-theme-blue paginationjs-small). To create a fully custom theme, use className: 'custom-paginationjs' and provide your own CSS.

    // Example: Small and Blue theme
className: 'paginationjs-theme-blue paginationjs-small'

  5. Apply and Customize Pagination Themes

    master

    Pagination.js includes 5 default themes. To use them, include the pagination.css file in your HTML header and set the className option.

    Default Theme Usage:

    • Blue theme: className: 'paginationjs-theme-blue'
    • Small blue theme: className: 'paginationjs-theme-blue paginationjs-small'
    • Large blue theme: className: 'paginationjs-theme-blue paginationjs-big'

    To create a completely custom style, use the CSS class custom-paginationjs.

    <!-- In your HTML header -->
<link rel="stylesheet" href="path/to/pagination.css" />

<!-- In your JS config -->
<script>
$('#example').pagination({
    className: 'paginationjs-theme-blue paginationjs-small'
});
</script>```

  6. Customize AJAX request parameters with alias

    master

    When using a URL as a dataSource, Pagination.js automatically appends pageNumber and pageSize to the request. Use the alias option to change these parameter names to match your backend requirements.

    alias: {
    pageNumber: 'pageNum',
    pageSize: 'limit'
}
// Resulting URL: /test.json?pageNum=1&limit=10

  7. Customize pagination CSS classes

    master

    To style the pagination component, you can override the default CSS classes using these options:

    • classPrefix: Prefix for all classes (default: pagination).
    • className: Extra class for the main container.
    • activeClassName: Class for the active page (default: active).
    • disableClassName: Class for disabled items (default: disabled).
    • ulClassName: Class for the <ul> element inside the container.
    • pageClassName: Class for page number buttons.
    • prevClassName: Class for the 'Previous' button.
    • nextClassName: Class for the 'Next' button.

  8. Customize pagination text and templates

    master

    You can customize the text and the HTML structure of various pagination elements using template strings or functions.

    Text Customization

    • prevText: Text for 'Previous' (default: &laquo;).
    • nextText: Text for 'Next' (default: &raquo;).
    • ellipsisText: Text for ellipses (default: ...).
    • goButtonText: Text for the 'Go' button (default: Go).

    Template Customization

    Templates can use the following variables: currentPage, totalPage, totalNumber, rangeStart, and rangeEnd.

    • formatNavigator: Formats the navigator (e.g., 1 / 10).
    • formatGoInput: Formats the input field. Use <%= input %> to include the default input element (must have class J-paginationjs-go-pagenumber).
    • formatGoButton: Formats the button. Use <%= button %> to include the default button element (must have class J-paginationjs-go-button).
    • header / footer: Custom HTML/content for the top or bottom of the pagination.

    Example: Custom Navigator

    formatNavigator: '<%= rangeStart %>-<%= rangeEnd %> of <%= totalNumber %> items'
// Result: '1-20 of 195 items'

  9. Control pagination display elements

    master

    Use the following boolean options to show or hide specific UI components:

    • showPrevious (default: true): Show 'Previous' button.
    • showNext (default: true): Show 'Next' button.
    • showPageNumbers (default: true): Show page numbers.
    • showSizeChanger (default: false): Show the page size selector.
    • showNavigator (default: false): Show the navigator.
    • showGoInput (default: false): Show the 'Go to page' input.
    • showGoButton (default: false): Show the 'Go' button.
    • autoHidePrevious (default: false): Hide 'Previous' button when on the first page.
    • autoHideNext (default: false): Hide 'Next' button when on the last page.
    • hideFirstOnEllipsisShow (default: false): Hide the first page number when ellipses are present.
    • hideLastOnEllipsisShow (default: false): Hide the last page number when ellipses are present.

  10. Customize Ajax requests for asynchronous pagination

    master

    When using asynchronous pagination, you can configure the built-in Ajax request via the ajax option. This object must be compatible with $.ajax parameters.

    Commonly used ajax configuration keys:

    • type: Request method (default: GET).
    • dataType: Data format (e.g., json, xml, jsonp).
    • data: Additional parameters to send. Pagination automatically appends pageNumber and pageSize. Example: { ajax: { data: { dbType: 'oracle' } } }.
    • cache: Boolean to force/prevent browser caching (default: true).
    • async: Boolean for synchronous/asynchronous requests (default: true).
    • beforeSend: Callback function to modify the jqXHR object before the request is sent. Returning false cancels the request.
    • pageNumberStartWithZero: Set to true if your server-side pagination starts at index 0 instead of 1.
    // Example of adding extra data to the Ajax request
{
  ajax: {
    data: {
      dbType: 'oracle'
    }
  }
}

  11. Configure Display Control options

    master

    Control the visibility of pagination UI elements using boolean options:

    • showPrevious: Display 'previous' button (default true).
    • showNext: Display 'next' button (default true).
    • showPageNumbers: Display page number buttons (default true).
    • showSizeChanger: Display a dropdown to change page size (default false).
    • showNavigator: Display the page navigator (default false).
    • showGoInput: Display the 'Go' input box (default false).
    • showGoButton: Display the 'Go' button (default false).
    • autoHidePrevious: Hide 'previous' button if on the first page (default false).
    • autoHideNext: Hide 'next' button if on the last page (default false).
    • hideOnlyOnePage: Hide the entire pagination bar if there is only one page (default false).

  12. Customize pagination text and formatting

    master

    You can customize labels and template strings for various UI components:

    Labels:

    • prevText: Label for 'Previous' (default &laquo;).
    • nextText: Label for 'Next' (default &raquo;).
    • ellipsisText: Label for ellipsis (default ...).
    • goButtonText: Label for 'Go' button (default Go).

    Formatters (String or Function):

    • formatNavigator: Formats the navigator text. Available variables: currentPage, totalPage, totalNumber, rangeStart, rangeEnd.
    • formatGoInput: Formats the 'Go' input element. Available variables: input, currentPage, totalPage, totalNumber.
    • formatGoButton: Formats the 'Go' button element. Available variables: button, currentPage, totalPage, totalNumber.
    • header / footer: Prepend or append content to the pagination bar. Available variables: currentPage, totalPage, totalNumber.
    // Example: Custom navigator format
formatNavigator: '<%= rangeStart %>-<%= rangeEnd %> of <%= totalNumber %> items'