Form Editing

jqGrid supports creating a form “on the fly” to view, add, edit, delete, or search grid data. A screenshot of an “Add Record” form is shown below:

The methods listed in the table below are included in the navGrid (navigator method).

To use this module, you should mark the Common, Form Editing and optional jqModal and jqDnR plugins when you download the grid. For more information refer to Download.

Note For Developers - this is the grid.common.js, grid.formedit.js, jqModal.js and jqDnR.js in the src directory.

Methods used in form editing are a sub-set of those of the parent grid, and described below.
All the properties and events of the methods are not a part of jqGrid, but a part of options passed as parameters to the method.

For more information about this method refer to Single Searching and Advanced Searching

This method creates a form via modal dialog for editing a particular row from the grid.
This method uses Common Editing Properties from colModel and editurl option from jqGrid.

Calling convention:

jQuery("#grid_id").editGridRow( rowid, properties );

or when we use the new API

jQuery("#grid_id").jqGrid('editGridRow', rowid, properties );

Where

• grid_id: the id of the parent grid
• rowid: the id of the row to edit
• properties: an array of name: value pairs, including any of the following properties or events.

The method uses the following properties from language file:

$.jgrid = {
...
	edit : {
		addCaption: "Add Record",
		editCaption: "Edit Record",
		bSubmit: "Submit",
		bCancel: "Cancel",
		bClose: "Close",
		saveData: "Data has been changed! Save changes?",
		bYes : "Yes",
		bNo : "No",
		bExit : "Cancel",
...
	},
...
}

These options can be overwritten when passed as options to the method. When passed to the method we should use by example bSubmit : “Submit” and not $.jgrid.edit.bSubmit : “Submit”

When called the constructed form can look like this

When the form is constructed we set the following rules:

• Hidden fields are included in the form with the display:none property of the table row
• The id of the editable element is constructed from the name of the colModel array - propery - name
• The name of the editable element is constructed from the name of the colModel array - propery - name
• For ease in manipulating the elements in an edit form, every table row in the form that holds the data for the edit has a id which is a combination of “tr_” + name (from colmodel). Example:

<form ....> 
  <table> 
    <tr id='tr_myfield'>  
      <td> Caption</td> <td>edited element named, in colModel, as "myfield"</td> 
    </tr> ... 
  </table> 
</form>

This allow us to easily show or hide some table rows depending on conditions using beforeShowForm event

When we are in editing mode the data that is posted to the server is object {} that contain:

• the name:value pair where the name is the name of the input element represented in the form (this is for all input elements)
• additionally we add a pair id:rowid where the rowid is the id of the edited row
• additionally we add a pair oper:edit to indicate the edit mode
• if the editData object is not empty we extend this data with the posted data
• if the returned object from onclickSubmit event is not empty we extend the posted data with this object

The editGridRow method is also used to add data to the server, by passing “new” as the rowid.
This method uses Common Editing Properties from colModel and editurl option from jqGrid.

Calling convention:

jQuery("#grid_id").editGridRow( "new", properties );

or with the new API

jQuery("#grid_id").jqGrid('editGridRow', "new", properties );

Where

• grid_id: the id of the parent grid
• properties: an array of name: value pairs, including any of the following properties or events.

The method uses the following properties from language file:

$.jgrid = {
...
	edit : {
		addCaption: "Add Record",
		editCaption: "Edit Record",
		bSubmit: "Submit",
		bCancel: "Cancel",
		bClose: "Close",
		saveData: "Data has been changed! Save changes?",
		bYes : "Yes",
		bNo : "No",
		bExit : "Cancel",
...
	},
...
}

These options can be overwritten when passed as options to the method. When passed to the method we should use by example bSubmit : “Submit” and not $.jgrid.edit.bSubmit : “Submit”

The options are the same as those in editng row - See above.

When the form is constructed we set the following rules:

• Hidden fields are included in the form with the display:none property of the table row
• The id of the editable element is constructed from the name of the colModel array - propery - name
• The name of the editable element is constructed from the name of the colModel array - propery - name
• For ease in manipulating the elements in an edit form, every table row in the form that holds the data for the edit has a id which is a combination of “tr_” + name (from colmodel). Example:

