Try sorting the two table columns. Then look at the source of the page. The data-order attributes on the cells take precedent over the contents of the cells.
19 |
51 |
52 |
53 |
--------------------------------------------------------------------------------
/docs/documentation/API.md:
--------------------------------------------------------------------------------
1 | >Please note that the API is not finalised and may change so check back once in while.
2 |
3 | ### dom
4 | #### type `Object`
5 |
6 | Returns a reference to the [`HTMLTableElement`](https://developer.mozilla.org/en/docs/Web/API/HTMLTableElement).
7 |
8 | ---
9 |
10 | ### wrapper
11 | #### type `Object`
12 |
13 | Returns a reference to the main `HTMLDivElement` that wraps the entire layout.
14 |
15 | ---
16 |
17 | ### container
18 | #### type `Object`
19 |
20 | Returns a reference to the main `HTMLDivElement` that contains the table.
21 |
22 | ---
23 |
24 | ### pagers
25 | #### type `Array`
26 |
27 | Returns a reference to the currently displayed pagers.
28 |
29 | ---
30 |
31 | ### options
32 | #### type `Object`
33 |
34 | Returns the current configuration options. See [Options](Options)
35 |
36 | ---
37 |
38 | ### initialized
39 | #### type `Boolean`
40 |
41 | Returns true if the library is fully loaded and all HTML is rendered.
42 |
43 | ---
44 |
45 | ### data
46 | #### type `Object`
47 |
48 | The data of the table, containing two parts: `headings` and `data` (contents of the tables).
49 |
50 | * `headings`: An array of **header cells**.
51 |
52 | * `data`: An array of rows of data. Each row consists of an array of **row cells**.
53 |
54 |
55 | **Header cells** are objects with these fields:
56 |
57 | * `data` (any, required): The headers data in it's original format.
58 |
59 | * `text` (string, optional): In case the browser's automatic conversion of the data field to a string to display in a browser is not working correctly, this field can be sued to control what is being rendered.
60 |
61 | * `type` (string, optional): "html" in case of the data field is an array of DiffDOM nodes. "string" in case of a plaintext string.
62 |
63 | **Row cells** are objects with these fields:
64 |
65 | * `attributes` (any, optional): The row attributes. Use like `{ "class": "my-class", "style": "background-color: pink;" }`.
66 |
67 | * `cells` (any[], required): The list of cells in this row. See "Content cells" for more details.
68 |
69 | **Content cells** are also objects with the same `data` and `text` fields that **header fields** has and additionally with this field:
70 |
71 | * `order` (string or integer, optional): Used for sorting in case and is useful if the `data` field cannot be used for sorting.
72 |
73 | ---
74 |
75 | ### data-index
76 | #### type `Integer`
77 |
78 | All rows in the `data.data` array have a custom propery named `data-index`. This represents the position in the `data` array. It can be useful for getting the correct position of a row as the native `rowIndex` property may be either `-1` if the row isn't rendered or incorrect if you're on any other page than page 1.
79 |
80 | Also, in some browsers, the first row of a `tbody` element will have a `rowIndex` of `1` instead of `0` as they take the `thead` row as the first row.
81 |
82 | For example if you want to remove the first row on page 5 while showing 5 rows per page (21st row):
83 |
84 | ```javascript
85 | // grab the first row on page 5
86 | let firstRow = document.querySelector("tbody tr");
87 |
88 | // INCORRECT: Because it's the first rendered row the native firstRow.rowIndex
89 | // will be 1 which will remove the second row in the data array
90 | datatable.rows.remove(firstRow.rowIndex);
91 |
92 | // CORRECT: firstRow.dataset.index will return 20 which is the
93 | // correct position (21st row) in the data array
94 | datatable.rows.remove(parseInt(firstRow.dataset.index));
95 |
96 | ```
97 |
98 | ---
99 |
100 | ### pages
101 | #### type `Array`
102 |
103 | Returns a collection of pages each of which contain collections of `HTMLTableRowElement`s.
104 |
105 | ---
106 |
107 | ### hasRows
108 | #### type `Boolean`
109 |
110 | Returns `true` if the current table has rows.
111 |
112 | ---
113 |
114 | ### hasHeadings
115 | #### type `Boolean`
116 |
117 | Returns `true` if the current table has headings.
118 |
119 | ---
120 |
121 | ### currentPage
122 | #### type `Integer`
123 |
124 | Returns the current page number.
125 |
126 | ---
127 |
128 | ### totalPages
129 | #### type `Integer`
130 |
131 | Returns the number of pages.
132 |
133 | ---
134 |
135 | ### onFirstPage
136 | #### type `Boolean`
137 |
138 | Returns `true` if the current page is also the first page.
139 |
140 | ---
141 |
142 | ### onLastPage
143 | #### type `Boolean`
144 |
145 | Returns `true` if the current page is also the last page.
146 |
147 | ---
148 |
149 | ### searching
150 | #### type `Boolean`
151 |
152 | Returns `true` if a search is currently being done and search results are displayed.
153 |
154 | ---
155 |
156 | ### searchData
157 | #### type `Array`
158 |
159 | Returns an array of index numbers of current search result rows from `data.data`.
160 |
161 | ---
162 |
--------------------------------------------------------------------------------
/docs/documentation/Adding-a-column-from-a-remote-source.md:
--------------------------------------------------------------------------------
1 | Adding a column from a remote source (AJAX) is simple with the `columns` API.
2 |
3 | Let's say you've selected a column from your MySQL table and you want to include it in your `datatable` instance. You can encode the column data as a `JSON string` and fetch it:
4 | ```javascript
5 | {
6 | heading: "Progress"
7 | data: [
8 | "37%",
9 | "97%",
10 | "63%",
11 | "30%",
12 | ...
13 | ]
14 | }
15 | ```
16 |
17 |
18 | ```javascript
19 | let addNewColumn = function() {
20 | let columnData = "remote/data/url"
21 |
22 | fetch(columnData)
23 | .then(response => response.json())
24 | .then(data => datatable.columns.add(data))
25 | }
26 | ```
--------------------------------------------------------------------------------
/docs/documentation/Dynamically-adding-data.md:
--------------------------------------------------------------------------------
1 | New data of many formats can be added at any time with the `insert()` method as well as the `rows` and `columns` API.
2 |
3 | ---
4 |
5 | You can quickly add a new row with an `array` of cell data:
6 |
7 | ```javascript
8 | let newRow = ["Cell 1", "Cell 2", "Cell 3", "Cell 4", ...];
9 |
10 | datatable.rows.add(newRow);
11 | ```
12 |
13 | The `add()` method also accepts a nested `array` for adding multiple rows:
14 | ```javascript
15 | let newRows = [
16 | ["Cell 1", "Cell 2", "Cell 3", "Cell 4", ...],
17 | ["Cell 1", "Cell 2", "Cell 3", "Cell 4", ...],
18 | ["Cell 1", "Cell 2", "Cell 3", "Cell 4", ...],
19 | ["Cell 1", "Cell 2", "Cell 3", "Cell 4", ...],
20 | ...
21 | ];
22 |
23 | datatable.insert({ data: newRows });
24 | ```
25 | ---
26 |
27 | The `insert()` method can accept both an `object` or and array of `key-value objects` depending on your setup:
28 |
29 | ```javascript
30 |
31 | let newData = {
32 | headings: ["Heading 1", "Heading 2", "Heading 3", "Heading 4", ...],
33 | data: [
34 | ["Cell 1", "Cell 2", "Cell 3", "Cell 4", ...],
35 | ["Cell 5", "Cell 6", "Cell 7", "Cell 8", ...],
36 | ["Cell 9", "Cell 10", "Cell 11", "Cell 12", ...],
37 | ...
38 | ]
39 | };
40 |
41 | // or
42 |
43 | let newData = [
44 | {
45 | "Heading 1": "Cell 1",
46 | "Heading 2": "Cell 2",
47 | "Heading 3": "Cell 3",
48 | "Heading 4": "Cell 4",
49 | },
50 | {
51 | "Heading 1": "Cell 5",
52 | "Heading 2": "Cell 6",
53 | "Heading 3": "Cell 7",
54 | "Heading 4": "Cell 8",
55 | }
56 | ];
57 |
58 | // Insert the data
59 | datatable.insert(newData);
60 |
61 | ```
62 |
63 | Note that while the `key-value` method doesn't require you to order the data correctly to match the table layout, the instance will still check that the given `key` (heading) is present and will skip the insertion if it isn't, so make sure the `keys` match the column labels.
64 |
65 | ---
66 |
67 | `JSON` strings can easily be imported also:
68 |
69 | ```json
70 | "[{
71 | 'Heading 1': 'Value 1',
72 | 'Heading 2': 'Value 2',
73 | 'Heading 3': 'Value 3',
74 | ...
75 | },
76 | {
77 | 'Heading 1': 'Value 4',
78 | 'Heading 2': 'Value 5',
79 | 'Heading 3': 'Value 6',
80 | ...
81 | }]"
82 | ```
83 |
84 | ```javascript
85 | import {
86 | DataTable,
87 | convertJSON
88 | } from "simple-datatables"
89 | const dataTable = new DataTable("#myTable")
90 | const convertedData = convertJSON({
91 | data: // the above JSON string
92 | })
93 | dataTable.insert(convertedData)
94 | ```
95 |
96 | or `csv` strings:
97 |
98 | ```text
99 | Name,Ext.,City,Start Date
100 | Hammett Gordon,8101,Wah,1998/06/09
101 | Kyra Moses,3796,Quenast,1998/07/07
102 | Kelly Cameron,4836,Fontaine-Valmont,1999/02/07
103 | Theodore Duran,8971,Dhanbad,1999/04/07
104 | ...
105 | ```
106 |
107 | ```javascript
108 | import {
109 | DataTable,
110 | convertCSV
111 | } from "simple-datatables"
112 | const dataTable = new DataTable("#myTable")
113 | const convertedData = convertJSON({
114 | data: // the above CSV string,
115 | headings: true,
116 | columnDelimiter: ",",
117 | lineDelimiter: "\n"
118 | })
119 | dataTable.insert(convertedData)
120 | ```
121 |
--------------------------------------------------------------------------------
/docs/documentation/Events.md:
--------------------------------------------------------------------------------
1 | simple-datatables fires its own events which you can listen for by utilising the `.on()` method:
2 |
3 | ```javascript
4 | let dataTable = new DataTable(myTable);
5 |
6 | dataTable.on('datatable.XXXX', function(args) {
7 | // Do something when datatable.XXXX fires
8 | });
9 | ```
10 |
11 | ### `datatable.init`
12 | Fires when the table is fully rendered and ready for use.
13 |
14 | ### `datatable.page`
15 | Fires on page change.
16 |
17 | A single argument is available which returns the page number:
18 |
19 | ```javascript
20 | dataTable.on('datatable.page', function(page) {
21 | //
22 | });
23 | ```
24 |
25 | ### `datatable.page:before`
26 | Fires before page change.
27 |
28 | A single argument is available which returns the page number:
29 |
30 | ```javascript
31 | dataTable.on('datatable.page:before', function(page) {
32 | //
33 | });
34 | ```
35 |
36 | ### `datatable.perpage`
37 | Fires when the perPage option is changed with the dropdown. A single argument returns the per-page value:
38 |
39 | ```javascript
40 | dataTable.on('datatable.perpage', function(perpage) {
41 | //
42 | });
43 | ```
44 |
45 | ### `datatable.perpage:before`
46 | Fires before the perPage option is changed with the dropdown. A single argument returns the per-page value:
47 |
48 | ```javascript
49 | dataTable.on('datatable.perpage:before', function(perpage) {
50 | //
51 | });
52 | ```
53 |
54 | ### `datatable.refresh`
55 | Fires when the `.refresh()` method is called.
56 |
57 | ### `datatable.refresh:before`
58 | Fires before the `.refresh()` method is called.
59 |
60 | ### `datatable.search`
61 | Fires on keyup during a search.
62 |
63 | Two arguments are available: `query` which returns the query string entered and `matched` which returns an array of
64 | rows containing the matched string:
65 |
66 | ```javascript
67 | dataTable.on('datatable.search', function(query, matched) {
68 | //
69 | });
70 | ```
71 |
72 | ### `datatable.search:before`
73 | Fires on keyup before a search.
74 |
75 | Two arguments are available: `query` which returns the query string entered and `matched` which returns an array of rows containing the matched string:
76 |
77 | ```javascript
78 | dataTable.on('datatable.search:before', function(query, matched) {
79 | //
80 | });
81 | ```
82 |
83 | ### `datatable.selectrow`
84 | Fires when user selects a row - either by mouse click on a row or by a key specified by [rowSelectionKeys](rowSelectionKeys) during keyboard based navigation (requires option
85 | [rowNavigation](rowNavigation)).
86 |
87 | Three arguments are available:
88 |
89 | * `row` which returns the `
` element that was selected,
90 | * `event` which returns the event that caused the selection,
91 | * `focused` (true/false) which returns whether the table had focus when the row was selected.
92 |
93 |
94 | You can run `event.preventDefault()` like this:
95 |
96 | ```javascript
97 | dataTable.on("datatable.selectrow", (rowIndex, event, focused) => {
98 | event.preventDefault();
99 | ...
100 | });
101 | ```
102 |
103 | See the [row navigation demo](../demos/14-row-navigation/index.html) for a more complete example.
104 |
105 | ### `datatable.sort`
106 | Fires when the table is sorted.
107 |
108 | Two arguments are available when listening for this event: `column` which returns the column index and `direction` which returns the sort direction:
109 |
110 | ```javascript
111 | dataTable.on('datatable.sort', function(column, direction) {
112 | //
113 | });
114 | ```
115 |
116 | ### `datatable.update`
117 | Fires when the `.update()` method is called.
118 |
119 | ### `datatable.update:before`
120 | Fires before the `.update()` method is called.
121 |
122 | ### `editable.init`
123 | Fires when the editor is initialized.
124 |
125 | ### `editable.save.cell`
126 | Fires when the cell is saved (even when the value is not actually updated).
127 |
128 | ### `editable.save.row`
129 | Fires when the row is saved.
130 |
131 | ### `editable.context.open`
132 | Fires when the context menu is opened.
133 |
134 | ### `editable.context.close`
135 | Fires when the context menu is closed.
136 |
--------------------------------------------------------------------------------
/docs/documentation/Getting-Started.md:
--------------------------------------------------------------------------------
1 | ### Install
2 |
3 | ```
4 | npm install simple-datatables --save
5 | ```
6 |
7 | ---
8 |
9 | ### Initialise
10 |
11 | The JS file should be included before any scripts that call the plugin.
12 |
13 | Then just initialise the plugin by either passing a reference to the table or a CSS3 selector string as the first parameter:
14 |
15 | ```javascript
16 | let myTable = document.querySelector("#myTable");
17 | let dataTable = new DataTable(myTable);
18 |
19 | // or
20 |
21 | let dataTable = new DataTable("#myTable");
22 |
23 | ```
24 |
25 | You can also pass the options object as the second parameter:
26 |
27 | ```javascript
28 | let dataTable = new DataTable("#myTable", {
29 | searchable: false,
30 | fixedHeight: true,
31 | ...
32 | });
33 | ```
34 |
35 | ### Initial data
36 |
37 | You can either supply initial data through the options object or by starting with a table that already has data filled in.
38 |
39 | If you start out with a table that already contains header cells, you can add these attributes to individual header cells
40 | to influence how the corresponding column is treated:
41 |
42 | * `data-type`: Can be used to set the type of the column. It works the same as using `type` in the [columns](columns) option.
43 |
44 | * `data-hidden`: If set to `"true"` will hide the column. It works the same as using `hidden` in the [columns](columns) option.
45 |
46 | * `data-searchable`: If set to `"false"` will prevent searching of the column. It works the same as using `searchable` in the [columns](columns) option.
47 |
48 | * `data-sortable`: If set to `"false"` will prevent sorting of the column. It works the same as using `sortable` in the [columns](columns) option.
49 |
50 | If you start out with a table that already contains data, you can add these attributes to individual cells to influence how
51 | the cell is being processed:
52 |
53 | * `data-content`: If this attribute is present on a cell, the value of this attribute rather than the contents of the cell
54 | will be processed.
55 |
56 | * `data-order`: If this attribute is present on a cell, the value of this attribute will be used for ordering the row in case
57 | of sorting. Any other sort order will be overridden. IF the field only contains numeric characters, the field will first
58 | be converted to a number.
59 |
--------------------------------------------------------------------------------
/docs/documentation/Options.md:
--------------------------------------------------------------------------------
1 | simple-datatables can be initialised with custom options passed as the second parameter of the constructor.
2 |
3 | ```javascript
4 | let options = {
5 | searchable: true,
6 | perPage: 10,
7 | ...
8 | };
9 | let dataTable = new DataTable(myTable, options);
10 | ```
11 |
12 | ---
13 | ### Data
14 | * [data](data)
15 | * [type](columns#type)
16 | * [format](columns#format)
17 | ### Appearance
18 | * [caption](caption)
19 | * [classes](classes)
20 | * [columns](columns)
21 | * [fixedColumns](fixedColumns)
22 | * [fixedHeight](fixedHeight)
23 | * [footer](footer)
24 | * [header](header)
25 | * [hiddenHeader](hiddenHeader)
26 | * [labels](labels)
27 | * [template](template)
28 | * [scrollY](scrollY)
29 | ### Rendering
30 | * [pagerRender](pagerRender)
31 | * [rowRender](rowRender)
32 | * [tableRender](tableRender)
33 | * [diffDomOptions](diffDomOptions)
34 | ### Pagination
35 | * [paging](paging)
36 | * [perPage](perPage)
37 | * [perPageSelect](perPageSelect)
38 | * [firstLast](firstLast)
39 | * [nextPrev](nextPrev)
40 | * [firstText](firstText)
41 | * [lastText](lastText)
42 | * [prevText](prevText)
43 | * [nextText](nextText)
44 | * [ellipsisText](ellipsisText)
45 | * [truncatePager](truncatePager)
46 | * [pagerDelta](pagerDelta)
47 | ### Searching
48 | * [searchable](searchable)
49 | * [sensitivity](columns#sensitivity)
50 | * [searchQuerySeparator](searchQuerySeparator)
51 | * [searchMethod](searchMethod)
52 | ### Sorting
53 | * [sortable](sortable)
54 | * [locale](columns#locale)
55 | * [numeric](columns#numeric)
56 | * [caseFirst](columns#caseFirst)
57 | * [ignorePunctuation](columns#ignorePunctuation)
58 | ### Navigation
59 | * [rowNavigation](rowNavigation)
60 | * [rowSelectionKeys](rowSelectionKeys)
61 | * [tabIndex](tabIndex)
62 | ### Other
63 | * [destroyable](destroyable)
64 |
--------------------------------------------------------------------------------
/docs/documentation/caption.md:
--------------------------------------------------------------------------------
1 | ### `caption`
2 | #### Type: `string`
3 | #### Default: `undefined`
4 |
5 | Display a table caption with [
](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/caption). No caption
6 | is displayed by default.
7 |
--------------------------------------------------------------------------------
/docs/documentation/classes.md:
--------------------------------------------------------------------------------
1 | ### `classes`
2 | #### Type: `object`
3 |
4 | ### Default
5 | ```javascript
6 | {
7 | active: "datatable-active",
8 | bottom: "datatable-bottom",
9 | container: "datatable-container",
10 | cursor: "datatable-cursor",
11 | dropdown: "datatable-dropdown",
12 | ellipsis: "datatable-ellipsis",
13 | empty: "datatable-empty",
14 | headercontainer: "datatable-headercontainer",
15 | info: "datatable-info",
16 | input: "datatable-input",
17 | loading: "datatable-loading",
18 | pagination: "datatable-pagination",
19 | paginationList: "datatable-pagination-list",
20 | search: "datatable-search",
21 | selector: "datatable-selector",
22 | sorter: "datatable-sorter",
23 | table: "datatable-table",
24 | top: "datatable-top",
25 | wrapper: "datatable-wrapper"
26 | },
27 | ```
28 |
29 | Allows for customizing the classnames used by simple-datatables.
30 |
31 | Please note that class names cannot be empty and cannot be reused between different attributes. This is required for simple-datatables to work correctly.
32 |
33 | Multiple classes can be provided per attribute. Please make sure that classes are be separated by spaces.
34 | For example, `dt.options.classes.table = "first second"` will apply classes `first` and `second` to the generated table.
--------------------------------------------------------------------------------
/docs/documentation/columns-API.md:
--------------------------------------------------------------------------------
1 | As of `v1.2.0`, the `columns` API is implemented and allows access to the table columns for quick manipulation.
2 |
3 | As of `v4.0.0`, `columns` is a property and not a method on the current instance.
4 |
5 | To use the `columns` API just access under the `columns` property of the current instance:
6 |
7 | ```javascript
8 | let columns = datatable.columns;
9 | ```
10 |
11 | You can then chain the following methods.
12 |
13 | ---
14 |
15 | ### `get(column [integer])`
16 |
17 | Fetch read-only data about the column at index `column`. The `column` parameter should be an integer representing the column.
18 |
19 | ---
20 |
21 | ### `size()`
22 |
23 | Fetch the number of columns.
24 |
25 | ---
26 |
27 | ### `sort(column [integer], direction [string])`
28 |
29 | Sort the selected column. The `column` parameter should be an integer representing the column, starting with zero for the first column. The `direction` parameter is optional.
30 |
31 | ---
32 |
33 | ### `add(data [object])`
34 |
35 | Add a new column to the current instance. The `data` parameter should be an object with the required `heading` and `data` properties set. The `heading` property should be a `string` representing the new column's heading. The `data` property should be an array of `strings` representing the cell content of the new column.
36 |
37 | ```javascript
38 | let columns = datatable.columns;
39 |
40 | let newData = {
41 | heading: "Column Heading",
42 | data: [
43 | "Value 1",
44 | "Value 2",
45 | "Value 3",
46 | ...
47 | ]
48 | };
49 |
50 | // Add the new column
51 | columns.add(newData);
52 | ```
53 |
54 | You can also pass the `sortable`, `type` and `format` properties to further customise the new column.
55 |
56 | The `sortable` property defaults to `true`, unless sorting is disabled globally.
57 |
58 | ```javascript
59 | let newData = {
60 | type: "date",
61 | format: "YYYY/MM/DD"
62 | heading: "Start Date",
63 | data: [
64 | "1999/10/25",
65 | "2000/05/12",
66 | "2003/08/01",
67 | ...
68 | ]
69 | };
70 | ```
71 |
72 | ---
73 |
74 | ### `remove(select [integer|array])`
75 |
76 | Remove a column or columns from the current instance. The `select` parameter should be either an `integer` or an array of `integers` representing the column indexes to be removed.
77 |
78 | ```javascript
79 | let columns = datatable.columns;
80 |
81 | // Remove the 4th column
82 | columns.remove(3);
83 |
84 | // Remove the 1st and 2nd column
85 | columns.remove([0, 1]);
86 |
87 | // Remove the last column
88 | columns.remove(datatable.headings.length - 1);
89 | ```
90 |
91 | ---
92 |
93 | ### `hide(select [integer|array])`
94 |
95 | Hides the selected column(s). The columns will not be visible and will be omitted from search results and exported data.
96 |
97 | ```javascript
98 | // Hide the first and second columns
99 | columns.hide([0, 1]);
100 | ```
101 |
102 | ---
103 |
104 | ### `show(select [integer|array])`
105 |
106 | Shows the selected column(s) (if hidden). The columns will be visible and will be included in search results and exported data.
107 |
108 | ```javascript
109 | // Show the first and second columns
110 | columns.show([0, 1]);
111 | ```
112 |
113 | ---
114 |
115 | ### `visible(select [integer|array])`
116 |
117 | Checks to see if the selected column(s) are visible. Returns a `boolean` for single indexes or an `array` of `boolean`s for multiple indexes.
118 |
119 | If you omit the `select` parameter, an `array` of `booleans` will be returned representing all available columns.
120 |
121 | ```javascript
122 | let columns = datatable.columns;
123 |
124 | // Hide the 4th of 5 columns
125 | columns.hide(3);
126 |
127 | // Check visiblilty
128 | columns.visible(3); // returns false
129 | ```
130 |
131 | or
132 |
133 | ```javascript
134 | columns.visible([0, 1, 2, 3]); // returns [true, true, true, false]
135 | ```
136 |
137 | or
138 |
139 | ```javascript
140 | columns.visible(); // returns [true, true, true, false, true]
141 | ```
142 |
143 | ---
144 |
145 | ### `hidden(select [integer|array])`
146 |
147 | Checks to see if the selected column(s) are visible. Returns a `boolean` for single indexes or an `array` of `boolean`s for multiple indexes.
148 |
149 | Usage is the same as the `visible` method.
150 |
151 | **As of `1.4.18` the `hidden()` method has been deprecated and will be removed in the next minor version.**
152 |
153 | ---
154 |
155 | ### `swap(indexes [array])`
156 |
157 | Swap th position of two columns. Just pass an array of 2 integers representing the column indexes you require swapping.
158 |
159 | ```javascript
160 | let columns = datatable.columns;
161 |
162 | // Swap the 1st and 6th columns
163 | columns.swap([0, 5]);
164 | ```
165 |
166 | ---
167 |
168 | ### `order(indexes [array])`
169 |
170 | Order the columns based on the given order. Just pass an array of column indexes in the order you require:
171 |
172 | ### Original order
173 |
174 | 
175 |
176 | ```javascript
177 | // Reorder the columns
178 | datatable.columns.order([1, 3, 4, 2, 0]);
179 | ```
180 |
181 | ### Result
182 |
183 | 
184 |
--------------------------------------------------------------------------------
/docs/documentation/columns.md:
--------------------------------------------------------------------------------
1 | ### `columns`
2 | #### Type: `array`
3 | #### Default: `undefined`
4 |
5 | Controls various aspects of individual or groups of columns. Should be an array of objects with the following properties:
6 |
7 | #### `caseFirst`
8 |
9 | Default: `"false"` Options: `["false", "upper", "lower"]`. Influences how string sorting is done and whether upper or lower case letters are sorted first. If `"false"` is selected, will use the chosen `locale`'s default sorting order. Specifying `caseFirst`
10 | as part of the table's configuration will define a default for all columns.
11 |
12 | #### `cellClass`
13 |
14 | Allows to specify the CSS classes to apply to the body cell.
15 |
16 | #### `filter`
17 |
18 | Instead of ordering the row, clicking on the header will filter it. Specify an array of items to filter for. The array can also contain functions that will be executed on the data item of the cell to determine whether to include it in the filtered content.
19 |
20 | #### `format`
21 |
22 | A string representing the `datetime` format when using the `date` type. Specifying `format`
23 | as part of the table's configuration will define a default for all columns.
24 |
25 | #### `headerClass`
26 |
27 | Allows to specify the CSS classes to apply to the header cell.
28 |
29 | #### `hidden`
30 |
31 | When set to `true` the column(s) will not be visible and will be excluded from search results.
32 |
33 | #### `ignorePunctuation`
34 |
35 | Default: `true` (boolean). Influences how sorting and searching is done. Specifying `ignorePunctuation` as part of the table's configuration will define a default for all columns.
36 |
37 | #### `locale`
38 |
39 | Default: `"en-US"` (string). Set a locale such as `en-UK` or `de` for the column. Influences how string sorting is done. Allows even for specification of specific subvariants such as `de-DE-u-co-phonebk`. Specifying `locale` as part of the table's configuration will define a default for all columns.
40 |
41 | #### `numeric`
42 |
43 | Default: `true` (boolean). Influences how string sorting is done. If `true` multiple numbers will be seen as just one so that "file 1.jpg" will come before "file 100.jpg". Specifying `numeric`
44 | as part of the table's configuration will define a default for all columns.
45 |
46 | #### `searchable`
47 |
48 | When set to `false` the column(s) cannot be searched.
49 |
50 | #### `searchItemSeparator`
51 |
52 | Default: `""`. Influences searching in that cell content will be split with this value by default when searching for content. Specifying `searchItemSeparator` as part of the table's configuration will define a default for all search boxes.
53 |
54 | #### `searchMethod`
55 |
56 | A custom search method to be used for the column(s). The function should take 5 arguments:
57 | `terms` (an array of strings representing the search terms),
58 | `cell` (the cell that is to be checked for the search terms),
59 | `row` (the data row that the cell is part of),
60 | `column` (the id of the column of the cell),
61 | `source` (a unique string given to a particular search interface so that multiple search itnerfaces can be used simultaneously).
62 |
63 | It should return `true` if the search string is found in the data, `false` otherwise.
64 |
65 | The default is that it simply checks for the presence of a particular search term in the cell content.
66 |
67 | Defining a `searchMethod` as part of the table's configuration will define a default for all columns.
68 |
69 | #### `select`
70 |
71 | An integer or array of integers representing the column(s) to be manipulated.
72 |
73 | #### `sensitivity`
74 |
75 | Default: `"base"`. Options: `["base", "accent", "case", "variant"]`. Influences how searching is done. `"base"` and `"accent"` will ignore case differences. `"base"` and `"case"` will ignore differences in accent symbols. Specifying `sensitivity` as part of the table's configuration will define a default for all columns.
76 |
77 | #### `sort`
78 |
79 | Automatically sort the selected column. Can only be applied if a single column is selected.
80 |
81 | #### `sortSequence`
82 |
83 | An array of "asc" and "desc" describing the order sort will be executed as the user clicks on the column header. Note that each can only be mentioned up to one time. So effectively you have these options:
84 |
85 | ```js
86 | ["asc", "desc"] // default
87 | ["desc", "asc"]
88 | ["asc"]
89 | ["desc"]
90 | ```
91 |
92 | #### `sortable`
93 |
94 | When set to `false` the column(s) cannot be sorted.
95 |
96 | #### `type`
97 |
98 | A `string` representing the type of data in the column(s) cells. Choose from the following options:
99 |
100 | * `html` (default)
101 | * `string`
102 | * `date` - a valid `datetime` string
103 | * `number`
104 | * `boolean`
105 | * `other`
106 |
107 | Specifying `type` as part of the table's configuration will define a default for all columns.
108 |
109 | #### `render`
110 |
111 | A callback to customise the rendering of the column(s) cell content. The function takes 4 parameters.
112 | You can either return a string representing the cells content, you can modify the provided td in the format used by [diffDOM](https://github.com/fiduswriter/diffDOM) or you can return a new td in that same format.
113 |
114 | ```javascript
115 | =>
116 | render: function(value, td, rowIndex, cellIndex) {
117 |
118 | }
119 |
120 | ```
121 |
122 | ---
123 |
124 | #### Examples
125 | ```javascript
126 | let datatable = new DataTable("#myTable", {
127 | columns: [
128 | // Sort the second column in ascending order
129 | { select: 1, sort: "asc" },
130 |
131 | // Set the third column as datetime string matching the format "DD/MM/YYY"
132 | { select: 2, type: "date", format: "DD/MM/YYYY" },
133 |
134 | // Disable sorting on the fourth and fifth columns
135 | { select: [3,4], sortable: false },
136 |
137 | // Hide the sixth column
138 | { select: 5, hidden: true },
139 |
140 | // Append a button to the seventh column
141 | {
142 | select: 6,
143 | type: 'string',
144 | render: function(data, td, rowIndex, cellIndex) {
145 | return `${data}`;
146 | }
147 | }
148 | ]
149 | });
150 | ```
151 |
152 | You can use the same properties in your markup. Just add the property to the `th` element as a `data-{property}` attribute:
153 |
154 | ```html
155 |
156 |
157 |
Heading 1
158 |
Heading 2
159 |
Heading 3
160 | ...
161 |
162 | ...
163 |
164 | ```
165 |
--------------------------------------------------------------------------------
/docs/documentation/data.md:
--------------------------------------------------------------------------------
1 | ### `data`
2 | #### Type: `object`
3 | #### Default: `undefined`
4 |
5 | Pass an object of data to populate the table.
6 |
7 | You can set both the headings and rows with `headings` and `data` properties, respectively. The headings property is optional.
8 |
9 | ```javascript
10 | let myData = {
11 | "headings": [
12 | "Name",
13 | "Company",
14 | "Ext.",
15 | "Start Date",
16 | "Email",
17 | "Phone No."
18 | ],
19 | "data": [
20 | [
21 | "Hedwig F. Nguyen",
22 | "Arcu Vel Foundation",
23 | "9875",
24 | "03/27/2017",
25 | "nunc.ullamcorper@metusvitae.com",
26 | "070 8206 9605"
27 | ],
28 | [
29 | "Genevieve U. Watts",
30 | "Eget Incorporated",
31 | "9557",
32 | "07/18/2017",
33 | "Nullam.vitae@egestas.edu",
34 | "0800 106980"
35 | ],
36 | ...
37 | };
38 |
39 | let dataTable = new DataTable(myTable, {
40 | data: myData
41 | });
42 | ```
43 |
44 | > NOTE: If the headings count and rows count do not match, the library will throw an exception.
45 |
46 | ### Using key-value pairs
47 |
48 | If your data is in the form of key-value pairs, you can quickly convert it to a format that the API can use:
49 |
50 | ```javascript
51 |
52 | let data = [
53 | {
54 | "prop1": "value1",
55 | "prop2": "value2",
56 | "prop3": "value3"
57 | },
58 | {
59 | "prop1": "value4",
60 | "prop2": "value5",
61 | "prop3": "value6"
62 | }
63 | ];
64 |
65 | let obj = {
66 | // Quickly get the headings
67 | headings: Object.keys(data[0]),
68 |
69 | // data array
70 | data: []
71 | };
72 |
73 | // Loop over the objects to get the values
74 | for ( let i = 0; i < data.length; i++ ) {
75 |
76 | obj.data[i] = [];
77 |
78 | for (let p in data[i]) {
79 | if( data[i].hasOwnProperty(p) ) {
80 | obj.data[i].push(data[i][p]);
81 | }
82 | }
83 | }
84 |
85 | ```
86 |
87 | which will produce:
88 |
89 | ```javascript
90 | {
91 | headings : [
92 | "prop1",
93 | "prop2",
94 | "prop3"
95 | ],
96 | data : [
97 | [
98 | "value1",
99 | "value2",
100 | "value3"
101 | ],
102 | [
103 | "value4",
104 | "value5",
105 | "value6"
106 | ]
107 | ]
108 | }
109 | ```
--------------------------------------------------------------------------------
/docs/documentation/datetime.md:
--------------------------------------------------------------------------------
1 | Simple DataTables utilizes the [MomentJS](https://momentjs.com/) library for parsing datetime strings for easier column sorting.
2 |
3 | ## Method 1
4 |
5 | Define a `data-type` attribute on the headings and set the value to `date`. If the datetime string is in a format that can not be sorted easily by standard methods, you must define the `data-format` attribute and set its value to the format that is expected.
6 |
7 | ```html
8 |
9 |
10 |
11 |
12 | ...
13 |
14 |
15 | ```
16 |
17 | ## Method 2
18 |
19 | The `date` and `format` strings can also be defined in the options using the `columns` property:
20 |
21 | ```javascript
22 | // Allow sorting of the first column with "DD/MM/YYYY" format
23 | let datatable = new DataTable("#myTable", {
24 | columns: [
25 | {
26 | select: 0,
27 | type: "date",
28 | format: "DD/MM/YYYY"
29 | }
30 | ]
31 | });
32 |
33 | // Apply formatting to the third and fourth columns as well
34 | let datatable = new DataTable("#myTable", {
35 | columns: [
36 | {
37 | select: 0,
38 | type: "date",
39 | format: "DD/MM/YYYY"
40 | },
41 | {
42 | select: [2,3],
43 | type: "date",
44 | format: "MM/DD/YY"
45 | }
46 | ]
47 | });
48 | ```
49 |
50 | As well as custom format strings, there are some pre-defined formats that you can utilise:
51 |
52 | * `ISO_8601`
53 | * `RFC_2822`
54 | * `MYSQL`
55 |
56 | ```javascript
57 | // Allow sorting of the third column by MySQL datetime strings
58 | let datatable = new DataTable("#myTable", {
59 | columns: [
60 | {
61 | select: 2,
62 | type: "date",
63 | format: "MYSQL"
64 | }
65 | ]
66 | });
67 | ```
68 |
--------------------------------------------------------------------------------
/docs/documentation/destroy().md:
--------------------------------------------------------------------------------
1 | #### type `Function`
2 |
3 | Destroy the instance.
4 |
5 | #### Usage
6 | ```javascript
7 | datatable.destroy();
8 | ```
--------------------------------------------------------------------------------
/docs/documentation/destroyable.md:
--------------------------------------------------------------------------------
1 | ### `destroyable`
2 | #### Type: `boolean`
3 |
4 | ### Default
5 | ```javascript
6 | true
7 | ```
8 |
9 |
10 | Whether to keep the original HTML in memory in order to be able to destroy the table again.
11 |
--------------------------------------------------------------------------------
/docs/documentation/diffDomOptions.md:
--------------------------------------------------------------------------------
1 | ### `diffDomOptions`
2 | #### Type: `object`
3 | #### Default: `{ valueDiffing: false }`
4 |
5 |
6 | If specified, specifies options to apply to diffDOM. See diff-dom package for specifics.
7 |
--------------------------------------------------------------------------------
/docs/documentation/ellipsisText.md:
--------------------------------------------------------------------------------
1 | ### `ellipsisText`
2 | #### Type: `string`
3 | #### Default: `'…'`
4 |
5 | Set the content of the ellipsis used in the pager.
6 |
--------------------------------------------------------------------------------
/docs/documentation/firstLast.md:
--------------------------------------------------------------------------------
1 | ### `firstLast`
2 | #### Type: `boolean`
3 | #### Default: `false`
4 |
5 | Toggle the skip to first page and skip to last page buttons.
--------------------------------------------------------------------------------
/docs/documentation/firstText.md:
--------------------------------------------------------------------------------
1 | ### `firstText`
2 | #### Type: `string`
3 | #### Default: `'«'`
4 |
5 | Set the content of the skip to first page button.
6 |
--------------------------------------------------------------------------------
/docs/documentation/fixedColumns.md:
--------------------------------------------------------------------------------
1 | ### `fixedColumns`
2 | #### Type: `boolean`
3 | #### Default: `true`
4 |
5 | Fix the width of the columns. This stops the columns changing width when loading a new page.
--------------------------------------------------------------------------------
/docs/documentation/fixedHeight.md:
--------------------------------------------------------------------------------
1 | ### 'fixedHeight`
2 | #### Type: `boolean`
3 | #### Default: `false`
4 |
5 | Fix the height of the table. This is useful if your last page contains less rows than set in the perPage options and
6 | simply stops the table from changing size and affecting the layout of the page.
7 |
--------------------------------------------------------------------------------
/docs/documentation/footer.md:
--------------------------------------------------------------------------------
1 | ### `footer`
2 | #### Type: `boolean`
3 | #### Default: `false`
4 |
5 | Enable or disable the table footer.
--------------------------------------------------------------------------------
/docs/documentation/header.md:
--------------------------------------------------------------------------------
1 | ### `header`
2 | #### Type: `boolean`
3 | #### Default: `true`
4 |
5 | Enable or disable the table header.
--------------------------------------------------------------------------------
/docs/documentation/hiddenHeader.md:
--------------------------------------------------------------------------------
1 | ### `hiddenHeader`
2 | #### Type: `boolean`
3 | #### Default: `false`
4 |
5 | Whether to hide the table header.
--------------------------------------------------------------------------------
/docs/documentation/index.md:
--------------------------------------------------------------------------------
1 | #### Getting Started
2 | * [Install](Getting-Started#install)
3 | * [Manual](Getting-Started#browser)
4 | * [Initialise](Getting-Started#initialise)
5 | * [Upgrading](Upgrading)
6 |
7 | #### Tips
8 | * [Sorting Datetimes](datetime)
9 | * [Dynamically Adding Data](Dynamically-adding-data)
10 | * [Add columns from remote source](Adding-a-column-from-a-remote-source)
11 |
12 | #### Events
13 | * [datatable.init](Events#datatableinit)
14 | * [datatable.refresh](Events#datatablerefresh)
15 | * [datatable.update](Events#datatableupdate)
16 | * [datatable.page](Events#datatablepage)
17 | * [datatable.sort](Events#datatablesort)
18 | * [datatable.perpage](Events#datatableperpage)
19 | * [datatable.search](Events#datatablesearch)
20 | * [datatable.multisearch](Events#datatablesearch)
21 | * [datatable.selectrow](Events#datatableselectrow)
22 |
23 | #### Options
24 |
25 | See [Options](Options)
26 |
27 |
28 | #### Properties
29 | * [dom](API#dom)
30 | * [wrapper](API#wrapper)
31 | * [container](API#container)
32 | * [pagers](API#pagers)
33 | * [options](API#options)
34 | * [initialized](API#initialized)
35 | * [data](API#data)
36 | * [data-index](API#data-index)
37 | * [pages](API#pages)
38 | * [hasRows](API#hasrows)
39 | * [hasHeadings](API#hasheadings)
40 | * [currentPage](API#currentpage)
41 | * [totalPages](API#totalpages)
42 | * [onFirstPage](API#onfirstpage)
43 | * [onLastPage](API#onlastpage)
44 | * [searching](API#searching)
45 | * [searchData](API#searchdata)
46 |
47 | #### Methods
48 | * [rows API](rows-API)
49 | * [columns API](columns-API)
50 | * [on()](on())
51 | * [update()](update())
52 | * [refresh()](refresh())
53 | * [page()](page())
54 | * [insert()](insert())
55 | * [setMessage()](setMessage())
56 | * [destroy()](destroy())
57 | * [init()](init())
58 | * [print()](print())
59 | * [search()](search())
60 | * [multiSearch()](multiSearch())
61 |
--------------------------------------------------------------------------------
/docs/documentation/init().md:
--------------------------------------------------------------------------------
1 | #### type `Function`
2 |
3 | Initialise the instance after [destroying]().
4 |
5 | #### Usage
6 |
7 | ```javascript
8 | /**
9 | * @return {Void}
10 | */
11 | datatable.init();
12 | ```
13 |
--------------------------------------------------------------------------------
/docs/documentation/insert().md:
--------------------------------------------------------------------------------
1 | #### type `Function`
2 |
3 | Insert new data in to the table.
4 | #### Usage
5 | ```javascript
6 | /**
7 | * @param {object} data New data to insert
8 | * @return {void}
9 | */
10 | datatable.insert(data);
11 | ```
12 |
13 | ---
14 |
15 | #### Examples
16 |
17 | ##### Pass an `array` of `key-value` pairs (objects):
18 | ```javascript
19 | let newData = [
20 | {
21 | "Heading 1": "Cell 1",
22 | "Heading 2": "Cell 2",
23 | "Heading 3": "Cell 3",
24 | "Heading 4": "Cell 4",
25 | },
26 | {
27 | "Heading 1": "Cell 5",
28 | "Heading 2": "Cell 6",
29 | "Heading 3": "Cell 7",
30 | "Heading 4": "Cell 8",
31 | }
32 | ];
33 |
34 | datatable.insert(newData);
35 | ```
36 |
37 | ##### Pass an `object` with the `headings` and/or `data` property:
38 |
39 | ```javascript
40 | let newData = {
41 | headings: [
42 | "Name",
43 | "Position",
44 | "Town",
45 | "Ext.",
46 | "Start Date",
47 | "Salary"
48 | ],
49 | data: [
50 | [
51 | "Cedric Kelly",
52 | "Senior Javascript Developer",
53 | "Edinburgh",
54 | "6224",
55 | "2012/03/29",
56 | "$433,060"
57 | ],
58 | [
59 | "Airi Satou",
60 | "Accountant",
61 | "Tokyo",
62 | "5407",
63 | "2008/11/28",
64 | "$162,700"
65 | ],
66 | ...
67 | ]
68 | };
69 |
70 | // add the rows
71 | dataTable.insert(newData);
72 | ```
73 |
74 | If you attempt to pass new headings to a table that has headings, they'll be ignored.
--------------------------------------------------------------------------------
/docs/documentation/labels.md:
--------------------------------------------------------------------------------
1 | ### `labels`
2 | #### Type: `object`
3 |
4 | Customise the displayed labels. (v1.0.6 and above)
5 |
6 | #### Defaults
7 | ```javascript
8 | labels: {
9 | placeholder: "Search...",
10 | searchTitle: "Search within table",
11 | pageTitle: "Page {page}",
12 | perPage: "entries per page",
13 | noRows: "No entries found",
14 | info: "Showing {start} to {end} of {rows} entries",
15 | noResults: "No results match your search query",
16 | }
17 | ```
18 |
19 | The strings wrapped in curly braces represent variables that are inserted.
20 |
21 |
22 |
23 |
24 |
Property
25 |
Effect
26 |
Variables
27 |
28 |
29 |
30 |
31 |
placeholder
32 |
Sets the placeholder of the search input
33 |
None
34 |
35 |
36 |
searchTitle
37 |
Sets the title of the search input
38 |
None
39 |
40 |
41 |
pageTitle
42 |
Sets the title of the page (as used in the page navigator)
43 |
44 | {page} - The current page number
45 |
46 |
47 |
48 |
perPage
49 |
Sets the per-page dropdown's label
50 |
None
51 |
52 |
53 |
noRows
54 |
The message displayed when there are no search results
55 |
None
56 |
57 |
58 |
info
59 |
Displays current range, page number, etc
60 |
61 | {start} - The first row number of the current page
62 | {end} - The last row number of the current page
63 | {page} - The current page number
64 | {pages} - Total pages
65 | {rows} - Total rows
66 |
67 |
68 |
69 |
70 |
71 | #### Example:
72 |
73 | ```javascript
74 | labels: {
75 | placeholder: "Search employees...",
76 | searchTitle: "Search within employees",
77 | perPage: "employees per page",
78 | noRows: "No employees to display",
79 | info: "Showing {start} to {end} of {rows} employees (Page {page} of {pages} pages)",
80 | },
81 | ```
82 |
--------------------------------------------------------------------------------
/docs/documentation/lastText.md:
--------------------------------------------------------------------------------
1 | ### `lastText`
2 | #### Type: `string`
3 | #### Default: `'»'`
4 |
5 | Set the content of the skip to last page button.
6 |
--------------------------------------------------------------------------------
/docs/documentation/multiSearch().md:
--------------------------------------------------------------------------------
1 | #### type `Function`
2 |
3 | Filter the table based on multiple queries.
4 |
5 | #### Usage
6 |
7 | ```javascript
8 | /**
9 | * @param { { terms: String[], columns=: Number[] }[] } queries Queries including search term and columns (optional)
10 | * @param {str} source Source of the search. (optional, used to invalidate search rows later on)
11 | * @return {void}
12 | */
13 | datatable.multiSearch(queries);
14 | ```
15 |
--------------------------------------------------------------------------------
/docs/documentation/nextPrev.md:
--------------------------------------------------------------------------------
1 | ### `nextPrev`
2 | #### Type: `integer`
3 | #### Default: `true`
4 |
5 | Toggle the next and previous pagination buttons.
--------------------------------------------------------------------------------
/docs/documentation/nextText.md:
--------------------------------------------------------------------------------
1 | ### `nextText`
2 | #### Type: `string`
3 | #### Default: `'›'`
4 |
5 | Set the content on the next button.
6 |
--------------------------------------------------------------------------------
/docs/documentation/on().md:
--------------------------------------------------------------------------------
1 | Listen for custom events.
2 |
3 | See the [Events API](Events).
4 |
--------------------------------------------------------------------------------
/docs/documentation/page().md:
--------------------------------------------------------------------------------
1 | #### type `Function`
2 |
3 | Loads a given page. Page number must be an `integer`.
4 |
5 | #### Usage
6 |
7 | ```javascript
8 | /**
9 | * @param {int} num Page Number
10 | * @return {void}
11 | */
12 | datatable.page(num);
13 | ```
--------------------------------------------------------------------------------
/docs/documentation/pagerDelta.md:
--------------------------------------------------------------------------------
1 | ### `pagerDelta`
2 | #### Type: `number`
3 | #### Default: `2`
4 |
5 | Delta used for truncating pager.
6 |
--------------------------------------------------------------------------------
/docs/documentation/pagerRender.md:
--------------------------------------------------------------------------------
1 | ### `pagerRender`
2 | #### Type: `boolean` \ `function(data, ul)`
3 | #### Default: `false`
4 |
5 |
6 | If specified, declares a callback to customise the rendering of all pagers. The function can take 2 parameters:
7 |
8 | * **data**: an array of data relevant to render the pager: `[onFirstPage: boolean, onLastPage: boolean, currentPage: number, totalPages: number]`.
9 |
10 | * **ul**: the ul in the format used by (diffDOM)[https://github.com/fiduswriter/diffDOM].
11 |
12 | You can either modify the ul in place, or you can return a new ul object in the same format.
13 |
--------------------------------------------------------------------------------
/docs/documentation/paging.md:
--------------------------------------------------------------------------------
1 | ### `paging`
2 | #### Type: `boolean`
3 | #### Default: `true`
4 |
5 | Whether paging is enabled for the table.
--------------------------------------------------------------------------------
/docs/documentation/perPage.md:
--------------------------------------------------------------------------------
1 | ### `perPage`
2 | #### Type: `integer`
3 | #### Default: `10`
4 |
5 | Sets the maximum number of rows to display on each page.
--------------------------------------------------------------------------------
/docs/documentation/perPageSelect.md:
--------------------------------------------------------------------------------
1 | ### `perPageSelect`
2 | #### Type: `array`
3 | #### Default: `[5, 10, 15, 20, 25]`
4 |
5 | Sets the per page options in the dropdown. Must be an array of integers or arrays in the format [label (string), value (int)].
6 |
7 | Values below 1 return all values.
8 |
9 | For example, you could specify the values in words like this:
10 |
11 | `[["Five", 5], ["Ten", 10], ["All", 0]]`
12 |
13 | Setting this to `false` will hide the dropdown.
--------------------------------------------------------------------------------
/docs/documentation/prevText.md:
--------------------------------------------------------------------------------
1 | ### `prevText`
2 | #### Type: `string`
3 | #### Default: `'‹'`
4 |
5 | Set the content on the previous button.
6 |
--------------------------------------------------------------------------------
/docs/documentation/print().md:
--------------------------------------------------------------------------------
1 | #### type `Function`
2 |
3 | Display printable version.
4 |
5 | #### Usage
6 |
7 | ```javascript
8 | datatable.print();
9 | ```
--------------------------------------------------------------------------------
/docs/documentation/refresh().md:
--------------------------------------------------------------------------------
1 | #### type `Function`
2 |
3 | Refreshes the table. This will recount the rows, reset any search and remove any set message, but will not reset any sorting.
4 |
5 | #### Usage
6 |
7 | ```javascript
8 | datatable.refresh();
9 | ```
--------------------------------------------------------------------------------
/docs/documentation/rowNavigation.md:
--------------------------------------------------------------------------------
1 | ### `rowNavigation`
2 | #### Type: `boolean`
3 | #### Default: `false`
4 |
5 | Enable or disable the navigation rows with keyboard.
--------------------------------------------------------------------------------
/docs/documentation/rowRender.md:
--------------------------------------------------------------------------------
1 | ### `rowRender`
2 | #### Type: `boolean` \ `function(rowValue, tr, index)`
3 | #### Default: `false`
4 |
5 |
6 | If specified, declares a callback to customise the rendering of all rows. The function can take 3 parameters:
7 |
8 | * **rowValue**: the row as it exists in `dataTable.data.data`.
9 |
10 | * **tr**: the table row in the format used by (diffDOM)[https://github.com/fiduswriter/diffDOM].
11 |
12 | * **index**: the integer representing the index of the row in `dataTable.data.data`.
13 |
14 | You can either modify the tr in place, or you can return a new tr object in the same format.
15 |
--------------------------------------------------------------------------------
/docs/documentation/rowSelectionKeys.md:
--------------------------------------------------------------------------------
1 | ### `rowSelectionKeys`
2 | #### Type: `string[]`
3 | #### Default: `["Enter", " "]`
4 |
5 | Keys that will be monitored for row selection. If the key is pressed while a row is focused, a "datatable.selectrow" event
6 | will be triggered (see [Events](Events#datatableselectrow).
7 |
8 | The default keys are `Enter` and `Space`.
9 |
--------------------------------------------------------------------------------
/docs/documentation/rows-API.md:
--------------------------------------------------------------------------------
1 | As of `v1.4.0`, the `rows` API is implemented and allows access to the table rows for quick manipulation.
2 |
3 | As of `v4.0.0`, `rows` is a property and not a method on the current instance.
4 |
5 | To use the `rows` API just access under the `rows` property of the current instance:
6 |
7 | ```javascript
8 | let rows = datatable.rows;
9 | ```
10 |
11 | You can then chain the following methods.
12 |
13 | ---
14 |
15 | ### `add(data [array])`
16 |
17 | Add new row data to the current instance. The `data` parameter must be an `array` of `strings` to be inserted into each of the new row's cells.
18 |
19 | ```javascript
20 | let newRow = ["column1", "column2", "column3", "column4", ...];
21 |
22 | dataTable.rows.add(newRow);
23 |
24 | ```
25 |
26 | **Note:** Only one row can be added at a time. If you want to add multiple rows simultaneously, do this instead:
27 |
28 | ```javascript
29 | let newRows = [
30 | ["column1", "column2", "column3", "column4", ...],
31 | ["column1", "column2", "column3", "column4", ...],
32 | ["column1", "column2", "column3", "column4", ...],
33 | ["column1", "column2", "column3", "column4", ...],
34 | ...
35 | ];
36 |
37 | dataTable.insert({data: newRows})
38 | ```
39 |
40 | ---
41 |
42 | ### `remove(select [array|number])`
43 |
44 | Remove existing rows from the current instance. The `select` parameter can either be an `integer` or `array` of `integers` representing the row indexes.
45 |
46 | ```javascript
47 | let rows = dataTable.rows;
48 |
49 | // remove the 6th row
50 | rows.remove(5);
51 |
52 | // remove the first 5 rows
53 | rows.remove([0,1,2,3,4]);
54 |
55 | ```
56 |
57 | Note that the indexes passed to this method should represent the actual index of the row in the [`data`](API#data) array. The native [`rowIndex`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLTableRowElement/rowIndex) property represents the position of a row in the rendered page and may be different to the index you need to pass to the `remove()` method.
58 |
59 | For example, if you're trying to remove a row that's unrendered, the `rowIndex` property will return `-1`.
60 |
61 | Another example would be if you're currently on page 5 and you have `perPage` set to `5` the currently rendered rows have a `rowIndex` of `0`, `1`, `2`, `3` and `4`, respectively, but to remove them you would need to use the indexes `20`, `21`, `22`, `23` and `24`, respectively.
62 |
63 | ```javascript
64 | let rows = dataTable.rows;
65 |
66 | // Switch to page 5
67 | dataTable.page(5);
68 |
69 | // WRONG: removes the first 5 rows on page 1
70 | rows.remove([0, 1, 2, 3, 4]);
71 |
72 | // CORRECT: removes the 5 currently rendered rows on page 5
73 | rows.remove([20, 21, 22, 23, 24]);
74 | ```
75 |
76 | You can quickly access the correct index for the rendered row by grabbing it's `dataset-index` property as opposed to the `rowIndex` property.
77 |
78 | ```javascript
79 | // Get the first rendered row
80 | let rowToRemove = dataTable.body.querySelector("tr");
81 |
82 | // Remove it
83 | dataTable.rows.remove(parseInt(rowToRemove.dataset.index));
84 |
85 | ```
86 |
87 | ---
88 |
--------------------------------------------------------------------------------
/docs/documentation/scrollY.md:
--------------------------------------------------------------------------------
1 | ### `scrollY`
2 | #### Type: `string`
3 | #### Default: `""`
4 |
5 | Enable vertical scrolling. Vertical scrolling will constrain the DataTable to the given height, and enable scrolling for any data which overflows the current viewport. This can be used as an alternative to paging to display a lot of data in a small area.
6 |
7 | The value given here can be given in any CSS unit.
--------------------------------------------------------------------------------
/docs/documentation/search().md:
--------------------------------------------------------------------------------
1 | #### type `Function`
2 |
3 | Filter the table based on a single query.
4 |
5 | #### Usage
6 |
7 | ```javascript
8 | /**
9 | * @param {str} term Search term
10 | * @param {int[]} columns Columns to be searched (optional)
11 | * @param {str} source Source of the search. (optional, used to invalidate search rows later on)
12 | * @return {void}
13 | */
14 | datatable.search(term, columns);
15 | ```
16 |
--------------------------------------------------------------------------------
/docs/documentation/searchMethod.md:
--------------------------------------------------------------------------------
1 | ### `searchMethod`
2 | #### Type: `function`
3 | #### Default: `undefined`
4 |
5 | A custom search method to be used for the column(s). The function should take 5 arguments:
6 | `terms` (an array of strings representing the search terms),
7 | `cell` (the cell that is to be checked for the search terms),
8 | `row` (the data row that the cell is part of),
9 | `column` (the id of the column of the cell),
10 | `source` (a unique string given to a particular search interface so that multiple search itnerfaces can be used simultaneously).
11 |
12 | It should return `true` if the search string is found in the data, `false` otherwise.
13 |
14 | The default is that it simply checks for the presence of a particular search term in the cell content.
15 |
16 | A `searchMethod` can also be defined for individual columns. If a `searchMethod` is defined for a column, it will override the
17 | default `searchMethod` defined for the table.
18 |
--------------------------------------------------------------------------------
/docs/documentation/searchQuerySeparator.md:
--------------------------------------------------------------------------------
1 | ### `searchQuerySeparator`
2 | #### Type: `string`
3 | #### Default: `" "`
4 |
5 | Influences searching in that search queries will be split with this value by default when searchign through a search box.
6 |
--------------------------------------------------------------------------------
/docs/documentation/searchable.md:
--------------------------------------------------------------------------------
1 | ### `searchable`
2 | #### Type: `boolean`
3 | #### Default: `true`
4 |
5 | Toggle the ability to search the dataset
--------------------------------------------------------------------------------
/docs/documentation/setMessage().md:
--------------------------------------------------------------------------------
1 | #### type `Function`
2 |
3 | Display a message in the table.
4 |
5 | #### Usages
6 | ```javascript
7 | /**
8 | * @param {string} message The message to show
9 | * @return {void}
10 | */
11 | dataTable.setMessage(message);
12 | ```
--------------------------------------------------------------------------------
/docs/documentation/sortable.md:
--------------------------------------------------------------------------------
1 | ### `sortable`
2 | #### Type: `boolean`
3 | #### Default: `true`
4 |
5 | Toggle the ability to sort the columns.
6 |
7 | > This option will be forced to `false` if the table has no headings.
--------------------------------------------------------------------------------
/docs/documentation/tabIndex.md:
--------------------------------------------------------------------------------
1 | ### `tabIndex`
2 | #### Type: `boolean`
3 | #### Default: `false`
4 |
5 | If specified, declares the tab index number to be used for the table. This is useful in combination with [rowNavigation](rowNavigation).
6 |
--------------------------------------------------------------------------------
/docs/documentation/tableRender.md:
--------------------------------------------------------------------------------
1 | ### `tableRender`
2 | #### Type: `boolean` \ `function(data, table, type)`
3 | #### Default: `false`
4 |
5 |
6 | If specified, declares a callback to customise the rendering of all tables. The function can take 3 parameters:
7 |
8 | * **data**: the current state of the data as it exists in `dataTable.data`.
9 |
10 | * **table**: the table in the format used by (diffDOM)[https://github.com/fiduswriter/diffDOM].
11 |
12 | * **type**: a string representing the kind of table that is being drawn: `"main"` is the regular table, `"message"` is an empty table that is to include a message to the user, `"header"` is a special header table used for `scrollY`-tables, and `"print"` when the table is being rendered for printing.
13 |
14 | You can either modify the table in place, or you can return a new table object in the same format.
15 |
--------------------------------------------------------------------------------
/docs/documentation/template.md:
--------------------------------------------------------------------------------
1 | ### `template`
2 | #### Type: `function`
3 |
4 | ### Default
5 |
6 | ```javascript
7 | (options, dom) => `
`
34 | ```
35 |
36 | Allows for custom arranging of the DOM elements in the top and bottom containers. Be aware that several of the class names are used to position specific parts of the table, such as the pager (`options.classes.pagination`), the table itself (`options.classes.container`) and the pagination selector (`options.classes.selector`). There can be several pagers.
37 |
38 | There can be multiple search fields and you can influence how they operate by adding `data-column`, `data-query-separator` and `data-and` attributes to them. `data-column` is to be a JSON array of column indices that the search is to operate on. The `data-query-separator` will be used to split the search value for individual search items. The `data-and` attribute will change the search from an OR-search to an AND-search. Default values can be specified as `searchQuerySeparator` and `searchAnd` options.
39 |
40 | For example: ``
41 |
--------------------------------------------------------------------------------
/docs/documentation/truncatePager.md:
--------------------------------------------------------------------------------
1 | ### `truncatePager`
2 | #### Type: `boolean`
3 | #### Default: `true`
4 |
5 | Truncate the page links to prevent overflow with large datasets.
--------------------------------------------------------------------------------
/docs/documentation/update().md:
--------------------------------------------------------------------------------
1 | #### type `Function`
2 |
3 | Updates the dom of the table. Needs to be called after you change the data of `datatable.data` manually or you changed things inside of `datatable.columns.settings`, etc. The argument `measureWidths` will determine whether the needed widths of the columns will be measured again. The columns need to measured again if any change that was made could have lead to differently sized columns.
4 |
5 | #### Usage
6 |
7 | ```javascript
8 | datatable.update(measureWidths=false);
9 | ```
10 |
--------------------------------------------------------------------------------
/docs/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/fiduswriter/simple-datatables/e070774d1e07647ea335d53bba20cd520b76826a/docs/favicon.ico
--------------------------------------------------------------------------------
/docs/favicon.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/fiduswriter/simple-datatables/e070774d1e07647ea335d53bba20cd520b76826a/docs/favicon.png
--------------------------------------------------------------------------------
/docs/favicon.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/docs/index.html:
--------------------------------------------------------------------------------
1 |
2 |
3 |
4 |
5 |
6 | simple-datatables
7 |
8 |
9 |
10 |
11 |