@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/src/filters.js ADDED
@@ -0,0 +1,394 @@
1
+ (function (CT) {
2
+ const FILTER_DEBOUNCE_TIMER_KEY = "kgridFilterDebounceTimer";
3
+
4
+ /**
5
+ * Cancel a pending debounced filter submit on one control.
6
+ * @param {JQuery} $input
7
+ */
8
+ CT.cancelFilterSubmit = function ($input) {
9
+ const timer = $input.data(FILTER_DEBOUNCE_TIMER_KEY);
10
+ if (timer) {
11
+ clearTimeout(timer);
12
+ $input.removeData(FILTER_DEBOUNCE_TIMER_KEY);
13
+ }
14
+ };
15
+
16
+ /**
17
+ * Cancel debounced submits for all fields associated with a filter form.
18
+ * @param {HTMLFormElement|JQuery} form
19
+ */
20
+ CT.cancelFilterDebounces = function (form) {
21
+ const formId = $(form).attr("id");
22
+ if (!formId) {
23
+ return;
24
+ }
25
+ $(document)
26
+ .find("[form='" + formId + "']")
27
+ .each(function () {
28
+ CT.cancelFilterSubmit($(this));
29
+ });
30
+ };
31
+
32
+ /**
33
+ * Run a pending debounced submit immediately, if any.
34
+ * @param {JQuery} $input
35
+ */
36
+ CT.flushFilterSubmit = function ($input) {
37
+ const timer = $input.data(FILTER_DEBOUNCE_TIMER_KEY);
38
+ if (!timer) {
39
+ return;
40
+ }
41
+ clearTimeout(timer);
42
+ $input.removeData(FILTER_DEBOUNCE_TIMER_KEY);
43
+ const form = $input[0] && $input[0].form;
44
+ if (form) {
45
+ $(form).trigger("submit");
46
+ }
47
+ };
48
+
49
+ /**
50
+ * Optionally debounce filter submit (see resolveFilterDebounceMs / shouldDebounceFilterSubmit).
51
+ * @param {JQuery} $input
52
+ * @param {Function} onSubmit bound with control as `this`
53
+ * @param {string|null} events resolved filter events
54
+ * @param {number} debounceMs
55
+ * @returns {Function}
56
+ */
57
+ CT.wrapFilterSubmitHandler = function ($input, onSubmit, events, debounceMs) {
58
+ if (!CT.shouldDebounceFilterSubmit(events, debounceMs)) {
59
+ return onSubmit;
60
+ }
61
+ const delay = debounceMs;
62
+ return function filterSubmitDebounced() {
63
+ CT.cancelFilterSubmit($input);
64
+ const timer = setTimeout(
65
+ function () {
66
+ $input.removeData(FILTER_DEBOUNCE_TIMER_KEY);
67
+ onSubmit.call(this);
68
+ }.bind(this),
69
+ delay
70
+ );
71
+ $input.data(FILTER_DEBOUNCE_TIMER_KEY, timer);
72
+ };
73
+ };
74
+
75
+ CT.filterDefaultValue = function (defaultSpec) {
76
+ if (defaultSpec != null && typeof defaultSpec === "object" && defaultSpec.value != null) {
77
+ return defaultSpec.value;
78
+ }
79
+ return defaultSpec;
80
+ };
81
+
82
+ /** Hidden / persist filters survive reset and stay out of the visible filter row when appropriate. */
83
+ CT.columnFilterPersisted = function (col) {
84
+ const filter = col && col.filter ? col.filter : {};
85
+ return !!(col && (col.hidden || filter.type === "hidden" || filter.persist));
86
+ };
87
+
88
+ /**
89
+ * Ensure a named filter field exists on the hidden form (creates hidden input if needed).
90
+ * @returns {HTMLInputElement|null}
91
+ */
92
+ CT.ensureFilterField = function (formEl, name, value, operator) {
93
+ if (!formEl || !name || value == null || value === "") {
94
+ return null;
95
+ }
96
+ let field = formEl.elements && formEl.elements.namedItem(name);
97
+ if (field && field.length != null && !field.tagName) {
98
+ field = field[0];
99
+ }
100
+ if (!field || !field.tagName) {
101
+ field = document.createElement("input");
102
+ field.type = "hidden";
103
+ field.name = name;
104
+ formEl.appendChild(field);
105
+ }
106
+ field.setAttribute("data-operator", operator || "=");
107
+ field.value = String(value);
108
+ field.defaultValue = String(value);
109
+ return field;
110
+ };
111
+
112
+ CT.applyColumnDefaultFilters = function (formEl, columns) {
113
+ if (!formEl || !columns) {
114
+ return;
115
+ }
116
+ columns.forEach(function (col) {
117
+ if (!col.name || (col.features && col.features.filter === false)) {
118
+ return;
119
+ }
120
+ const filter = col.filter;
121
+ if (!filter || filter.default == null || filter.default === "") {
122
+ return;
123
+ }
124
+ const value = CT.filterDefaultValue(filter.default);
125
+ if (value == null || value === "") {
126
+ return;
127
+ }
128
+ const operator =
129
+ filter.operator || (CT.columnFilterPersisted(col) ? "=" : "~=~");
130
+ const $existing = CT.filterFormField(formEl, col.name);
131
+ if (col.hidden || filter.type === "hidden" || !$existing.length) {
132
+ CT.ensureFilterField(formEl, col.name, value, operator);
133
+ return;
134
+ }
135
+ if (!$existing.val()) {
136
+ $existing.val(String(value));
137
+ $existing.attr("data-operator", operator);
138
+ }
139
+ });
140
+ };
141
+
142
+ /**
143
+ * Re-apply persisted defaults on reset; optionally re-submit when URL lacks them.
144
+ * @param {HTMLFormElement|JQuery} filterFormEl
145
+ * @param {Object} options
146
+ * @param {Object} [collection] KViews collection
147
+ */
148
+ CT.setupDefaultFilters = function (filterFormEl, options, collection) {
149
+ const form = $(filterFormEl)[0];
150
+ if (!form || !options || !options.features || !options.features.filtering) {
151
+ return;
152
+ }
153
+ const columns = options.columns || [];
154
+ CT.applyColumnDefaultFilters(form, columns);
155
+
156
+ if (columns.some(CT.columnFilterPersisted)) {
157
+ let resetting = false;
158
+ $(form)
159
+ .off("reset.kgridDefaultFilters")
160
+ .on("reset.kgridDefaultFilters", function (e) {
161
+ if (resetting) {
162
+ return;
163
+ }
164
+ e.preventDefault();
165
+ CT.cancelFilterDebounces(form);
166
+ resetting = true;
167
+ try {
168
+ form.reset();
169
+ CT.applyColumnDefaultFilters(form, columns);
170
+ if (
171
+ collection &&
172
+ collection.filtering &&
173
+ typeof collection.filtering.handleSubmit === "function"
174
+ ) {
175
+ collection.filtering.handleSubmit(form);
176
+ } else {
177
+ $(form).trigger("submit");
178
+ }
179
+ } finally {
180
+ resetting = false;
181
+ }
182
+ });
183
+ }
184
+
185
+ if (!collection || !collection.filtering) {
186
+ return;
187
+ }
188
+ const persisted = columns.filter(function (col) {
189
+ return (
190
+ col.name &&
191
+ col.filter &&
192
+ col.filter.default != null &&
193
+ col.filter.default !== "" &&
194
+ CT.columnFilterPersisted(col)
195
+ );
196
+ });
197
+ if (!persisted.length) {
198
+ return;
199
+ }
200
+ const urlFilter = String(
201
+ (collection.url &&
202
+ collection.url.parameters &&
203
+ collection.url.parameters.filter) ||
204
+ ""
205
+ );
206
+ const missing = persisted.some(function (col) {
207
+ return urlFilter.indexOf(col.name + "=") === -1;
208
+ });
209
+ if (missing) {
210
+ collection.filtering.handleSubmit(form);
211
+ }
212
+ };
213
+
214
+ /**
215
+ * Setup filtering row.
216
+ * Filter inputs live in <th> cells; they cannot sit inside one <form> in a <tr>.
217
+ * Each control uses the HTML form="" attribute pointing at a hidden <form id="…"> (see setupFilterHeader).
218
+ * @returns {jQuery|null} hidden filter form element (for FilterForm / KViews)
219
+ */
220
+ CT.setupFilterHeader = function (table, options) {
221
+ if (!options.features || !options.features.filtering) {
222
+ return null;
223
+ }
224
+ const theadFilters = table.find(".thead-filters");
225
+ theadFilters.empty();
226
+
227
+ const columns = [...options.columns];
228
+ const filtersRow = $("<tr>");
229
+ filtersRow.appendTo(theadFilters);
230
+ const filterFormId = "filter_form_" + CT.uuid();
231
+ const filterForm = $("<form>")
232
+ .attr("id", filterFormId)
233
+ .attr("hidden", "hidden")
234
+ .attr("aria-hidden", "true")
235
+ .addClass("table-filter-form")
236
+ .insertBefore(table);
237
+
238
+ columns.forEach((col) => {
239
+ const filter = col.filter || {};
240
+ const skipVisible = col.hidden || filter.type === "hidden";
241
+
242
+ if (skipVisible) {
243
+ if (col.features && col.features.filter === false) {
244
+ return;
245
+ }
246
+ if (!col.name) {
247
+ return;
248
+ }
249
+ const defVal = CT.filterDefaultValue(filter.default);
250
+ if (defVal != null && defVal !== "") {
251
+ CT.ensureFilterField(
252
+ filterForm[0],
253
+ col.name,
254
+ defVal,
255
+ filter.operator || "="
256
+ );
257
+ } else if (CT.columnFilterPersisted(col)) {
258
+ CT.ensureFilterField(filterForm[0], col.name, "", filter.operator || "=");
259
+ }
260
+ return;
261
+ }
262
+
263
+ let filterCell = $("<th>").appendTo(filtersRow).attr("data-label", col.label);
264
+ CT.applyColumnCellMeta(filterCell, col);
265
+
266
+ if (col.features.filter === false) {
267
+ return;
268
+ }
269
+ if (!col.name) {
270
+ throw new Error(
271
+ "Column must have a name when column.features.filter is true: \n" +
272
+ JSON.stringify(col, null, 2)
273
+ );
274
+ }
275
+
276
+ let input;
277
+ let pluggableResult = null;
278
+ const pluggable = CT.createFieldInput({ mode: "filter", col, config: filter });
279
+ if (pluggable) {
280
+ pluggableResult = pluggable;
281
+ input = pluggable.$input;
282
+ input.appendTo(filterCell);
283
+ CT.mountField({ mode: "filter", $input: input, col, config: filter });
284
+ } else {
285
+ switch (filter.type) {
286
+ case "select":
287
+ if (!filter.options) {
288
+ throw new Error(
289
+ "Column must have a filter.options array when column.filter.type is select: \n" +
290
+ JSON.stringify(col, null, 2)
291
+ );
292
+ }
293
+ input = $("<select>").addClass("form-select form-select-sm");
294
+ if (Array.isArray(filter.options)) {
295
+ filter.options.forEach((opt) => {
296
+ if (!opt.label || typeof opt.value !== "string") {
297
+ throw new Error(
298
+ "Column must have an filter.options object with label and value when column.filter.type is select: \n" +
299
+ JSON.stringify(col, null, 2)
300
+ );
301
+ }
302
+ $("<option>")
303
+ .text(opt.label)
304
+ .attr("value", opt.value)
305
+ .appendTo(input);
306
+ });
307
+ } else {
308
+ throw new Error(
309
+ "Column must have a filter.options array when column.filter.type is select: \n" +
310
+ JSON.stringify(col, null, 2)
311
+ );
312
+ }
313
+ input.appendTo(filterCell);
314
+ break;
315
+ default:
316
+ if (!CT.isValidFilterType(filter.type)) {
317
+ throw new Error("Unknown filter type: " + filter.type);
318
+ }
319
+ input = $(
320
+ `<input autocomplete='off' type='${filter.type}' class='form-control form-control-sm'/>`
321
+ );
322
+ input.appendTo(filterCell);
323
+ }
324
+ }
325
+
326
+ input.attr("data-operator", filter.operator);
327
+ input.attr("form", filterFormId);
328
+ input.attr("name", col.name);
329
+
330
+ const defVal = CT.filterDefaultValue(filter.default);
331
+ if (defVal != null && defVal !== "" && !input.val()) {
332
+ input.val(String(defVal));
333
+ input.attr("data-default", String(defVal));
334
+ if (input[0]) {
335
+ input[0].defaultValue = String(defVal);
336
+ }
337
+ }
338
+
339
+ const submitFilterForm = function () {
340
+ const form = this.form;
341
+ if (form) {
342
+ $(form).trigger("submit");
343
+ }
344
+ };
345
+ CT.bindFilterInputEvents({
346
+ type: filter.type,
347
+ $input: input,
348
+ onSubmit: submitFilterForm,
349
+ createResult: pluggableResult,
350
+ filterConfig: filter,
351
+ });
352
+ });
353
+
354
+ if (CT.hasActionColumn(options)) {
355
+ $("<th>")
356
+ .addClass("kgrid-row-actions")
357
+ .attr("data-label", "Actions")
358
+ .appendTo(filtersRow);
359
+ }
360
+
361
+ return filterForm;
362
+ };
363
+
364
+ CT.FilterForm = function (form) {
365
+ this.form = $(form)[0];
366
+ this.filter = (name, value, operator = "~=~") => {
367
+ if (!this.form) return this;
368
+ let $field = CT.filterFormField(this.form, name);
369
+ if (!$field.length) {
370
+ CT.ensureFilterField(this.form, name, value, operator);
371
+ $field = CT.filterFormField(this.form, name);
372
+ }
373
+ if (!$field.length) return this;
374
+ CT.flushFilterSubmit($field);
375
+ $field.val(value);
376
+ const oldOperator = $field.attr("data-operator");
377
+ $field.attr("data-operator", operator);
378
+ $(this.form).trigger("submit");
379
+ $field.attr("data-operator", oldOperator);
380
+ return this;
381
+ };
382
+ this.ensure = (name, value, operator = "=") => {
383
+ CT.ensureFilterField(this.form, name, value, operator);
384
+ return this;
385
+ };
386
+ this.reset = () => {
387
+ if (this.form) {
388
+ CT.cancelFilterDebounces(this.form);
389
+ this.form.reset();
390
+ }
391
+ return this;
392
+ };
393
+ };
394
+ })(window.KGrid);
package/src/init.js ADDED
@@ -0,0 +1,199 @@
1
+ (function (CT) {
2
+ /**
3
+ * Initialize a KGrid table inside a host element (DOM node or jQuery).
4
+ * The host may be an empty element; KGrid builds the table DOM when none is present.
5
+ *
6
+ * @param {Element|JQuery} host
7
+ * @param {Object} opts table configuration
8
+ * @returns {Promise<KGridTable>} API: instance, filterForm, setInteraction, …
9
+ */
10
+ CT.init = async function (host, opts) {
11
+ const $host = CT.resolveHostElement(host);
12
+ const options = { ...CT.protoOptions, ...opts };
13
+ const table = CT.mountTableShell($host, options);
14
+ CT.log("table config options", options);
15
+
16
+ const initialInteraction = CT.resolveDefaultInteraction(options);
17
+ CT.applyInteraction($host, initialInteraction);
18
+
19
+ const api = {
20
+ $host,
21
+ instance: null,
22
+ filterForm: null,
23
+ find(sel) {
24
+ return $host.find(sel);
25
+ },
26
+ setInteraction(mode, overrides) {
27
+ CT.applyInteraction($host, mode, overrides);
28
+ return api;
29
+ },
30
+ getInteraction() {
31
+ const mode = CT.getTableInteractionHost($host).attr("data-interaction");
32
+ return mode === "edit" ? "edit" : "view";
33
+ },
34
+ /** @deprecated prefer setInteraction('edit'|'view') */
35
+ setEditMode(editMode) {
36
+ if (typeof editMode !== "boolean") {
37
+ throw new TypeError(
38
+ "setEditMode(editMode) expects a boolean (true = edit, false = view)"
39
+ );
40
+ }
41
+ return api.setInteraction(editMode ? "edit" : "view");
42
+ },
43
+ /**
44
+ * @deprecated prefer setInteraction('edit'|'view')
45
+ * Boolean: true = edit, false = view. No arg / Event: toggle.
46
+ */
47
+ toggleEditMode(editMode) {
48
+ if (
49
+ editMode != null &&
50
+ typeof editMode === "object" &&
51
+ typeof editMode.preventDefault === "function"
52
+ ) {
53
+ editMode = undefined;
54
+ }
55
+ if (typeof editMode === "boolean") {
56
+ return api.setInteraction(editMode ? "edit" : "view");
57
+ }
58
+ return api.setInteraction(api.getInteraction() === "edit" ? "view" : "edit");
59
+ },
60
+ };
61
+
62
+ options.columns = options.columns.map((col) => CT.normalizeColumnConfig(col));
63
+
64
+ const handlers = options.handlers ?? {};
65
+ delete options.handlers;
66
+ options.columns.forEach((col) => {
67
+ ["insert", "update", "display"].forEach((mode) => {
68
+ const events = col[mode].events;
69
+ if (!events || !Array.isArray(events)) {
70
+ throw new Error("Column " + col.name + " events are not an array");
71
+ }
72
+ events.forEach((event) => {
73
+ if (typeof event.callback === "string") {
74
+ const fn =
75
+ handlers[event.callback] ||
76
+ (options.functions && options.functions[event.callback]);
77
+ if (!fn || typeof fn !== "function") {
78
+ throw new Error(
79
+ "Event callback function " +
80
+ event.callback +
81
+ " not found for column " +
82
+ col.name +
83
+ " or is not a function"
84
+ );
85
+ }
86
+ event.callback = fn;
87
+ } else if (typeof event.callback !== "function") {
88
+ throw new Error(
89
+ "Event callback must be a function for column " + col.name
90
+ );
91
+ }
92
+ });
93
+ });
94
+ const display = col.display;
95
+ if (display && display.events && Array.isArray(display.events)) {
96
+ display.events.forEach((event) => {
97
+ if (typeof event.callback === "string") {
98
+ const fn =
99
+ handlers[event.callback] ||
100
+ (options.functions && options.functions[event.callback]);
101
+ if (fn && typeof fn === "function") {
102
+ event.callback = fn;
103
+ }
104
+ }
105
+ });
106
+ }
107
+ });
108
+
109
+ const colMap = new Map();
110
+ options.columns.forEach((col) => {
111
+ colMap.set(col.name, col);
112
+ });
113
+
114
+ const labelsRow = CT.setupLabelsHeader(table.find(".thead-labels"), options);
115
+
116
+ const hasActionColumn = CT.hasActionColumn(options);
117
+ const visibleColumnsCount = labelsRow.find("th").length;
118
+ const dataColumnCount = visibleColumnsCount - (hasActionColumn ? 1 : 0);
119
+ CT.syncActionColumnColgroup(table, dataColumnCount, hasActionColumn);
120
+
121
+ const filterForm = options.filterForm ?? CT.setupFilterHeader(table, options);
122
+
123
+ let pagingFooter;
124
+ if (options.features && options.features.paging) {
125
+ pagingFooter = CT.setupPagingFooter(
126
+ table.find(".paging-footer"),
127
+ options,
128
+ visibleColumnsCount
129
+ );
130
+ } else {
131
+ pagingFooter = null;
132
+ table.find(".paging-footer").remove();
133
+ }
134
+
135
+ const noDataTbody = CT.setupNoDataTbody(
136
+ table.find(".no-data-tbody"),
137
+ options,
138
+ visibleColumnsCount
139
+ );
140
+
141
+ if (options.features && options.features.create) {
142
+ CT.setupNewRecordForm(table, options, api);
143
+ }
144
+
145
+ api.filterForm = new CT.FilterForm(filterForm);
146
+ const dataBody = CT.setupDataBody(
147
+ table.find(".main-tbody"),
148
+ options,
149
+ labelsRow,
150
+ filterForm,
151
+ pagingFooter,
152
+ noDataTbody
153
+ );
154
+
155
+ const KViewOptions = {
156
+ dontload: true,
157
+ setAttrAsId: options.setAttrAsId ?? false,
158
+ itemListeners: {
159
+ afterrender: (item) =>
160
+ CT.setupEvents(item, api.find("table"), options, colMap),
161
+ },
162
+ };
163
+
164
+ const KViews = CT.getKViews(options.kviews);
165
+ if (!KViews) {
166
+ throw new Error(CT.KVIEWS_MISSING_MSG);
167
+ }
168
+ api.instance = await KViews.createCollectionInstance(dataBody, KViewOptions);
169
+
170
+ if (options.url) {
171
+ api.instance.setUrl(options.url);
172
+ if (options.deleteUrl) {
173
+ CT.log("set deleteUrl", options.deleteUrl);
174
+ api.instance.setUrl(options.deleteUrl, "delete");
175
+ }
176
+ if (options.updateUrl) {
177
+ CT.log("set updateUrl", options.updateUrl);
178
+ api.instance.setUrl(options.updateUrl, "update");
179
+ }
180
+ if (options.insertUrl) {
181
+ api.instance.setUrl(options.insertUrl, "insert");
182
+ }
183
+ try {
184
+ await api.instance.loadFromRemote();
185
+ } catch (error) {
186
+ CT.onError(error);
187
+ }
188
+ } else if (options.data && options.data.constructor === Array) {
189
+ const dataCopy = options.data.map((item) => ({ attributes: item }));
190
+ api.instance.loadFromData(dataCopy);
191
+ } else {
192
+ throw new Error("Invalid data: missing datasource url or data for table");
193
+ }
194
+
195
+ CT.setupDefaultFilters(filterForm, options, api.instance);
196
+
197
+ return api;
198
+ };
199
+ })(window.KGrid);