Jqsuite Php Documentation

jqSuite php documentation

Editing Options

One of the key reasons for displaying data in a grid is to edit it, quickly and easily. jqGrid supports editing data in three ways:

cell editing: edit specific cells in a gird
inline editing: edit several cells in the same row
form editing: create a form to edit outside of the grid

By default when to colModel is created all fields are marked as editable, where the field is represented as input of type text.
If we want to disable the editing of some field we should just set the property editable to false:

$grid->setColProperty('somefield',array("editable"=>false));

after the colModel is created with setColModel method.

All editing modules uses a common properties in colModel in order to perform editing. Below is the list of these properties with detailed description:

editable
edittype
editoptions
editrules
formoptions (valid only in form editing)

The common syntax of using these options is:

<?php

....

$grid->setColModel(...);

$grid->setColProperty('somefield',array("editable"=>true, "edittype"=>"text", "editoptions"=>array(...), "editrules"=>array(...), "formoptions"=>array(...)));

...

$grid->renderGrid(...);

...

editable

The editable option is boolean and can have two values true or false. The option defines if this field is editable (or not). Default is true. To make a field non editable, set this to false: editable=>false.
We should mention that the hidden fields are not editable instead that they have been marked as editable. In in-line and cell editing modules you should show these fields (using showCol method) in order to edit it. In form editing module you should use editrules option (see below)

edittype

Edittype option defines the type of of the editable field. Possible values: 'text', 'textarea', 'select', 'checkbox', 'password', 'button', 'image', 'file' and 'custom'. The default value is 'text'.

text

When edittype is 'text', jqGrid constructs a input tag of type text:

In editoptions we can set all the possible attributes for this field. For example,

... "editoptions"=>array("size"=>10, "maxlength"=> 15).....

will cause jqGrid to construct the following input

In addition to the these settings, jqGrid adds the id and name attribute.

textarea

When edittype is 'textarea', jqGrid constructs a input tag of type textarea

In editoptions we can add additional attributes to this type. Typically, these govern the size of the box:

... "editoptions"=>array("rows"=>3, "cols"=> 20).....

To these attributes jqGrid adds id and name attributes .

checkbox

When edittype is 'checkbox', jqGrid constructs a input tag as follows:

editoptions is used to define the checked and unchecked values. The first value is checked. For example

..."editoptions"=>array("value"=>"Yes:No" )...

This will construct

defines a checkbox in which when the value is Yes the checkbox becomes checked, otherwise unchecked. This value is passed as parameter to the editurl.

If in the editoptions the value property is not set jqGrid search for the following values (false|0|no|off|undefined) in order to construct checkbox. If the cell content does not contain one of these values then the value attribute becomes the cell content and offval is set to off.
Example if the cell content is true, then
<input type="checkbox" value="true" offval="off" checked.../>
To these attributes jqGrid adds id and name attributes .

select

When edittype is 'select', jqGrid constructs a input tag as follows:

<select>
<option value='val1'> Value1 </option>
<option value='val2'> Value2 </option>
...
<option value='valn'> ValueN </option>
</select>

To construct this element we have two possible variants

Using the setSelect method
Setting editoptions dataUrl parameter

The method setSelect will be considered later (link)

The editoptions dataUrl parameter is valid only for element of edittype:select. The dataUrl parameter represent the url from where the html select element should be get.
When this option is set, the element will be filled with values from the ajax request. The data should be a valid html select element with the desired options - something like:

To this element, jqGrid adds the id and name attributes as above.
The corresponding script cam look like this:

...

$grid->setColProperty('somename',array('edittype'=>'select','editoptions'=>array('dataUrl'=>'some_url')));

...

Multiple selection of options in a select box is also possible. Also the size attribute can be added too

...

$grid->setColProperty('somename',array('edittype'=>'select','editoptions'=>array("multiple"=>true,"size"=>3,...)));

...

password

When edittype is 'password', jqGrid constructs a input tag of type text:

In editoptions we can set all the possible attributes for this field. For example,

... "editoptions"=>array("size"=>10, "maxlength"=> 8).....

will cause jqGrid to construct the following input

In addition to the these settings, jqGrid adds the id and name attribute.

button

When edittype is 'button', jqGrid constructs a input tag of type text:

In editoptions we can set all the possible attributes for this field. For example,

... "editoptions"=>array("value"=>"MyButton").....

will cause jqGrid to construct the following input

In addition to the these settings, jqGrid adds the id and name attribute.

image

When edittype is 'image', jqGrid constructs a input tag of type text:

In editoptions we can set all the possible attributes for this field. For example,

... "editoptions"=>array("src"=>"path_to_my_image").....

will cause jqGrid to construct the following input

In addition to the these settings, jqGrid adds the id and name attribute.

file

When edittype is 'file', jqGrid constructs a input tag of type text:

In editoptions we can set all the possible attributes for this field. For example,
... "editoptions"=>array("alt"=>"Alt text").....

will cause jqGrid to construct the following input

In addition to the these settings, jqGrid adds the id and name attribute.

When this element is created (usually in form editing) the form does not become ENCTYPE=“multipart/form-data” in order to upload the file. You should apply another plugin for this purpose - Ajax File Upload plugin works fine.

custom
This edit type allow definition of custom editable element. When edit type is set to custom we should provide a set of functions which should to create the element, and get the value from it in order to be posted to the server.
Functions that should be defined:

