wc-grid-table
v3.1.14
Published
A table component implemented with css-grid and webcomponents.
Readme
wc-grid-table
Description
wc-grid-table (short: wgt) is a Free and Open-Source, CSS-Grid, Table WebComponent. The goal of this WebComponent is high customizability and a low barrier to entry.
It uses no required dependencies (lodash.debounce as optional plugin) and is only around 30kB (unzipped, minified) in size.
Current version: 3.1.13
Features
- Sortable columns, including stable multi-column sort (later columns keep their order when an earlier column is reversed)
- Locale-aware number sorting and comparison filters (
0,16and0.16are both treated as decimals) - Per-column filters (contains / not-contains regex, equals, greater, less, …)
- Filters run on the raw values; formatters only change what is displayed
- Pagination, column chooser (modal) and a footer that stays put while cells scroll
- Optional URL rewrite so filter, sort, pagination and hidden columns survive a reload
- Optional
debuglogging
Installation
Install via npm:
npm install wc-grid-tableUse via CDN:
<script src="https://unpkg.com/[email protected]/dist/standalone/bundle.min.js"></script>Build from Source
First install all dev-dependencies:
npm installwgt uses Browserify as bundler. To build the component and the examples:
npm run build:allUseful scripts:
| Script | Purpose |
| --- | --- |
| npm test | Jest tests |
| npm run serve | Serve dist/ and open the standalone example |
| npm run build:all | Create dist/ folders if needed, then build all bundles |
Usage
Getting Started
Include it in your page:
<body>
...
<script src="https://unpkg.com/[email protected]/dist/standalone/bundle.min.js"></script>
</body>Afterwards register the custom element. Use the provided defineCustomElement() function to register it as wc-grid-table, or call customElements.define with a custom name:
WcGridTable.defineCustomElement();
// or
customElements.define('your-fancy-name', WcGridTable.TableComponent);The name has to include at least one hyphen. After creating a wgt element the only thing needed is to add data:
let data = [
{
firstname: "Hans",
lastname: "Dieter",
age: 28,
hobby: "running"
},{
firstname: "Karl",
lastname: "Heinrich",
age: 52
},{
firstname: "Manfred",
lastname: "Steibl",
age: 60
}
]
let table = document.createElement('wc-grid-table');
table.setData(data);
document.querySelector('body').append(table);Formatters can wrap values for display (for example as links) without changing filter or sort:
table.formatter.Artikelnummer = [
(value) => value != undefined
? `<a href="/article/${value}">${value}</a>`
: ''
];Customization
Methods
The following functions are exposed on the wgt element (documented in their respective docstring):
useDefaultOptions()connectedCallback()setDebounceFn(debounceFn, sortDebounceOptions, filterDebouncedOptions)setData(data)getDisplayedData()getOriginalData()redrawData()redrawTable()registerPlugin(plugin)
Properties
The following properties can be accessed / set directly on the wgt element:
root_document— eitherdocumentor the connected shadowRootconditionalColumnStyle— an object with keys [condition,styles] whereconditionis a function(data: Array<Object>, column: string) => Booleanandstylesis an Array of CSS strings applied whenconditionreturns true for a columnconditionalRowStyle— like column styles, but per row / cellconditionalStyleOptions—{ active: Boolean }formatter— an Object with column names as keys, containing lists of formatter functions applied before displaying a value. Signature:(value, rowIndex, completeData) => any. Formatters run left to right. They do not change the values used for filter and sortformatterOptions—{ active: Boolean }filter— an Object with column names as keys, containing the filter input stringsfilterOptions—{ active: Boolean }filterOperations— list of{ name, char, fn(filterInput, testValue) }. Default operations: contains / not-contains (regex), equals, greater, greater-or-equal, less, less-or-equal, not-equal. Cycle them with the symbol next to each filter inputsortedBy— Array of{ col, dir }(diris"asc"or"desc"). Sorting is stacked, so primary, secondary, tertiary, … sorting is possiblesortOptions—{ active: Boolean }customChooseSortsCompareFn— maps a column to a compare function. Signature:(table, data, column) => CompareFncustomCompareNumbers/customCompareText— replacements for the default number / text compare functions (Array.prototype.sortstyle)pagination—{ active, currentPage, pageSize }(default page size is 40)hiddenColumns/visibleColumns/hiddenColumnsCondition— control which columns are shown. The footer columns button opens a modal to toggle them
Attributes
noheader— hide header rownofilter— hide filter rownofooter— hide footernopagekey— do not bind left/right keys for paginationnorewriteurl— do not write table state into the URLdebug— verboseconsole.logoutput (sort, filter, format, plugins)page-size— initial page size, e.g.page-size="25"height— max-height of the table container, e.g.height="80vh"options— serialized initial options (same shape as the URL state)
<wc-grid-table height="80vh" page-size="25" debug></wc-grid-table>License
ISC. See LICENSE.