@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.
- package/AGENTS.md +9 -0
- package/LICENSE +34 -0
- package/NOTICE.md +24 -0
- package/README.md +151 -0
- package/dist/kgrid.js +2051 -0
- package/dist/kgrid.min.js +2 -0
- package/docs/ai-guide.md +273 -0
- package/docs/api.md +191 -0
- package/docs/configuration.md +337 -0
- package/docs/field-types.md +92 -0
- package/docs/integration.md +81 -0
- package/docs/table-shell.md +110 -0
- package/integrations/kgrid-plugin-demo-select.js +99 -0
- package/integrations/kgrid-widgets.js +136 -0
- package/integrations/maxxops.example.js +16 -0
- package/package.json +57 -0
- package/src/cells.js +113 -0
- package/src/config.js +59 -0
- package/src/configure.js +136 -0
- package/src/constants.js +113 -0
- package/src/data-body.js +99 -0
- package/src/dom.js +123 -0
- package/src/events.js +100 -0
- package/src/field-types-builtins.js +25 -0
- package/src/field-types.js +228 -0
- package/src/filters.js +394 -0
- package/src/init.js +199 -0
- package/src/insert-row.js +172 -0
- package/src/interaction.js +43 -0
- package/src/labels.js +49 -0
- package/src/table-shell.js +152 -0
- package/styles/table.css +201 -0
|
@@ -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).
|