Pagination Handle

Generic Pagination Handling JavaScript Library

Table of Contents:

• General
  • Links
  • Build Size
• Usage
  • Import/Setup
  • Get Pagination State
  • Use the Generic Attributes to create your own element/component
  • Manual Navigation & Callback
  • API
• Contribution/Development
  • Primary Tech Stack
  • CLI Command
  • Folder Structure

---

General

Links

• NPM Package

Build Size (ESM/UMD/CJS)

• Minified Size: 8KB
• Gzipped: 2.7KB

Usage

Import/Setup:

• via ES Module (Js/Ts/Tsx file)

import PgnHandle from 'pagination-handle';
const pgnHandle = new PgnHandle();

• via CommonJs (Js file)

const PgnHandle = require('pagination-handle');
const pgnHandle = new PgnHandle();

• via UMD (Js file)

const pgnHandle = new PaginationHandle();

• via Script Tag (HTML)

<script src="<path>/<to>/<library>/umd/main.min.js"></script>
<script>
    const pgnHandle = new PaginationHandle();
</script>

Get Pagination State:

const sampleData = [ 'a', 'b', 'c' ];
const totalRecord = sampleData.length;
const pgnOption = {
    page: 0,                // start at 1st page
    increment: [ 1, 2 ],    // typically for select dropdown: 1 per page, 2 per page
    incrementIdx: 0,        // means increment is 1 from above
    maxSpread: 3          
};

// using builtin Type under `PgnType` namespace (no import required)
let someOption: PgnType.IOption;

// get the pagination state only
const pgnState = pgnHandle.getState(totalRecord, pgnOption);
const {
    perPage,
    totalPage,
    curr,
    pageNo,
    startIdx,
    endIdx,
    first,
    prev,
    next,
    last,
    totalRecord,
    startRecord,
    endRecord,
    ltSpread,
    rtSpread,
    maxSpread
} = pgnState;

// get the corresponding "visible" data slice
const sampleDataSlice = sampleData.slice(startIdx, endIdx);

// get the generic pagination element attributes to construct elements on your own
const genericComponentAttr = pgnHandle.createGenericCmpAttr({
    totalRecord,
    state: pgnState,
    option: pgnOption,
    callback: () => console.log('pgn state changed')
});
const {
    firstBtnAttr,
    prevBtnAttr,
    nextBtnAttr,
    lastBtnAttr,
    ltSpreadBtnsAttr,
    rtSpreadBtnsAttr,
    pageSelectAttr,
    perPageSelectAttr,
} = genericComponentAttr;

Use the Generic Attributes to create your own element/component

// JavaScript Example
const btn = document.createElement('button');
btn.type = 'button';
btn.disabled = firstBtnAttr.disabled;
btn.addEventListener('click', firstBtnAttr.onClick);
btn.textContent = firstBtnAttr.title;

// React Example
const PgnFristBtn = (firstBtnAttr) => {
    const { title, disabled, onClick } = firstBtnAttr;
    return (
        <button disabled={disabled} onClick={onClick}>
            {title}
        </button>
    );
};

Manual Navigation & Callback:

// start with page 0
const pgnStateOne = pgnHandle.getState(totalRecord, pgnOption);

// go to next page
const pgnStateTwo = pgnHandle.getState(totalRecord, {
    ...pgnOption, 
    page: pgnStateOne.next
});

API

Pagination State Object pgnState

Property	Type	Description
perPage	integer	current total number displayed/allowed per page
totalPage	integer	total number of pages
curr	integer	current page index (starts from 0)
pageNo	integer	current page number (starts from 1)
startIdx	integer	start index (inclusive) for the sliced data
endIdx	integer	end index (exclusive) for the sliced data
first	integer	index for first page
prev	integer	index for previous page
next	integer	index for next page
last	integer	index for last page
totalRecord	integer	total number of records in data
startRecord	integer	starting index for current displayed data
endRecord	integer	end index (non-inclusive) for current displayed data
ltSpread	integer or string	either a number (if less than the maxSpread) or '...' to indicate the non-displayed pages
rtSpread	integer or string	either a number (if less than the maxSpread) or '...' to indicate the non-displayed pages
maxSpread	integer	total page interval that is represented by the spread '...', i.e. not shown

Pagination Option Object pgnOption

Property	Type	Description
page	integer	index for default/starting page number (starts from 0)
increment	array of integers	available increments typically for the dropdown, e.g. [10, 20]
incrementIdx	integer	the default increment value above
maxSpread	integer	maximum number of page interval that is represented by the spread '...'

General Button Attribute Object firstBtnAttr/prevBtnAttr/nextBtnAttr/lastBtnAttr

Property	Type	Description
title	string	name of the button, one of the values: first prev next last
disabled	boolean	whether the button is disabled based on the current pagination state
onClick	function	page navigation callback when the button is clicked

Spread Button Attribute Object ltSpreadBtnsAttr/rtSpreadBtnsAttr

Property	Type	Description
title	string	name of the spread button, default: left-spread or right-spread
isSpread	boolean	whether the button is the spread symbol (false if it is a number)
onClick	function	page navigation callback when the button is clicked

Select Attribute Object perPageSelectAttr/getPageSelectAttr

Property	Type	Description
title	string	name of select dropdown, default: per page select
disabled	boolean	whether select dropdown is disabled based on the current pagination
options	array of integers	list of total number displayed/allowed per page OR list of navigatable pages
selectedOptionValue	integer	value of current total number displayed/allowed per page OR current page number
selectedOptionIdx	integer	corresponding index of selectedOptionValue property in options property
onSelect	function	page navigation callback when the select option is changed

Contribution/Development

Primary Tech Stack:

• TypeScript 3.8.3
• Node 13.12.0 | Npm 6.14.4
• Jest 25.5.3

CLI Command

• Build

npm run build

• Unit Test

npm run test

• Lint

npm run lint

• Compile Js

npm run compile-js

• Compile Bundled .d.ts file

npm run compile-dts

• Clear "dist" folder

npm run clean

Folder Structure

dist/                       // output files
    cjs/                    // common js format
        index.js            
        index.js.map
        index.min.js
    esm/                    // es module js format
        index.js            
        index.js.map
        index.min.js
    umd/                    // universal module definition format
        index.js            
        index.js.map
        index.min.js
    index.d.ts              // typings
    
src/                        // source code
    index.ts                // main entry file
    index.spec.ts           // unit test
    type.ts                 // typings

rollup.config.js            // rollup (bundler/build) config
.eslintrc.js                // EsLint config
tsconfig.json               // TypeScript config 
babel.config.js             // Babel config - transform TS and new Js features into ES5/Standard JavaScript
jest.config.js              // Jest config - unit test
package.json                // dev-dependencies, dependencies for the project    
.gitignore                  // git ignored
README.md                   // readme