net-tools / js-grid-editor
Javascript API implementing a grid editor
Installs: 52
Dependents: 1
Suggesters: 0
Security: 0
Stars: 0
Watchers: 1
Forks: 0
Open Issues: 0
Language:JavaScript
Requires
- net-tools/js-core: ^1.0.0
- net-tools/ui: ^1.0.0
README
Composer library with a Javascript grid editor
The library defines a Javascript nettools.jsGridEditor
class which makes it possible to edit data stored as rows and columns.
Setup instructions
To install net-tools/js-grid-editor package, just require it through composer : require net-tools/js-grid-editor:^1.0.0
.
How to use ?
The nettools.jsGridEditor
class constructor expects the following parameters :
- the
HTMLElement
node where the editor must be rendered (usually a DIV) - an object litteral with options :
columns
: an array of object litterals defining columns (see below)data
: an array of object litterals containing data (see below)editable
: a boolean value ; if set to false, the grid data can't be editeddisableDblClick
: a boolean value ; if set to true, a double-click can't switch the row to edit modedefaultValues
: an object litteral containing default values for new linesdialog
: an object inheriting fromnettools.jsGridEditor.Dialog
withalert
andconfirm
methods ; by default, Javasriptalert
andconfirm
functions are usedrowToStringColumns
: an event to help convert column values for a given row to a string ; if a numeric (starting at 0) or 'first' is given, the conversion is a key=value string for the corresponding column. If 'all' is given, the conversion returns all key values separated with commasonRowValidate
: an event called to validate row data before exiting edit mode (rowData may be updated during call) ; return a resolved Promise to accept changes, or a rejected Promise with error message to reject updatesonRowToString
: an event called to get a string value for a row (the default code for this event userowToStringColumns
value to generate the string)onRowChange
: an event called to notify the client that a row content has changed ; the client code must return a resolved Promise if he acknowledges the update, or a rejected Promise otherwiseonRowDelete
: an event called to notify the client that a row has been deleted ; the client code must acknowledge the deletion and return a resolved Promise when done, or a rejected Promise if an error occuredonRowInsert
: an event called to notify the client that a row has been inserted ; the client code must return a Promise when done, or a rejected Promise if an error occuredonCellHtml
: an event called for 'html' columns to set some rich GUI inside TD nodeonGetCellHtmlValue
: an event called for 'html' columns in edit-mode to get edited value to store in dataset when committing row edits
The columns
object litteral array defines all columns ; the allowed parameters for a column are (also, see sample below) :
id
: the column ID as a string ; will be used indata
parameter as property nametitle
: the title that will appear in table header for this columnsubTitle
: the subtitle in table header for the columntype
: defines the type for the column (string, int, float, bool, list or html)required
: bool value to enforce column mandatory statushidden
: a bool value to hide the columnformat
: regular expression to valide column datareadonly
: the column can't be editedreadonlyEdit
: the column can't be edited except when creating a new linedatalist
: iftype
property is list, defines an array of string values accepted as valuesvalidator
: a custom function to validate column value (return true if value is accepted or false if value is rejected)
The data
array of object litterals contains grid data : one object litteral per row, each object property is a column value. See sample below.
var grid = new nettools.jsGridEditor(document.getElementById('grid'), { // defining columns columns : [ { id : 'key', subTitle:'string(2)', format:/^[A-Z][A-Z0-9]$/, required : true, validator:function(v){ return v!='RU'; } }, { id : 'country', title : 'Country name', subTitle:'string', readonly : true }, { id : 'region', title : 'World area', subTitle:'list', required : true, type:'list', datalist:['Europe', 'America', 'North-America', 'South-America', 'Asia', 'Africa'] }, { id : 'order', type : 'int', subTitle:'int' }, { id : 'english', title : 'Speak English ?', subTitle:'bool(0/1)', required : true, type : 'bool' } ], // data to edit data : [ { key : 'FR', country : 'France', region : 'Europe', order : 1, english : 0 }, { key : 'US', country : 'USA', region : 'North-America', order : 2, english : 1 }, { key : 'UK', country : 'United Kingdom', region : 'Europe', order : 3, english : 1 } ], // grid is editable editable : true, // a row is converted to a string by return key=value for column 1 (second column) rowToStringColumns : 1, // default values for new lines defaultValues : { region : 'Asia', english : 1 }, // output in console values to validate onRowValidate : function(row, values) { console.log('Values to validate at row ' + row); console.log(values); return true; }, // accepting updates in rows only for even one onRowChange : function(row, values) { console.log('Row changed at offset ' + row); console.log(values); if ( row % 2 == 0 ) return Promise.resolve(row); else return Promise.reject('Row commit failed at row ' + row); }, // processing deletion client-side ; if the user acknowledges deletion, the row is removed from dataset onRowDelete : function(row, values) { return new Promise(function(resolve, reject){ if ( confirm('Confirm deletion has been processed client-side ?') ) resolve(row); else reject('Deletion at row ' + row + ' denied'); }); }, // procession new line ; if the user acknowledges insert, the row is inserted in the dataset onRowInsert : function(row, values) { return new Promise(function(resolve, reject){ if ( confirm('Confirm insert has been processed client-side ?') ) resolve(row); else reject('Insert at row ' + row + ' denied'); }); } } );
There are several object methods that can be called :
setData
: ifdata
options parameter is not set during constructor call, the data can be assigned to grid editor later by callingsetData
method with an array of object litterals.isInserting
: returns true if the editor is currently inserting a new lineinsertRow
: switch the editor to insert mode, filling the empty new line with default values providededitRow
: edit the row at offset in parameterdeleteRow
: delete the row at offset in parameter ; the user is asked to confirm row deletion ; theonRowDelete
event is called to notify client-side
Samples
There are one sample inside /samples
subdirectory :
- editor.html