UNPKG

6.17 kB Markdown View Raw
1[![Build Status](https://api.travis-ci.org/koalyptus/TableFilter.svg?branch=master)](https://travis-ci.org/koalyptus/TableFilter)
2[![Document](https://www.tablefilter.com/docs/badge.svg)](https://www.tablefilter.com/docs/source.html)
3[![codecov](https://codecov.io/gh/koalyptus/TableFilter/branch/master/graph/badge.svg)](https://codecov.io/gh/koalyptus/TableFilter)
4[![Greenkeeper badge](https://badges.greenkeeper.io/koalyptus/TableFilter.svg)](https://greenkeeper.io/)
5[![Donate](https://img.shields.io/badge/donate-%24-green.svg)](https://www.tablefilter.com/donate.html)
6
7# TableFilter
8
9> A Javascript library making HTML tables filterable
10
11TableFilter is a modernised version of the [HTML Table Filter generator](http://tablefilter.free.fr) javascript plugin.
12This library adds to any html table a "filter by column" feature that enables
13users to filter and limit the data displayed within a long table. By default, the script automatically adds a filter grid bar at the top of the desired table.
14
15## Features
16* Convert a regular HTML table into an advanced grid component providing:
17 * Advanced columns filtering model
18 * Sorting and pagination capabilities
19 * Complete selection model ([ezEditTable](http://codecanyon.net/item/ezedittable-enhance-html-tables/2425123?ref=koalyptus) extension)
20 * Extended keyboard navigation ([ezEditTable](http://codecanyon.net/item/ezedittable-enhance-html-tables/2425123?ref=koalyptus) extension)
21 * Inline cell or row editing ([ezEditTable](http://codecanyon.net/item/ezedittable-enhance-html-tables/2425123?ref=koalyptus) extension)
22 * Row insertion or deleting ([ezEditTable](http://codecanyon.net/item/ezedittable-enhance-html-tables/2425123?ref=koalyptus) extension)
23 * And even more features...
24* Attach to an existing HTML table
25* Integration with any server-side technology as this is a pure client-side
26solution
27* Exhaustive documentation and poweful API
28
29## Getting started
30* Clone the repo using Git:
31```shell
32git clone https://github.com/koalyptus/TableFilter.git
33```
34
35* You can [download](https://github.com/koalyptus/TableFilter/archive/master.zip) this repository.
36
37* TableFilter is available on [npm repository](https://www.npmjs.com/package/tablefilter), you can install it from the command line using the following command:
38```shell
39npm install tablefilter --save-dev
40```
41* or get the future features from the ``next`` release channel:
42```shell
43npm install tablefilter@next --save-dev
44```
45* Alternatively you can also [access these files from unpkg CDN](https://unpkg.com/tablefilter/), download them or point your package manager to them.
46
47## Setup
48### Using modules
49Require `TableFilter`:
50```javascript
51// ES2015 modules
52import TableFilter from 'tablefilter';
53
54// CommonJS or AMD modules
55var TableFilter = require('tablefilter');
56```
57
58### Using distribution scripts
59If you are not using a module system, you can reference the distribution scripts directly in your html pages:
60```html
61<script src="path_to/node_modules/tablefilter/dist/tablefilter/tablefilter.js"></script>
62```
63
64### Placing manually the distribution scripts in your project
65Copy the ``tablefilter`` directory under ``dist`` and place it at desired location in your project. Then include the main js file in your page:
66```shell
67<script src="path/to/my/scripts/tablefilter/tablefilter.js"></script>
68```
69
70### Usage
71Place the following snippet just under the HTML table and always define a ``base_path`` property in the configuration object to reflect the path to the script
72```shell
73<script>
74var tf = new TableFilter(document.querySelector('.my-table'), {
75 base_path: 'path/to/my/scripts/tablefilter/'
76});
77tf.init();
78</script>
79```
80If the ``base_path`` property is not specified, it will default to ``/tablefilter`` directory:
81```shell
82your-page.html
83 |— tablefilter
84```
85
86## Development
87This project requires node.js and Grunt to be installed:
88- install [node.js](https://nodejs.org/) v8.9.4 or higher
89- install [Grunt](http://gruntjs.com/getting-started) from the command line using npm (comes with node.js):
90```shell
91npm install -g grunt-cli
92```
93Once ``Grunt`` is sorted out you can follow the instructions below.
94Start by installing any dependencies.
95
96```shell
97npm install
98```
99Use
100```shell
101npm run dev
102```
103command to launch a build / watch cycle and start the local
104sever on port ``8080``.
105
106Use
107```shell
108npm run build
109```
110command to generate a production build.
111
112The
113```shell
114npm run dist
115```
116command will create a production build, run the tests and finally generate
117the demos:
118
119To run all the tests and generate the coverage report:
120
121```shell
122npm test
123```
124
125or to run specific test(s):
126
127```shell
128grunt test-only:test.html
129grunt test-only:test.html,test-sort.html
130```
131
132to view the coverage report(s), open the `index.html` under the
133`report/coverage` folder or
134[online](https://codecov.io/gh/koalyptus/TableFilter).
135
136## Demos
137Check out the online [examples](http://www.tablefilter.com/examples.html)
138or generate the demos locally:
139```shell
140npm run build:demos
141```
142then run the local webserver:
143```shell
144npm start
145```
146then pick a demo from:
147```shell
148http://localhost:8080/demos/
149```
150
151## Documentation
152Find exhaustive documentation on the configuration options in the [WIKI](https://github.com/koalyptus/TableFilter/wiki) section.
153
154Autogenerated documentation of the ES6 modules is available on the website: [docs](http://www.tablefilter.com/docs)
155
156If you previously used the HTML Table Filter Generator plugin, verify the configuration
157options you are using are still supported: [Obsolete](https://github.com/koalyptus/TableFilter/wiki/Obsolete)
158
159Run this task to generate the documentation in the ``docs/docs`` directory:
160```shell
161npm run esdoc
162```
163
164## Support
165* GitHub for [reporting bugs](https://github.com/koalyptus/TableFilter/blob/master/CONTRIBUTING.md#reporting-bugs) and [feature requests](https://github.com/koalyptus/TableFilter/blob/master/CONTRIBUTING.md#suggesting-enhancements-and-features).
166
167## License
168[MIT](LICENSE)
169
170
171
172
173
174