<form ....> 
  <table> 
    <tr id='tr_myfield'>  
      <td> Caption</td> <td>edited element named, in colModel, as "myfield"</td> 
    </tr> ... 
  </table> 
</form>

This allow us to easily show or hide some table rows depending on conditions using beforeShowForm event

When we are in editing mode the data that is posted to the server is object {} that contain:

• the name:value pair where the name is the name of the input element represented in the form (this is for all input elements)
• additionally we add a pair id:_empty where the _empty indicates that new row is inserted
• additionally we add a pair oper:add to indicate the add mode
• if the editData object is not empty we extend this data with the posted data
• if the returned object from onclickSubmit event is not empty we extend the posted data with this object

This method is similar to the editGridRow method except that the fields are not editable and we do not have any events attached to the form.

Calling convention:

jQuery("#grid_id").viewGridRow( rowid, properties );

or when we use the new API

jQuery("#grid_id").jqGrid('viewGridRow', rowid, properties );

Where

• grid_id: the id of the parent grid
• rowid: the id of the row to edit
• properties: an array of name: value pairs, including any of the following properties or events.

The method uses the following properties from language file:

$.jgrid = {
...
	view : {
		caption: "View Record",
		bClose: "Close"
	},
...

When the form is constructed we set the following rules:

• No input elements are created
• Hidden fields are included in the form with the display:none property of the table row
• The id of the viewed element is constructed from “v_” + the name of the colModel array - propery - name
• For ease in manipulating the elements in an edit form, every table row in the form that holds the data for the edit has a id which is a combination of “trv_” + name (from colmodel). Example:

<form ....> 
  <table> 
    <tr id='trv_myfield'>  
      <td> Caption</td> <td id="v_myfield"><span>content of"myfield"</span></td> 
    </tr> ... 
  </table> 
</form>

With this method we can perform a delete operation at server side.
This method uses colModel and editurl parameters from jqGrid

Calling convention:

jQuery("#grid_id").delGridRow( row_id_s, options );

or when we use the new API

jQuery("#grid_id").jqGrid('delGridRow', row_id_s, options );

Where:

• grid_id: the id of the parent grid
• row_id_s: the id of the row(s) to delete; can be a single value or list of ids separated by comma
• options: an array of name: value pairs, including any of the following properties or events.

The method uses the following properties from language file:

$.jgrid = {
...
	del : {
		caption: "Delete",
		msg: "Delete selected record(s)?",
		bSubmit: "Delete",
		bCancel: "Cancel"
	},
...

These options can be overwritten when passed as options to the method. When passed to the method we should use by example bSubmit : “Delete” and not $.jgrid.del.bSubmit : “Delete”

When we are in delete mode the data that is posted to the server is object {} that contain:

• the pair id:rowids where the rowids can be a single value a value string separated with comma in case of multiple selection
• additionally we add a pair oper:del to indicate the delete mode
• if the delData object is not empty we extend this data with the posted data
• if the returned object from onclickSubmit event is not empty we extend the posted data with this object

This method does not have interaction with the user
Calling convention:

jQuery("#grid_id").GridToForm( rowid, formid );

or

jQuery("#grid_id").jqGrid('GridToForm', rowid, formid );

Where

• grid_id: the id of the parent grid
• rowid: the id of the row
• formid: is the jQuery object of form id, you can use formid[0].id to get form id.

When called this method read the grid data with the id = rowid and places the data from the grid to the given form. if the form element has a name which is equal of those from colModel the value is placed to the form.

This method does not have interaction with the user
Calling convention:

jQuery("#grid_id").FormToGrid( rowid, formid, mode, position );

or

jQuery("#grid_id").jqGrid('FormToGrid', rowid, formid, mode, position );

Where

• grid_id: the id of the parent grid
• rowid: the id of the row
• formid: is the jQuery object of form id, you can use formid[0].id to get form id.
• mode: determines the mode. Can be set or add. Default is set. If the mode is defined as set, the record in the grid is updated with the new values from the form. When the mode is defined as add the record is added to the grid.
• position: this parameter have sense only when the mode parameter is set to add. Can be first - the record is inserted as first row in the grid or last - the record is inserted as last row in the grid.

When called this method does the opposite of the GridToForm method - i.e. places the form data in the grid if the names matches.