@bandwidth/redux-facet-pagination
v1.0.0
Published
Pagination behaviors for redux-facet
Downloads
5
Readme
redux-facet-pagination
A plug-in pagination system for redux-facet
which lets you add pagination to various types of collections without repeating yourself too much.
After you've integrated redux-facet
, you can enhance your containers and reducers to enable them to keep track of pagination state and render paginated data.
Check out a simple example here. The source is located in /example.
Immutable.js Support
To use redux-facet-pagination
with immutable
, import all modules from @bandwidth/redux-facet-pagination/immutable
. Module names and usages stay the same.
Documentation
Default export: withPaginatedData(selectItems: Function|String, options: Object)
A higher-order-component which enhances a facet
container with:
- Access to a paginated slice of provided data
- Access to pagination information (current page, page size)
- A set of action creator props which allow page navigation
The first parameter of withPaginatedData
is required. If you provide a function, this function must be a selector function which will retrieve your items list from the Redux state. If you provide a string, this string must be a prop name. The container will assume that this prop is provided with your items list and will paginate the data accordingly.
The last parameter for withPaginatedData()
is options
:
{
dataPropName: String = 'filteredData',
}
dataPropName
will let you change the prop name of the paginated data when it's provided to your wrapped component.
Using withPaginatedData()
Compose withPaginatedData()
after facet()
before passing in your component:
// selector function version
facet('users')(
withPaginatedData(selectUsers)( // selecting our own data list from the store
ViewComponent
),
);
// prop name version
facet('users')(
withPaginatedData('users')( // assuming that the container is provided with a `users` prop
ViewComponent
)
)
To make things more idiomatic, it's recommented to use recompose
:
compose(
facet('users'),
withPaginatedData(selectUsers),
)(ViewComponent);
Remember, withPaginatedData()
must come after facet()
.
Properties provided
A component enhanced using withPaginatedData()
will receive the following props:
paginatedData | [dataPropName]
- The paginated dataset will be supplied to a prop name you can define yourself via
options
. By default, this prop will bepaginatedData
.
- The paginated dataset will be supplied to a prop name you can define yourself via
currentPage
- The page number of the currently displayed page
pageSize
- The size of a page. You can specify pageSize as a prop to your container, which will seed this value.
pageCount
- The total number of pages, based on the length of the raw data array.
setPage(page: Number, pageSize: Number)
- Action creator function which is already bound to this facet.
- Call it to set the current page and/or change the page size.
nextPage()
- Action creator function which is already bound to this facet.
- Call it to advance to the next page.
- This will not advance past the last page according to
pageCount
.
previousPage()
- Action creator function which is already bound to this facet.
- Call it to go back one page.
- This will not go below page 0.
Setting the Page Size
redux-facet-pagination
defaults to a page size of 10
. To initialize, a container enhanced with redux-facet-pagination
will dispatch a setPage
action on mount with the current page properties (so if the component was mounted with currentPage=2
and pageSize=3
, an action will be dispatched which sets those values in the store).
To set the page size, you can provide the pageSize
prop to your container. When the container dispatches the initializing action, it will utilize your provided value. Consider using recompose
's withProps
helper within your container definition if you don't need the page size to change.
You can also change the page size at any time by providing it as a second parameter to setPage
. This can enable patterns where the user is allowed to customize the number of items they want to see on the screen.
withPagination(selectItems)
A lighter-weight higher-order-component that just provides pagination data, but does not compute a paginated list. withPagination
will provide currentPage
, pageSize
, pageCount
, setPage
, nextPage
, and previousPage
.
selectItems
has the same usage as withPaginatedData
. It's required to calculate the total page count.
This smaller container may be useful if you want to implement your pagination controls as a separate container from your data view.
paginationReducer
Include this reducer within your facet reducers to track pagination state.
This reducer expects to be mounted within a facet reducer. If this is done correctly, it will therefore only listen to pagination actions related to its facet.
Basic usage
To mount it manually, please reference the .key
property to mount it at the correct location in your facet reducer, or the library will not work.
const facetReducr = facetReducer('users', combineReducers({
foo: fooReducer,
bar: barReducer,
[paginationReducer.key]: paginationReducer,
}));
Automatic usage
Note:
mount
will not work withcombineReducers
, sincecombineReducers
ignores any 'extra' keys that get added to the resulting map.
You can mount the paginationReducer
automatically into your facet reducer using its .mount(facetReducer: Function)
function. By calling it with your facet reducer, it will return a new reducer and mount itself at the correct key. Your base reducer must return a state which is an object so that a key can be created for the alert reducer.
const enhancedFacetReducer = paginationReducer.mount(facetReducer);
paginationActions
The library exports a set of action creators which you can use to manage pagination within sagas or other parts of your code.
The action creators are:
paginationActions.setPage(page: Number, pageSize: Number)
: sets the current page, and optionally updates the page size.
NOTE: facet name metadata is required
redux-facet-pagination
does not apply facet names to actions created by its action creators. It's up to you to apply them if necessary. If you use the action creators provided to your component by withPagination
, these will be applied automatically. Likewise, if you use these action creators in a saga which is created with facetSaga
, the facet name will be applied.
To apply a facet name to an action, use redux-facet
's withFacet
helper function.
createPaginationSelectors(itemsSelector: Function)
A helper factory which returns a set of facet selectors you can use to select data based on pagination.
Pass a selector function which returns an array of items. An object will be returned which contains a few selector creators you can use in your facet
container:
createPageSelector(facetName)
: creates a selector which returns the current page of data from your items.createPageCountSelector(facetName)
: creates a selector which returns the total number of pages based on the number of items and the page size.
Example Usage
const selectors = createPaginationSelectors(selectUsers);
const FacetContainer = facet(
'users',
// a helper from the redux-facet library
// which applies the facetName to all selector creators
createStructuredFacetSelector({
pageCount: selectors.createPageCountSelector,
items: selectors.createPageSelector,
}),
)(ViewComponent);
paginationSelectors
redux-facet-pagination
ships with a few selector creators and selectors which can be used to read pagination data from the store and construct pages from your data.
paginationSelectors.createPaginationSelector(facetName: String)
- A function which creates a selector. Takes one parmeter,
facetName
. - The created selector returns all pagination info from the store as a JS object.
- A function which creates a selector. Takes one parmeter,
paginationSelectors.createCurrentPageSelector(facetName: String)
- A function which creates a selector. Takes one parmeter,
facetName
. - The created selector returns the current page.
- A function which creates a selector. Takes one parmeter,
paginationSelectors.createPageSizeSelector(facetName: String)
- A function which creates a selector. Takes one parmeter,
facetName
. - The created selector returns the page size.
- A function which creates a selector. Takes one parmeter,
paginationSelectors.selectPage(items: Array|List, currentPage: Number, pageSize: Number)
- A selector computation function. The parameters should be computed by other selectors.
- Use this as the 'combining' final parameter in
reselect
'screateSelector
, for instance. - Using the provided inputs, this will return a page of your
items
collection. - Defaults
pageSize
to10
if no other value is present.
paginationSelectors.selectPageCount(itemCount: Number, pageSize: Number)
- A selector computation function. The parameters should be computed by other selectors.
- Use this as the 'combining' final parameter in
reselect
'screateSelector
, for instance. - Using the provided inputs, this will return the number of pages present.
- This may seem trivial, but why not?