2.4.0 • Published 9 months ago
@vtaits/filterlist v2.4.0
@vtaits/filterlist
Util for creating lists with filters, sotring, paginatinon, endless scroll etc.
Installation
npm install @vtaits/filterlist --save
or
yarn add @vtaits/filterlist
Api
import { Filterlist } from '@vtaits/filterlist';
/*
* assuming the API returns something like this:
* const json = {
* results: [
* {
* value: 1,
* label: 'Audi',
* },
* {
* value: 2,
* label: 'Mercedes',
* },
* {
* value: 3,
* label: 'BMW',
* },
* ],
* total: 50,
* };
*/
const filterlist = new Filterlist({
loadItems: async ({
// currently applied filters
appliedFilters,
// current page
page,
// number of items on one page
pageSize,
// sorting state
sort: {
// sorting parameter
param,
// asc or desc (boolean)
asc,
},
}, {
items,
}) => {
const response = await fetch(`/awesome-api-url/?page=${page}`);
const responseJSON = await response.json();
return {
items: responseJSON.results,
total: responseJSON.total,
};
},
});
filterlist.emitter.on(eventTypes.changeListState, (nextListState) => {
// change ui
document.getElementById('loader').style.display = nextListState.loading ? 'block' : 'none';
});
// load next chunk of for the infinite list
filterlist.loadMore();
// change runtime value of filter (e.g. on keyboard input)
filterlist.setFilterValue('foo', 'bar');
// apply runtime value and reload the list
filterlist.applyFilter('foo');
// change value of the filter and reload the list
filterlist.setAndApplyFilter('foo', 'bar');
// reset value of the filter and reload the list
filterlist.resetFilter('foo');
// bulk change values of filters (e.g. on keyboard input)
filterlist.setFiltersValues({
foo: 'value',
bar: ['baz', 'qux'],
}));
// bulk apply runtime values and reload the list
filterlist.applyFilters(['foo', 'bar']);
// bulk change values of filters and reload the list
filterlist.setAndApplyFilters({
foo: 'value',
bar: ['baz', 'qux'],
});
// bulk change empty values of filters and reload the list
filterlist.setAndApplyEmptyFilters({
foo: 'value',
bar: ['baz', 'qux'],
});
// bulk reset values of filters and reload the list
filterlist.resetFilters(['foo', 'bar']);
// reset all setted filters and reload the list
filterlist.resetAllFilters();
// set sorting state and reload the list
filterlist.setSorting('id');
// asc
filterlist.setSorting('id', true);
// desc
filterlist.setSorting('id', false);
// reload sorting state and reload the list
filterlist.resetSorting();
// reload current list
filterlist.reload();
// change current page reload the list (for pagination bases lists)
filterlist.setPage(3);
// change current page reload the list
filterlist.setPageSize(nextPage);
const {
// currently applied filters
appliedFilters,
// current page
page,
// number of items on one page
pageSize,
// sorting state
sort: {
// sorting parameter
param,
// asc or desc (boolean)
asc,
},
} = filterlist.getRequestParams();
const {
// runtime values of filters
filters,
// is the list currently loading
loading,
// list of loading items
items,
} = filterlist.getListState();
Filterlist parameters
const filterlist = new Filterlist({
// Create data store to store parameters such as currently applied filtes, sorting state, current page and number of items on one page
createDataStore,
// function that loads items into the list
loadItems,
// initially defined list of items
items,
// initial sorting
sort,
// filters and their values that applied by default
appliedFilters,
// request items on init
autoload,
// debounce timeout to prevent extra requests
debounceTimeout,
// default `asc` param after change sorting column
isDefaultSortAsc,
// filters and their values that will be set after filter reset
resetFiltersTo,
// by default items are cleared if filters or sorting changed. If `saveItemsWhileLoad` is `true`, previous list items are saved while load request is pending
saveItemsWhileLoad,
// initial page
page,
// initial size of the page
pageSize,
// check whether the list should be refreshed by timeout
shouldRefresh,
// timeout to refresh the list
refreshTimeout,
// total count of items
total,
});
Navigator url sync
You can use createDataStore
parameter
There's an example of synchronization using window.history
and window.location
here:
import {
createEmitter,
createStringBasedDataStore,
} from "@vtaits/filterlist/datastore/string";
const historyEmitter = createEmitter();
window.addEventListener("popstate", () => {
historyEmitter.emit();
});
function createDataStore() {
return createStringBasedDataStore(
() => window.location.search,
(nextSearch) => {
window.history.pushState('', '', `${window.location.pathname}?${nextSearch}`);
},
historyEmitter,
options,
);
};
const filterlist = new Filterlist({
createDataStore,
// ...
})
Events
emitter
is the instance of mitt.
import { EventType } from '@vtaits/filterlist';
filterlist.emitter.on(EventType.changeListState, (listState) => {
// ...
});
List of event types:
Name | When triggered |
---|---|
loadMore | after load items on init or call loadMore method |
setFilterValue | after call setFilterValue method |
applyFilter | after call applyFilter method |
setAndApplyFilter | after call setAndApplyFilter method |
resetFilter | after call resetFilter method |
setFiltersValues | after call setFiltersValues method |
applyFilters | after call applyFilters method |
setAndApplyFilters | after call setAndApplyFilters method |
setAndApplyEmptyFilters | after call setAndApplyEmptyFilters method |
setPage | after call setPage method |
setPageSize | after call setPageSize method |
resetFilters | after call resetFilters method |
resetAllFilters | after call resetAllFilters method |
setSorting | after call setSorting method |
resetSorting | after call resetSorting method |
reload | after call reload method |
updateStateAndRequest | after call updateStateAndRequest method |
changeLoadParams | after call some of next methods: loadMore , applyFilter , setAndApplyFilter , resetFilter , applyFilters , setAndApplyFilters , resetFilters , resetAllFilters , setSorting , resetSorting , updateStateAndRequest |
insertItem | after call insertItem method |
deleteItem | after call deleteItem method |
updateItem | after call updateItem method |
requestItems | before load items |
loadItemsSuccess | after successfully load |
loadItemsError | after load with error |
changeListState | after every change of list state |
2.4.0-signals.0
9 months ago
2.4.0
9 months ago
2.3.0
10 months ago
2.2.1
11 months ago
2.2.0
11 months ago
2.1.0
12 months ago
2.0.0
1 year ago
1.1.0
1 year ago
1.0.0
1 year ago
0.3.1
2 years ago
0.3.0
3 years ago
0.2.3
4 years ago
0.2.4
4 years ago
0.2.2
5 years ago
0.2.1
5 years ago
0.2.0
5 years ago
0.1.5
6 years ago
0.1.4
6 years ago
0.1.3
6 years ago
0.1.2
6 years ago
0.1.1
7 years ago
0.1.0
7 years ago