xfields

⚠️ Archived / no longer maintained. These fields now live on, actively maintained, as part of jsxgrid — a maintained fork of jsGrid with this whole field set merged in as a core part of the package (and no longer dependent on the native jsGrid field types). If you're starting something new, or want fixes/updates going forward, use jsxgrid instead:

npm install jsxgrid

This repo is kept around for history; no further changes will land here.

More custom fields for jsGrid!

Installation

npm install xfields

Peer dependencies: jquery (^3.0.0) and jsgrid (^1.5.3). select2 is optional (only needed if you use Xselect's select2 option), jsoneditor is optional (only needed for Xjsoneditor).

Usage

Each field ships as its own file and also as a single bundle (dist/xfields.js / dist/xfields.min.js). Every file works three ways:

• Plain <script> tag (no bundler) — just load jQuery and jsGrid first, then the field files. This is the primary/expected way to use the library:

<script src="jquery.js"></script>
<script src="jsgrid.js"></script>

<script src="node_modules/xfields/dist/fields/lib/jsgrid.popup.basic.min.js"></script>
<script src="node_modules/xfields/dist/fields/jsgrid.field.Xselect.min.js"></script>
<!-- ...other fields as needed -->

• AMD (define(["jsgrid", "jquery"], ...)) and CommonJS (require("xfields/dist/fields/jsgrid.field.Xselect.min.js"), which resolves require("jsgrid")/require("jquery") itself) are also supported if you load individual field files through a bundler. Registration is a side effect (jsGrid.fields.X = ...); the modules don't export anything meaningful themselves.

See a full working example with every field wired up: example/index.html.

Fields

The defaultSelected convention

Every filterable field below (all except XRowSelectField, which doesn't filter) supports a defaultSelected option: a value used to preset the filter control the first time its filter row is rendered. After that first render it's reset to null, so it won't keep overriding whatever the user searches for afterwards. It's null (a no-op) by default on every field. The expected value shape differs per field — see each field's table below.

Xcheckbox

Drop-in replacement for the standard checkbox field. Returns 1/0 instead of true/false, which avoids a lot of backend type-coercion headaches (especially with databases).

Option	Default	Description
defaultSelected	null	0/1/true/false to preset the filter checkbox as unchecked/checked; leave null for the default indeterminate ("any") state.

XimgField

Text field that previews its value as an <img>. Options:

Option	Default	Description
fm_callback	null	function(control) — if set, insert/edit renders a button instead of a text input, and clicking it calls this callback with the jQuery-wrapped control so you can wire up your own file manager/picker.
editButtonText	'Open FM'	Text for that button.
defaultSelected	null	A string to preset the filter input with.

Xselect

Drop-in replacement for the standard select field, plus:

Option	Default	Description
pseudoElement	null	An extra item unshifted to the start of the filter dropdown (e.g. an "any" option). Shape must match your items (object for object-items, or a {[textField]:'', [valueField]:null}-like item for array items).
select2	null	Config object passed to select2 on the filter control (width is always forced to 100%). Applied via setTimeout(0) so the control is attached to the DOM first.
defaultSelected	null	A value to preselect in the filter, matched against items by valueField (or by array index / object key if there's no valueField).

Xtextarea

Long text is collapsed and expandable on click.

Option	Default	Description
maxShowSymbols	50	Values longer than this are truncated with ...; click the cell to expand.
defaultSelected	null	A string to preset the filter input with.

Xjsoneditor

Edits/views a JSON value through jsoneditor (required peer dependency — must be loaded on the page, e.g. via CDN, or Xjsoneditor will throw when you try to open the editor).

Option	Default	Description
templates	[]	Forwarded to jsoneditor's templates option.
editText	'Editor'	Text of the button shown in view mode.
closeText	'Save'	Close-button text used when opening the editor for insert/edit.
defaultSelected	null	A string to preset the (text-based) filter input with — the filter matches against the raw JSON string, not parsed values.

XRowSelectField

A checkbox-per-row selection column with an optional header action button. filtering is hardcoded to false, so there's no filter row and no defaultSelected support.

Option	Default	Description
buttonText	''	Header button text. Header button is hidden entirely if left empty.
selectedItemsAction	no-op	function(selectedItems) — called when the header button is clicked. Override this to implement your bulk action.

Field instance also exposes:

• selectItem(item) / unselectItem(item) — used internally by the row checkboxes.
• unselectAll() — clears selectedItems and unchecks every row checkbox for this field. Call it at the end of your selectedItemsAction if you want selection to reset after the action runs.

XDateTimeField

Date/datetime field backed by a native <input type="datetime-local"> (or whatever datePickerType you set).

Option	Default	Description
datePickerType	'datetime-local'	Any native <input> date/time type (date, datetime-local, time, ...).
dateRange	false	When true, the filter renders two date inputs (from/to) instead of one, and filterValue() returns {from, to}.
options	built-in Intl.DateTimeFormat options	Passed to toLocaleDateString() when rendering the item view. Empty values render as an empty string.
defaultSelected	null	A value (matching datePickerType's input format) to preset the filter with. When dateRange is true, pass {from, to} instead.

popup.basic

src/lib/jsgrid.popup.basic.js registers a minimal, jQuery-only modal used by Xjsoneditor (and available for your own use) as jsGrid.popup / jsGrid.popupBasic:

jsGrid.popup(formContentOrElement, {
    heading: "Title",     // optional
    closeText: "Close",   // optional
    styles: "...",        // optional, overrides the injected default CSS (injected once per page)
    onClose: function (popup) { /* ... */ }
});

You can swap in your own modal implementation entirely by overwriting jsGrid.popup before this file loads (or instead of loading it).

jsGridSummaryPlugin

src/lib/jsGridSummaryPlugin.js patches $.fn.jsGrid so any field can define a summary(data) function; the results are rendered as a <tfoot> row (.jsgrid-summary-footer) after every grid refresh:

{
    name: "Age", type: "number",
    summary: function (data) {
        var total = data.reduce(function (s, i) { return s + (parseFloat(i.Age) || 0); }, 0);
        return "Sum: " + total; // rendered via .html(), so markup is allowed
    }
}

Load this file after jsGrid but before $(...).jsGrid(...) is called for the grid you want the footer on.

Development

npm install
npm run lint    # ESLint over src/
npm run build   # rebuilds dist/ (grunt: clean, concat, uglify)

dist/ is committed to the repo (consumers pull it directly via a plain <script src="node_modules/xfields/dist/...">), so run npm run build and commit the result whenever you change anything under src/.