@logimaxx/kgrid 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,337 @@
1
+ # Configuration reference
2
+
3
+ KGrid tables are driven by a JSON **options** object passed to `KGrid.init(host, opts)`. The host is a DOM element or jQuery object (empty, or already containing a `<table class="custom-table">`).
4
+
5
+ Table-level options are merged with `KGrid.protoOptions`. Each entry in `columns` is deep-merged with `KGrid.protoColumnConfig` via `KGrid.setDefaultValues`.
6
+
7
+ **You must pass a `columns` array.** KGrid does not infer columns from your API or local `data` — every field needs an explicit column definition. View text defaults to `{{attribute_name}}` per column; configure `filter`, `insert`, and `update` when those features are enabled.
8
+
9
+ ---
10
+
11
+ ## Complete example
12
+
13
+ Typical remote JSON:API table with filter, sort, paging, and CRUD. This is the shape to aim for; the sections below explain each part.
14
+
15
+ ```javascript
16
+ await KGrid.init(document.getElementById("grid-host"), {
17
+ // --- data source (remote) ---
18
+ url: "/api/products",
19
+ updateUrl: "/api/products",
20
+ deleteUrl: "/api/products",
21
+ insertUrl: "/api/products",
22
+ type: "products",
23
+
24
+ // --- table features (all default false) ---
25
+ defaultInteraction: "view",
26
+ features: {
27
+ filtering: true,
28
+ sorting: true,
29
+ paging: true,
30
+ create: true,
31
+ update: true,
32
+ delete: true,
33
+ },
34
+ insertFormRow: { position: "top" },
35
+ noDataTemplate: "<td colspan='99'>No records match your filters.</td>",
36
+
37
+ // --- columns: required; one object per field ---
38
+ columns: [
39
+ {
40
+ name: "id",
41
+ label: "ID",
42
+ hidden: true,
43
+ insert: { type: "hidden", events: [] },
44
+ update: { type: "hidden", events: [] },
45
+ },
46
+ {
47
+ name: "name",
48
+ label: "Name",
49
+ features: { sort: true, filter: true, create: true, update: true },
50
+ // use template to output custom HTML otherwise it will default to {{name}}
51
+ display: { template: "<strong>{{name}}</strong>"},
52
+ filter: { type: "text", operator: "~=~" },
53
+ insert: { type: "text", required: true, events: [] },
54
+ update: { type: "text", events: [] },
55
+ },
56
+ {
57
+ name: "category",
58
+ label: "Category",
59
+ features: { filter: true, create: true, update: true },
60
+ filter: {
61
+ type: "select",
62
+ operator: "=",
63
+ options: [
64
+ { label: "All", value: "" },
65
+ { label: "Hardware", value: "hardware" },
66
+ ],
67
+ },
68
+ insert: {
69
+ type: "select",
70
+ options: [{ label: "Hardware", value: "hardware" }],
71
+ events: [],
72
+ },
73
+ update: {
74
+ type: "select",
75
+ options: [{ label: "Hardware", value: "hardware" }],
76
+ events: [],
77
+ },
78
+ },
79
+ ],
80
+ });
81
+ ```
82
+
83
+ Local data only — omit URLs and pass rows as plain objects:
84
+
85
+ ```javascript
86
+ await KGrid.init(host, {
87
+ data: [{ id: 1, name: "Alpha", category: "hardware" }],
88
+ features: { filtering: true, sorting: true },
89
+ columns: [/* same column shape as above */],
90
+ });
91
+ ```
92
+
93
+ ---
94
+
95
+ ## How the example fits together
96
+
97
+ | Block | Role |
98
+ |-------|------|
99
+ | `url` + `type` | Load JSON:API collection via KViews (`updateUrl` / `deleteUrl` / `insertUrl` for per-item CRUD) |
100
+ | `data` | Alternative to `url` — local array, no remote load |
101
+ | `features` | Turn on filter row, sortable headers, paging footer, insert row, inline edit, row delete |
102
+ | `defaultInteraction` | `"view"` (read-only cells) or `"edit"` (inputs + row-actions column) |
103
+ | `columns` | **Required** — defines every field the table knows about |
104
+
105
+ ### Column checklist
106
+
107
+ For **each** column object:
108
+
109
+ 1. Set `name` (required when that column uses sort, filter, create, or update).
110
+ 2. Set `label` (header text).
111
+ 3. Set column `features`: which of `sort`, `filter`, `create`, `update` apply to this field.
112
+ 4. Configure the **field blocks** that match those features:
113
+
114
+ | When enabled | Configure | Purpose |
115
+ |--------------|-----------|---------|
116
+ | View mode (optional) | `display` | Custom Handlebars HTML or click handlers; omit for `{{name}}` |
117
+ | `features.filter` + table `features.filtering` | `filter` | Filter control in header (`type`, `operator`, `options` for selects) |
118
+ | `features.create` + table `features.create` | `insert` | Control in the new-record row (`type`, `required`, `options`, …) |
119
+ | `features.update` + table `features.update` | `update` | Inline edit control in data rows |
120
+
121
+ Proto defaults fill gaps: view cells use `{{name}}` when `display` is omitted; `insert`/`update` default to `type: "text"`. **Select-like types need `options`**, pluggable types need `KGrid.configure()` hooks, and **`events` must be an array** on `insert` and `update` when you define those blocks (use `events: []` when you have no handlers).
122
+
123
+ Table `features.*` gates whole UI regions; column `features.*` gates controls inside those regions. Example: `features.filtering: true` on the table plus `features.filter: true` on a column plus a `filter: { type: "text", … }` block produces a filter input for that column.
124
+
125
+ ---
126
+
127
+ ## Table options
128
+
129
+ ### Data source
130
+
131
+ Provide **either** a remote URL **or** a local array:
132
+
133
+ | Option | Type | Description |
134
+ |--------|------|-------------|
135
+ | `url` | `string` | Primary collection URL (load/list) |
136
+ | `deleteUrl` | `string` | Delete endpoint (per-item: `url/id`) |
137
+ | `updateUrl` | `string` | Update endpoint (per-item: `url/id`) |
138
+ | `insertUrl` | `string` | Insert endpoint (collection URL) |
139
+ | `data` | `array` | Local rows as plain objects (no `url`) |
140
+ | `type` | `string` | JSON:API resource type (e.g. `products`) — passed to KViews |
141
+ | `kviews` | `object` | Optional KViews override for this table only |
142
+
143
+ `init` throws if both `url` and `data` are missing.
144
+
145
+ ### Features
146
+
147
+ All default to `false`:
148
+
149
+ ```javascript
150
+ features: {
151
+ filtering: false,
152
+ sorting: false,
153
+ paging: false,
154
+ create: false,
155
+ update: false,
156
+ delete: false,
157
+ }
158
+ ```
159
+
160
+ ### Row actions column
161
+
162
+ When any of `create`, `update`, or `delete` is enabled, KGrid adds a trailing column for row controls (delete, save/cancel, insert submit). The same rule is used everywhere so header, filter row, data rows, and `colspan` stay aligned:
163
+
164
+ ```javascript
165
+ KGrid.hasActionColumn(options)
166
+ // true when features.delete || features.update || features.create
167
+ ```
168
+
169
+ | Markup | Role |
170
+ |--------|------|
171
+ | `th` / `td.kgrid-row-actions` | Header, filters, data rows |
172
+ | `colgroup col.kgrid-row-actions-col` | Width control for `table-layout: fixed` (added at init via `syncActionColumnColgroup`) |
173
+
174
+ **View vs edit:** In **view** mode (`data-interaction="view"`), the row-actions column is collapsed (`visibility: collapse`, zero width) so data columns use the full table width. In **edit** mode, the column is shown (~100px) with delete / save / cancel buttons and the insert-row submit cell.
175
+
176
+ The new-record row (`.new-record-row`) uses the same `kgrid-row-actions` class on its submit cell; the whole insert row is hidden in view mode via existing CSS.
177
+
178
+ Override delete UX per table: `deleteConfirm` (see below and [integration.md](integration.md#deleteconfirm-row-delete)).
179
+
180
+ ### Interaction mode
181
+
182
+ | Option | Type | Default | Description |
183
+ |--------|------|---------|-------------|
184
+ | `defaultInteraction` | `'view' \| 'edit'` | `'view'` | Initial UI mode |
185
+ | `editmode` | `boolean` | — | **Deprecated.** Use `defaultInteraction` |
186
+
187
+ CSS on `.custom-table-shell`: `data-interaction="view|edit"`. Optional overrides: `k.setInteraction('edit', { create, update, delete })`.
188
+
189
+ ### Insert row
190
+
191
+ | Option | Type | Default | Description |
192
+ |--------|------|---------|-------------|
193
+ | `insertFormRow.position` | `'top' \| 'bottom'` | `'top'` | New-record row position |
194
+ | `onNewItemCreated` | `function(data)` | — | After successful insert |
195
+ | `onInsertRowReady` | `function(form, row)` | — | After insert row DOM is built |
196
+ | `onRowFields` | `function(item, view, table)` | — | After each data row render / field mount |
197
+ | `deleteConfirm` | `(context, onConfirm, onCancel?) => void` | — | Row delete UX for this table; overrides `KGrid.configure({ deleteConfirm })` |
198
+
199
+ `deleteConfirm` receives `{ item, view, options }`. Call `onConfirm()` to delete; `onCancel()` to dismiss. See [integration.md](integration.md#deleteconfirm-row-delete).
200
+
201
+ ### Presentation
202
+
203
+ | Option | Type | Description |
204
+ |--------|------|-------------|
205
+ | `noDataTemplate` | `string` (HTML) | Empty-state row in `.no-data-tbody` |
206
+ | `tableAttrs` | `object` | Attributes on `<table>` |
207
+ | `labelsRowAttrs` | `object` | Label header row |
208
+ | `dataRowAttrs` | `object` | Data `<tr>` template |
209
+ | `filtersRowAttrs` | `object` | Filter row |
210
+ | `pagingFooterAttrs` | `object` | Paging `<tfoot>` |
211
+ | `setAttrAsId` | `boolean` | Passed to KViews |
212
+
213
+ ### Event handlers map
214
+
215
+ Column events may reference callbacks by **name**:
216
+
217
+ ```javascript
218
+ {
219
+ handlers: { onNameClick: function (e, item, view) { /* ... */ } },
220
+ columns: [{
221
+ name: "name",
222
+ display: {
223
+ template: '<a href="#">{{name}}</a>',
224
+ events: [{ selector: "a", event: "click", callback: "onNameClick" }],
225
+ },
226
+ insert: { type: "text", events: [] },
227
+ update: { type: "text", events: [] },
228
+ }],
229
+ }
230
+ ```
231
+
232
+ Insert/update handlers must resolve to functions at `init` or initialization throws. Display handlers: a missing name leaves the string and fails at click time.
233
+
234
+ Also resolvable via `options.functions[callbackName]`.
235
+
236
+ ---
237
+
238
+ ## Column configuration
239
+
240
+ Each element of `columns: []`:
241
+
242
+ | Field | Type | Description |
243
+ |-------|------|-------------|
244
+ | `name` | `string` | Field name (**required** for sort, filter, create, update on that column) |
245
+ | `label` | `string` | Header text |
246
+ | `hidden` | `boolean` | Hide from UI; may still participate in forms (e.g. `id` as `hidden`) |
247
+ | `class` / `columnClass` | `string` | CSS class on label/filter/data/insert cells; sets `data-name` |
248
+ | `attrs` | `object` | HTML attributes on header/cells |
249
+ | `input` | `object` | Shared defaults for `insert` + `update` (explicit blocks win) |
250
+ | `features` | `object` | `create`, `update`, `filter`, `sort` per column (default all `false`) |
251
+
252
+ ### Display (`display`)
253
+
254
+ **Optional.** If you omit `display`, view-mode cells render `{{name}}` using the column’s `name`.
255
+
256
+ Set `display` only when you need custom markup or DOM events:
257
+
258
+ | Field | Type | Description |
259
+ |-------|------|-------------|
260
+ | `template` | `string` | Handlebars HTML; defaults to `{{name}}` when omitted |
261
+ | `events` | `array` | `{ selector, event, callback }`; defaults to `[]` from proto |
262
+
263
+ Use simple `{{field}}` in templates. KGrid does not ship Handlebars helpers (`eq`, `#if` on arbitrary helpers, etc.).
264
+
265
+ ### Insert / update (`insert`, `update`)
266
+
267
+ | Field | Type | Description |
268
+ |-------|------|-------------|
269
+ | `type` | `string` | See [field-types.md](field-types.md) |
270
+ | `default` | `any` | Insert default |
271
+ | `value` | `any` | Update value / select2 `{ value, label }` |
272
+ | `placeholder` | `string` | |
273
+ | `disabled` / `readonly` / `required` | `boolean` | |
274
+ | `dontsave` | `boolean` | Omit on submit |
275
+ | `options` | `array` \| `object` | **Required** for `select` (and similar) when create/update is enabled |
276
+ | `attrs` | `object` | Extra HTML attributes |
277
+ | `events` | `array` | `{ event, callback }` — use `[]` if none |
278
+
279
+ Check types with `KGrid.isValidInputType(type)`.
280
+
281
+ ### Filter (`filter`)
282
+
283
+ | Field | Type | Default | Description |
284
+ |-------|------|---------|-------------|
285
+ | `type` | `string` | `text` | Control type |
286
+ | `operator` | `string` | `~=~` | `data-operator` for KViews (`~=~`, `=`, …) |
287
+ | `default` | `any` | | Initial value |
288
+ | `placeholder` | `string` | `""` | |
289
+ | `options` | `array` \| `object` | | For `select`, `multi_select`, `select2`, … |
290
+ | `persist` | `boolean` | `false` | Re-apply `default` on filter reset (also implied when column `hidden` or `type: "hidden"`) |
291
+ | `debounceMs` | `number` | `configure({ filterDebounceMs })` | Ms to wait after typing before filter API call; `0` = immediate |
292
+
293
+ Check types with `KGrid.isValidFilterType(type)`.
294
+
295
+ Filter controls use `form=""` pointing at a hidden `<form>` (rows cannot wrap one `<form>`). Filter submits are debounced by default (`filterDebounceMs: 300`); set `debounceMs: 0` on a column/filter to make that control submit immediately.
296
+
297
+ ---
298
+
299
+ ## Field types (summary)
300
+
301
+ | Type | Context | Notes |
302
+ |------|---------|--------|
303
+ | Native HTML | filter, insert, update | `text`, `number`, `select`, … |
304
+ | `multi_select` | filter | Built-in |
305
+ | `date_range` | filter | Built-in single date input |
306
+ | `select2` | filter, insert, update | `customInputTypes: { select2: KGrid.select2(fn) }` + `kgrid-widgets.js` |
307
+ | `autosuggest` | filter, insert, update | `customInputTypes: { autosuggest: KGrid.autosuggest(fn) }` + `kgrid-widgets.js` |
308
+ | Custom | any | `customInputTypes` or `registerFieldType` |
309
+
310
+ Details: [field-types.md](field-types.md).
311
+
312
+ ---
313
+
314
+ ## Shell / DOM (generated by KGrid)
315
+
316
+ Pass an **empty host element** to `KGrid.init`. KGrid parses `KGrid.TABLE_SHELL_TEMPLATE` (HTML in `src/table-shell.js`), substitutes placeholders from the options below, and appends the `<table>`.
317
+
318
+ Full guide: **[table-shell.md](table-shell.md)**.
319
+
320
+ ### Shell options
321
+
322
+ | Option | Default | Description |
323
+ |--------|---------|-------------|
324
+ | `pagingPageSizes` | `[10, 25, 50, 75]` | Values for `<select class="pagesize">` (`{{PAGE_SIZE_OPTIONS}}`) |
325
+ | `pagingDefaultSize` | `10` | Selected page size and `data-pagesize` on `.pages` |
326
+ | `emptyRowMessage` | `"No records match your search."` | `{{EMPTY_ROW_MESSAGE}}` in `.no-data-tbody` |
327
+ | `pagingFooterLabel` | `"records per page. Total"` | `{{PAGING_FOOTER_LABEL}}` before `.totalrecscount` |
328
+
329
+ `noDataTemplate` still replaces the empty row content after init.
330
+
331
+ ### Custom markup
332
+
333
+ - **Edit** `TABLE_SHELL_TEMPLATE` in the library source, or
334
+ - **Pre-insert** your own `<table class="custom-table">` in the host (KGrid skips generation), or
335
+ - Call `KGrid.renderTableShellHtml(opts, yourTemplate)` when building manually.
336
+
337
+ Row forms are hidden anchors inside cells (`form=""` on controls).
@@ -0,0 +1,92 @@
1
+ # Field types
2
+
3
+ KGrid builds filter, insert, and update controls from `filter.type`, `insert.type`, and `update.type`.
4
+
5
+ | Category | Examples | Setup |
6
+ |----------|----------|--------|
7
+ | **Native HTML** | `text`, `number`, `select`, … | Built in |
8
+ | **DOM built-ins** | `multi_select`, `date_range` | Built in |
9
+ | **Your widgets** | `select2`, `autosuggest`, anything | `configure({ customInputTypes })` |
10
+
11
+ Check types: `KGrid.isValidInputType(type)`, `KGrid.isValidFilterType(type)`.
12
+
13
+ ## Custom input types (one pattern)
14
+
15
+ Register plugins once in `configure`. Each value must be a **plugin** — an object with at least `create()`:
16
+
17
+ ```javascript
18
+ KGrid.configure({
19
+ customInputTypes: {
20
+ select2: KGrid.select2(select2wrapper), // after kgrid-widgets.js
21
+ autosuggest: KGrid.autosuggest(function ($i, o) { return $i.autosuggest(o); }),
22
+ rating: {
23
+ create() {
24
+ return { $input: $("<input type='range' min='1' max='5'/>") };
25
+ },
26
+ },
27
+ },
28
+ });
29
+ ```
30
+
31
+ Columns use the name: `filter: { type: "select2", options: { url, idFld, labelFld } }`.
32
+
33
+ Remove a type with `null`: `customInputTypes: { select2: null }`.
34
+
35
+ ### Lifecycle (what the plugin does)
36
+
37
+ 1. **`create({ mode, col, config })`** — build the control; return `{ $input: jQuery }`.
38
+ 2. **`mount({ mode, $input, config, col, … })`** — optional; init Select2, autosuggest, etc. after the node is in the table.
39
+ 3. **`validate?(config, mode, col)`** — optional; throw on bad column config.
40
+ 4. **`filterEvents?`** — optional on the plugin (or on the object returned from `create()` in filter mode): jQuery event names that submit the filter form (`"change"`, `"input"`, …). Set `false` when the widget only uses `bindFilterSubmit` (e.g. Select2). If omitted: `"change"` for `<select>`, `"input"` otherwise.
41
+ 5. **`filterDebounceMs?`** — optional on plugin; column `filter.debounceMs` overrides. Global default: `KGrid.configure({ filterDebounceMs: 300 })`. When `debounceMs > 0`, filter submissions are debounced for the resolved submit event (`"input"` or `"change"` depending on control).
42
+ 6. **`bindFilterSubmit?($input, onSubmit)`** — optional; widget-specific events (`select2:select`, …) in addition to `filterEvents`.
43
+
44
+ ### Helpers
45
+
46
+ | Helper | Use for |
47
+ |--------|---------|
48
+ | `KGrid.select2(wrapper)` | Select2 (`integrations/kgrid-widgets.js`) |
49
+ | `KGrid.autosuggest(wrapper)` | Autosuggest (same file) |
50
+ | `KGrid.inputType(mount, { element })` | Any “static HTML + mount widget” control |
51
+
52
+ Simple custom control without an integration file:
53
+
54
+ ```javascript
55
+ customInputTypes: {
56
+ color: KGrid.inputType(
57
+ function ($input) { /* init widget */ },
58
+ { element: "<input type='color' class='form-control form-control-sm'/>", filterEvents: "change" }
59
+ ),
60
+ }
61
+ ```
62
+
63
+ ### Minimal example (no extra libraries)
64
+
65
+ See [`integrations/kgrid-plugin-demo-select.js`](../integrations/kgrid-plugin-demo-select.js) and the [demo](../demo/) **Category** column:
66
+
67
+ ```javascript
68
+ KGrid.configure({
69
+ customInputTypes: { demo_select: KGrid.demoSelect() },
70
+ });
71
+ // column: filter / insert / update { type: "demo_select", options: [...] }
72
+ ```
73
+
74
+ ### Load order (Select2 / autosuggest)
75
+
76
+ 1. jQuery, KViews, `kgrid.js`
77
+ 2. `integrations/kgrid-widgets.js` (defines `KGrid.select2`, `KGrid.autosuggest`)
78
+ 3. Select2 / autosuggest libraries
79
+ 4. `KGrid.configure({ customInputTypes: … })`
80
+ 5. `KGrid.init(…)`
81
+
82
+ ## Native HTML & built-ins
83
+
84
+ See previous sections in this file for `select`, `multi_select`, `date_range`. Native types need no registration.
85
+
86
+ ## Direct API
87
+
88
+ `KGrid.registerFieldType(name, plugin)` — same plugin shape; useful in tests or dynamic registration.
89
+
90
+ ## Display templates
91
+
92
+ `display.template` uses KViews/Handlebars. Keep templates simple (`{{field}}`) unless your app registers helpers globally.
@@ -0,0 +1,81 @@
1
+ # Integration guide
2
+
3
+ ## Load order
4
+
5
+ 1. jQuery
6
+ 2. KViews
7
+ 3. `dist/kgrid.js`
8
+ 4. Optional: `integrations/kgrid-widgets.js` + widget libraries (Select2, autosuggest)
9
+ 5. `KGrid.configure({ … })`
10
+ 6. `KGrid.init(host, opts)`
11
+
12
+ ## Minimal config
13
+
14
+ ```javascript
15
+ KGrid.configure({
16
+ onError: function (err) { console.error(err); },
17
+ deleteConfirm: function (ctx, ok, cancel) {
18
+ if (confirm("Delete?")) ok(); else if (cancel) cancel();
19
+ },
20
+ });
21
+ ```
22
+
23
+ ## Custom input types
24
+
25
+ Optional widgets (Select2, autosuggest, your own):
26
+
27
+ ```javascript
28
+ // After kgrid-widgets.js
29
+ KGrid.configure({
30
+ customInputTypes: {
31
+ select2: KGrid.select2(function ($input, options) {
32
+ $input.select2({ ajax: { url: options.url, dataType: "json" } });
33
+ }),
34
+ autosuggest: KGrid.autosuggest(function ($input, options) {
35
+ return $input.autosuggest(options);
36
+ }),
37
+ },
38
+ });
39
+ ```
40
+
41
+ Use `type: "select2"` / `type: "autosuggest"` in column filter, insert, or update config.
42
+
43
+ Details: [field-types.md](field-types.md).
44
+
45
+ ## KViews
46
+
47
+ Resolved from `init({ kviews })`, then `configure({ kviews })`, then `window.KViews`.
48
+
49
+ ```javascript
50
+ import KViews from "@logimaxx/kviews";
51
+ KGrid.configure({ kviews: KViews });
52
+ ```
53
+
54
+ ## Delete confirmation
55
+
56
+ ```javascript
57
+ KGrid.configure({
58
+ deleteConfirm: function (context, onConfirm, onCancel) {
59
+ myApp.modal.confirm("Delete?").then(function (ok) {
60
+ if (ok) onConfirm();
61
+ else if (onCancel) onCancel();
62
+ });
63
+ },
64
+ });
65
+ ```
66
+
67
+ Per-table: pass `deleteConfirm` in `init(host, { deleteConfirm, … })`.
68
+
69
+ ## MAXXOPS example
70
+
71
+ [`integrations/maxxops.example.js`](../integrations/maxxops.example.js)
72
+
73
+ ## Styling
74
+
75
+ ```html
76
+ <link rel="stylesheet" href="node_modules/@logimaxx/kgrid/styles/table.css">
77
+ ```
78
+
79
+ Bootstrap and Font Awesome are recommended for the default paging/sort UI.
80
+
81
+ See [table-shell.md](table-shell.md) for the DOM contract.
@@ -0,0 +1,110 @@
1
+ # Table shell template
2
+
3
+ KGrid does not require you to write table HTML. On `KGrid.init(host, opts)`, an **empty host** is filled with markup from an internal HTML template.
4
+
5
+ ## Where the template lives
6
+
7
+ | Location | Purpose |
8
+ |----------|---------|
9
+ | `src/table-shell.js` → `KGrid.TABLE_SHELL_TEMPLATE` | Default markup (edit when forking KGrid) |
10
+ | `KGrid.renderTableShellHtml(options, template?)` | Runtime: pass your own HTML string |
11
+ | Host with existing `<table>` | Skip generation; use your markup |
12
+
13
+ After `npm install`, the template is inside the built bundle (`dist/kgrid.js`). To change defaults in a consuming app without patching the package, pass a custom template to `renderTableShellHtml` before mount (see below).
14
+
15
+ ## DOM structure
16
+
17
+ ```
18
+ .custom-table-shell ← class added on host if missing
19
+ table.custom-table
20
+ colgroup.kgrid-colgroup ← injected at init (data cols + optional row-actions col)
21
+ thead.thead-labels ← one <th> template; cloned per column in labels.js
22
+ thead.thead-filters ← filter inputs (if features.filtering)
23
+ tbody.before-main-tbody ← insert row when position: top
24
+ tbody.main-tbody ← KViews collection rows
25
+ tbody.after-main-tbody ← insert row when position: bottom
26
+ tbody.no-data-tbody ← empty state
27
+ tfoot.paging-footer ← removed when features.paging is false
28
+ ```
29
+
30
+ Required class names and regions are part of the public contract — `setupLabelsHeader`, `setupFilterHeader`, `setupDataBody`, etc. depend on them.
31
+
32
+ ## Template placeholders
33
+
34
+ Static HTML uses `{{NAME}}` slots filled by `renderTableShellHtml`:
35
+
36
+ | Placeholder | Table option | Description |
37
+ |-------------|--------------|-------------|
38
+ | `{{EMPTY_ROW_MESSAGE}}` | `emptyRowMessage` | Text in `.no-data-tbody` (HTML-escaped) |
39
+ | `{{PAGES_DATA_PAGESIZE}}` | `pagingDefaultSize` | `data-pagesize` on `.pages` |
40
+ | `{{PAGE_SIZE_OPTIONS}}` | `pagingPageSizes` + `pagingDefaultSize` | `<option>` lines for `.pagesize` |
41
+ | `{{PAGING_FOOTER_LABEL}}` | `pagingFooterLabel` | Text before `.totalrecscount` (escaped) |
42
+
43
+ Defaults (from `protoOptions`):
44
+
45
+ ```javascript
46
+ pagingPageSizes: [10, 25, 50, 75],
47
+ pagingDefaultSize: 10,
48
+ emptyRowMessage: null, // → "No records match your search."
49
+ pagingFooterLabel: "records per page. Total",
50
+ ```
51
+
52
+ `noDataTemplate` in table options still overrides the empty row **after** init (via `setupNoDataTbody`).
53
+
54
+ ## Customize defaults in table options
55
+
56
+ ```javascript
57
+ await KGrid.init("#grid", {
58
+ url: "/api/items",
59
+ type: "items",
60
+ emptyRowMessage: "No items found.",
61
+ pagingPageSizes: [5, 10, 25],
62
+ pagingDefaultSize: 5,
63
+ pagingFooterLabel: "rows per page. Total",
64
+ columns: [/* ... */],
65
+ });
66
+ ```
67
+
68
+ ## Custom HTML template
69
+
70
+ Keep the same class names and one sortable `<th>` template in `.thead-labels`. You may use the same four placeholders.
71
+
72
+ ```javascript
73
+ const myTemplate = `
74
+ <table class="custom-table" style="table-layout: fixed;">
75
+ <!-- same regions as TABLE_SHELL_TEMPLATE -->
76
+ <tbody class="no-data-tbody"><tr><td>{{EMPTY_ROW_MESSAGE}}</td></tr></tbody>
77
+ <!-- ... -->
78
+ </table>`.trim();
79
+
80
+ const html = KGrid.renderTableShellHtml(opts, myTemplate);
81
+ const $table = $(jQuery.parseHTML(html, document, true)).filter("table");
82
+ $("#host").addClass("custom-table-shell").append($table);
83
+ // then run setup manually, or init on host that already contains $table[0]
84
+ ```
85
+
86
+ Simplest path: put your table inside the host before init — KGrid detects it and skips generation:
87
+
88
+ ```html
89
+ <div id="grid">
90
+ <table class="custom-table">…your structure…</table>
91
+ </div>
92
+ ```
93
+
94
+ ## Styling and icons
95
+
96
+ - Include `styles/table.css` from the package (required for view/edit modes and row-actions column collapse).
97
+ - The default template uses **Bootstrap** button classes (`btn`, `btn-sm`, …) and **Font Awesome** sort icons (`fa-sort`, `fa-sort-up`, `fa-sort-down`). Load both in the host page, or edit the template to match your design system.
98
+
99
+ If you provide your own `<table>` in the host, call `KGrid.init` as usual — `syncActionColumnColgroup` still runs when row actions are enabled.
100
+
101
+ ## API
102
+
103
+ | Method | Description |
104
+ |--------|-------------|
105
+ | `KGrid.TABLE_SHELL_TEMPLATE` | Default HTML string |
106
+ | `KGrid.renderTableShellHtml(options, template?)` | Substitute placeholders |
107
+ | `KGrid.createTableShell(options)` | Template → jQuery `<table>` (applies `tableAttrs`) |
108
+ | `KGrid.mountTableShell($host, options)` | Append table when host has none |
109
+
110
+ See also [configuration.md](configuration.md) and [api.md](api.md).