1. custom_element - this function is used to create the element. The function should return the new DOM element. Parameters passed to this function are the value and the editoptions from colModel.
2. custom_value - this function should return the value from the element after the editing in order to post it to the server. Parameter passed to this function is the element object

When the custom element is created we automatically do the following additinal tasks:

1.add a class 'customelement'
2.add attribute name with name from colModel
3.add id according to the rules for every edited module.

See example on how to construct custom element

editoptions

editoptions property is array which contain important information about the editing column. It is important to note that in editoptins array you can set any valid attribute for the chosen edittype.

Below is the list of most commonly used options:

Property / Type / Description
value / mixed / When set for edittype checkbox this value should be a string with two possible values separated with a colon (:) - Example "editoptions"=>array("value"=>“Yes:No”) where the first value determines the checked property.
When set for edittype select value can be a string, object or function.
If the option is a string it must contain a set of value:label pairs with the value separated from the label with a colon (:) and ended with(;). The string should not ended with a (;)- "editoptions"=>array("value"=>“1:One;2:Two”). When defined as function - the function should return either formated string or object.
In all other cases this is the value of the input element if defined.
dataUrl / string / This option is valid only for the elements of type select - i.e., edittype:select and should represent the url for getting the data that should contain the select definition. The data is obtained via ajax call and should be a valid html select element with the desired options <select<option value='1'>One</option>…</select>. In this case you can use option group.
The ajax request is called only once when the element is created.
In inline edit or cell edit module it is called every time when you edit a new row or cell. In form edit module only once.
buildSelect / function / This option have sense only if the dataUrl parameter is set. In case where the server response can not build the select element you can use your on function to build the select. The function should return a string containing the select and options value(s) as described in dataUrl option. Parameter passed to this function is the server response. This function should be created like this "editoptions"=>array("buildSelect"=>"js:function(response){...}",..)
dataInit / function / To this function, if defined, we pass the element object. This function is called only once when the element is created. The event is called only once when the element is created.
In inline edit or cell edit module it is called every time when you edit a new row or cell. In form edit module only once.
dataEvents / array / list of events to apply to the data element; uses jQuery bind like $(”#id”).bind(type, [data], fn) to bind events to data element.
defaultValue / mixed / The option can be string or function. This option is valid only in Form Editing module when used with editGridRow method in add mode. If defined the input element is set with this value if only element is empty. If used in selects the text should be provided and not the key. Also when a function is used the function should return value.
NullIfEmpty / boolean / If the property is set to true the empty values from inline and form editing are set/added into the database as NULLs.
other options / mixed / In this case you can set any other valid attribute for the editable element. By Example if the element is edittype:'text' we can set size, maxlenght and etc. attributes. Refer to the valid attributes of of the element

editrules

This option add additional properties to the editable element and should be used in colModel. Mostly it is used to validate the user input before submitting the value(s) to the server.

Syntax:

<?php

....

$grid->setColModel(...);

$grid->setColProperty('somefield',array("editable"=>true, "editrules"=>array("edithidden"=>true, "required"=>true...), ..));

...

$grid->renderGrid(...);

...

Below is the list of available options:

Option / Type / Description
edithidden / boolean / This option is valid only in form editing module. By default the hidden fields are not editable. If the field is hidden in the grid and edithidden is set to true, the field can be edited when add or edit methods are called.
required / boolean / (true or false) if set to true, the value will be checked and if empty, an error message will be displayed.
number / boolean / (true or false) if set to true, the value will be checked and if this is not a number, an error message will be displayed.
integer / boolean / (true or false) if set to true, the value will be checked and if this is not a integer, an error message will be displayed.
minValue / number(integer) / if set, the value will be checked and if the value is less than this, an error message will be displayed.
maxValue / number(integer) / if set, the value will be checked and if the value is more than this, an error message will be displayed.
email / boolean / if set to true, the value will be checked and if this is not valid e-mail, an error message will be displayed
url / boolean / if set to true, the value will be checked and if this is not valid url, an error message will be displayed
date / boolean / if set to true a value from datefmt option is get (if not set ISO date is used) and the value will be checked and if this is not valid date, an error message will be displayed
time / boolean / if set to true, the value will be checked and if this is not valid time, an error message will be displayed. Currently we support only hh:mm format and optional am/pm at the end
custom / boolean / if set to true allow definition of the custom checking rules via a custom function. See below
custom_func / function / this function should be used when a custom option is set to true. Parameters passed to this function are the value, which should be checked and the name - the property from colModel. The function should return array with the following parameters: first parameter - true or false. The value of true mean that the checking is successful false otherwise; the second parameter have sense only if the first value is false and represent the error message which will be displayed to the user. Typically this can look like this [false,”Please enter valid value”]

formoptions

This option is valid only in form editing. The purpose of these options is to reorder the elements in the form and to add some information before and after the editing element. Should be used in colModel array. Syntax:

<?php

....

$grid->setColModel(...);

$grid->setColProperty('somefield',array("editable"=>true, "formoptions"=>array("elmprefix"=>"(*)", "rowpos"=>1, "colpos"=>2), ..));

...

$grid->renderGrid(...);

...

Below is a list of available options

Option / Type / Description
elmprefix / string / if set, a text or html content appears before the input element
elmsuffix / string / if set, a text or html content appears after the input element
label / string / if set, this replace the name from colNames array that appears as label in the form.
rowpos / number / determines the row position of the element (again with the text-label) in the form; the count begins from 1
colpos / number / determines the column position of the element (again with thelabel) in the form beginning from 1

Two elements can have equal row position, but different column position. This will place the two elements in one row on the form.