Grid Cells Editing
(requires jqxgrid.edit.js)
jqxGrid Cell Editing feature much resembles the data entering experience in an Excel Spreadsheet – once you select a grid cell, you can enter data when you start typing text. In order to
use the Cells Editing feature, you need to reference the jqxgrid.edit.js in your project and also to include the javascript files required by some of the editors. The Grid's 'editable' property
specifies whether the editing is enabled or not.
Mouse Edit Actions
- Single mouse click: Marks the clicked cell as selected and shows the editor. The editor’s value is equal to the cell’s value.
- Single mouse click on a selected cell: Marks the cell as selected and shows the editor.
- Double mouse click on a cell: Marks the cell as selected and shows the editor. The editor’s value is equal to the cell’s value..
Keyboard Edit Actions and Navigation
If the user starts typing text, the cell’s content is replaced with the text entered from the user.
- Left Arrow key is pressed - Selects the left cell, when the Grid is not in edit mode. Otherwise, the key stroke is handled by the editor.
- Right Arrow key is pressed - Selects the right cell, when the Grid is not in edit mode. Otherwise, the key stroke is handled by the editor.
- Up Arrow key is pressed - Selects the cell above, when the Grid is not in edit mode. Otherwise, the key stroke is handled by the editor.
- Down Arrow key is pressed - Selects the cell below, when the Grid is not in edit mode. Otherwise, the key stroke is handled by the editor.
- Page Up/Down is pressed - Navigate Up or Down with one page, when the Grid is not in edit mode. Otherwise, the key stroke is handled by the editor.
- Home/End is pressed - Navigate to the first or last row, when the Grid is not in edit mode. Otherwise, the key stroke is handled by the editor.
- Enter key is pressed - Shows the selected cell’s editor. If the cell is in edit mode, hides the cell’s editor and saves the new value. The editor’s value is equal to the cell’s value.
- Esc key is pressed - Hides the cell’s editor and cancels the changes.
- Tab key is pressed - Selects the right cell. If the Grid is in edit mode, saves the edit cell's value, closes its editor, selects the right cell and opens its editor.
- Shift+Tab keys are pressed - Selects the left cell. If the Grid is in edit mode, saves the edit cell's value, closes its editor, selects the left cell and opens its editor.
- F2 key is pressed - shows the selected cell's editor.
- Space key is pressed - Toggles the checkbox editor’s check state when the selected cell’s column is a checkbox column.
Programmatic Editing
The Grid have APIs for showing and hiding the cell editors.
The 'begincelledit' method allows you to put a specific cell into edit mode.
$("#jqxgrid").jqxGrid('begincelledit', 0, 'firstname');
The 'endcelledit' method ends the edit operation and confirms or cancels the changes.
The following code cancels the changes.
$("#jqxgrid").jqxGrid('endcelledit', 0, 'firstname', true);
The following code confirms the changes.
$("#jqxgrid").jqxGrid('endcelledit', 0, 'firstname', false);
To set a new value to a Grid cell, you can use the 'setcellvalue' method:
// the first parameter is the row's index.
// the second parameter is the column's datafield.
// the third parameter is the new cell's value.
$("#jqxgrid").jqxGrid('setcellvalue', 0, 'lastname', 'My Value');
To get the value of a Grid cell, you can use the 'getcellvalue' method:
// the first parameter is the row's index.
// the second parameter is the column's datafield.
var value = $("#jqxgrid").jqxGrid('getcellvalue', 0, 'lastname');
The 'cellbeginedit' and 'cellendedit' events are raised when the edit operation begins or ends.
$("#jqxgrid").on('cellbeginedit', function (event) {
var args = event.args;
var columnDataField = args.datafield;
var rowIndex = args.rowindex;
var cellValue = args.value;
});
$("#jqxgrid").on('cellendedit', function (event) {
var args = event.args;
var columnDataField = args.datafield;
var rowIndex = args.rowindex;
var cellValue = args.value;
var oldValue = args.oldvalue;
});
Editor Types
jqxGrid supports the following types of editors:
- TextBox
- CheckBox(uses the jqxCheckBox widget)
- NumberInput(uses the jqxNumberInput widget and edits currency, percentange and any type of numeric information)
- DateTimeInput(uses the jqxDateTimeInput widget and edits date and time values)
- DropDownList(uses the jqxDropDownList widget and selects a single value from a list of values)
To specify the column's editor, you should set the column's 'columntype' property to 'textbox', 'dropdownlist', 'numberinput', 'checkbox' or 'datetimeinput'.
To disable the editing of a specific grid column, you can set the column's editable property to false. The 'initeditor' function is called when the editor's widget
is initialized. It allows you to use the properties of the widget and make it best fit your application's scenario.
$("#jqxgrid").jqxGrid(
{
source: dataAdapter,
editable: true,
theme: theme,
selectionmode: 'singlecell',
columns: [
{ text: 'First Name', columntype: 'textbox', datafield: 'firstname', width: 90 },
{ text: 'Last Name', datafield: 'lastname', columntype: 'textbox', width: 90 },
{ text: 'Product', columntype: 'dropdownlist', datafield: 'productname', width: 180 },
{ text: 'Available', datafield: 'available', columntype: 'checkbox', width: 65 },
{ text: 'Ship Date', datafield: 'date', columntype: 'datetimeinput', width: 90, cellsalign: 'right', cellsformat: 'd'},
{ text: 'Quantity', datafield: 'quantity', width: 70, cellsalign: 'right', columntype: 'numberinput',
initeditor: function (row, cellvalue, editor) {
editor.jqxNumberInput({ decimalDigits: 0 });
}
},
{ text: 'Price', datafield: 'price', width: 65, cellsalign: 'right', cellsformat: 'c2', columntype: 'numberinput',
initeditor: function (row, cellvalue, editor) {
editor.jqxNumberInput({ digits: 3 });
}
}
]
});
Please note that in order to use the 'dropdownlist', 'numberinput', 'checkbox' or 'datetimeinput' editors you need to include the necessary javascript files.
Validation
The Grid will display a validation popup message when the new cell’s value is not valid. The developers are able to set a custom validation logic and error messages for each grid column. The Grid will stay in edit mode until a correct value is entered or the user presses the "Esc" key.
In following code, the "Ship Date", "Quantity" and "Price" columns define custom validation functions. Each function has 2 parameters - the edit cell and its value. Depending
on your logic, you can validate the value and return true if the value is correct or false, if the value is not correct. You can also return an object with 2 members - result and message.
The message member represents the message that your users will see, if the validation fails.
$("#jqxgrid").jqxGrid(
{
width: 670,
source: dataAdapter,
editable: true,
theme: theme,
selectionmode: 'singlecell',
columns: [
{ text: 'First Name', columntype: 'textbox', datafield: 'firstname', width: 90 },
{ text: 'Last Name', datafield: 'lastname', columntype: 'textbox', width: 90 },
{ text: 'Product', columntype: 'dropdownlist', datafield: 'productname', width: 180 },
{ text: 'Available', datafield: 'available', columntype: 'checkbox', width: 65 },
{ text: 'Ship Date', datafield: 'date', columntype: 'datetimeinput', width: 90, cellsalign: 'right', cellsformat: 'd',
validation: function (cell, value) {
var year = value.getFullYear();
if (year>= 2013) {
return { result: false, message: "Ship Date should be before 1/1/2013" };
}
return true;
}
},
{ text: 'Quantity', datafield: 'quantity', width: 70, cellsalign: 'right', columntype: 'numberinput',
validation: function (cell, value) {
if (value < 0 || value> 100) {
return { result: false, message: "Quantity should be in the 0-100 interval" };
}
return true;
},
initeditor: function (row, cellvalue, editor) {
editor.jqxNumberInput({ decimalDigits: 0 });
}
},
{ text: 'Price', datafield: 'price', width: 65, cellsalign: 'right', cellsformat: 'c2', columntype: 'numberinput',
validation: function (cell, value) {
if (value < 0 || value> 15) {
return { result: false, message: "Price should be in the 0-15 interval" };
}
return true;
},
initeditor: function (row, cellvalue, editor) {
editor.jqxNumberInput({ digits: 3 });
}
}
]
});
For Server-Side cells editing, see the
Server-side processing with PHP and MySQL help topic.