This is an old revision of the document!


~~ODT~~

ColModel API

The colModel property defines the individual grid columns as an array of properties. This is the most important part of the jqGrid. Syntax:

jQuery("#gridid").jqGrid({
...
   colModel: [ {name:'name1', index:'index1'...}, {...}, ... ],
...
});

The available colModel properties are listed here, in alphabetic order. The only required property is name. The colModel options can be get or set using getColProp and setColProp 1) methods - See methods.

PropertyTypeDescriptionDefault
alignstringDefines the alignment of the cell in the Body layer, not in header cell. Possible values: left, center, right.left
cellattrfunctionThis function add attributes to the cell during the creation of the data - i.e dynamically. By example all valid attributes for the table cell can be used or a style attribute with different properties. The function should return string. Parameters passed to this function are:
rowId - the id of the row
val - the value which will be added in the cell
rawObject - the raw object of the data row - i.e if datatype is json - array, if datatype is xml xml node.
cm - all the properties of this column listed in the colModel
rdata - the data row which will be inserted in the row. This parameter is array of type name:value, where name is the name in colModel
null
classesstringThis option allow to add classes to the column. If more than one class will be used a space should be set. By example classes:'class1 class2' will set a class1 and class2 to every cell on that column. In the grid css there is a predefined class ui-ellipsis which allow to attach ellipsis to a particular row. Also this will work in FireFox too.empty string
datefmtstringGoverns format of sorttype:date (when datetype is set to local) and editrules {date:true} fields. Determines the expected date format for that column. Uses a PHP-like date formatting. Currently “/”, “-”, and “.” are supported as date separators. Valid formats are:
y,Y,yyyy for four digits year
YY, yy for two digits year
m,mm for months
d,dd for days.
See Array Data
ISO Date (Y-m-d)
defvalstringThe default value for the search field. This option is used only in Custom Searching and will be set as initial search. empty
editablebooleanDefines if the field is editable. This option is used in cell, inline and form modules. See editing false
editoptionsarrayArray of allowed options (attributes) for edittype option editingempty array
editrulesarraysets additional rules for the editable field editingempty array
edittypestringDefines the edit type for inline and form editing Possible values: text, textarea, select, checkbox, password, button, image and file. See also editingtext
firstsortorderstringIf set to asc or desc, the column will be sorted in that direction on first sort.Subsequent sorts of the column will toggle as usualnull
fixedboolean If set to true this option does not allow recalculation of the width of the column if shrinkToFit option is set to true. Also the width does not change if a setGridWidth method is used to change the grid width.false
formoptionsarrayDefines various options for form editing. See Form options empty
formatoptionsarrayFormat options can be defined for particular columns, overwriting the defaults from the language file. See Formatter for more details.none
formattermixedThe predefined types (string) or custom function name that controls the format of this field. See Formatter for more details.none
frozenbooleanIf set to true determines that this column will be frozen after calling the setFrozenColumns methodfalse
hidedlgbooleanIf set to true this column will not appear in the modal dialog where users can choose which columns to show or hide. See Show/Hide Columns.false
hiddenbooleanDefines if this column is hidden at initialization.false
indexstringSet the index name when sorting. Passed as sidx parameter.empty string
jsonmapstringDefines the json mapping for the column in the incoming json string. See Retrieving Data none
keybooleanOverwrite the id (defined in readers) from server. Can be set as id for the unique row id. Only one column can have this property. This option have higher priority as those from the readers. If there are more than one key set the grid finds the first one and the second is ignored.false
labelstringWhen colNames array is empty, defines the heading for this column. If both the colNames array and this setting are empty, the heading for this column comes from the name property.none
namestringSet the unique name in the grid for the column. This property is required. As well as other words used as property/event names, the reserved words (which cannot be used for names) include subgrid, cb and rn.Required
resizablebooleanDefines if the column can be re sized true
searchbooleanWhen used in search modules, disables or enables searching on that column. Search Configurationtrue
searchoptionsarrayDefines the search options used searching Search Configurationempty
sortablebooleanDefines is this can be sorted.true
sortfuncfunctionCustom function to make custom sorting when datatype is local. Three parameters a, b and direction are passed. The a and b parameters are values to be compared direction is numeric 1 and -1 for ascending and descending order. The function should return 1, -1 or 0null
sorttypemixedUsed when datatype is local. Defines the type of the column for appropriate sorting.Possible values:
int/integer - for sorting integer
float/number/currency - for sorting decimal numbers
date - for sorting date
text - for text sorting
function - defines a custom function for sorting. To this function we pass the value to be sorted and it should return a value too.
See Array Data
text
stypestring Determines the type of the element when searching. See Search Configurationtext
surlstringValid only in Custom Searching and edittype : 'select' and describes the url from where we can get already-constructed select elementempty string
template object Set of valid properties for the colModel. This option can be used if you want to overwrite a lot of default values in the column model with easy. See cmTemplate in grid options null
titlebooleanIf this option is false the title is not displayed in that column when we hover a cell with the mousetrue
widthnumberSet the initial width of the column, in pixels. This value currently can not be set as percentage150
xmlmapstringDefines the xml mapping for the column in the incomming xml file. Use a CSS specification for this See Retrieving Datanone
unformatfunction Custom function to “unformat” a value of the cell when used in editing See Custom Formatter. (Unformat is also called during sort operations. The value returned by unformat is the value compared during the sort.) null
viewablebooleanThis option is valid only when viewGridRow method is activated. When the option is set to false the column does not appear in view Formtrue

As mentioned above the options in colModel can be get or sfunction are: rowId - the id of the row
val - the value which will be added in the cell
rawObject - the raw object of the data row - i.e if datatype is json - array, if datatype is xml xml node.
cm - all the properties of this coumn listed in the colModel
rdata - the data row which will be inserted in the row. This parameter is array of type name:value, wher name is the name in colModel et usitemplateng the methods getColProp and setColProp. Below are options which can not be changed dynamically when the grid is constructed (If changed they do not have effect or will cause the grid errors). For some of these options there are methods available to change the value.

  • name
  • width
  • resizable
  • label (method avail.)
1)
Some methods require that you include in your download the so named custom module

Discussion

Ari Maniatis, 2010/01/14 12:02

Setting label to '' (empty string) does not work to clear the heading. It needs to be ' ' (a single space) at the very least.

Sumon Chowdhury, 2010/07/30 05:49

Zahar, 2011/03/29 11:12, 2011/03/29 11:16

Hello, I'm using grid with a list of JSON objects. Some objects has subobjects - for example,

Letter = {

LetterId: 4, 
IncomingNumber: 'lolol',
Organization: {
  OrganizationName: 'foo',
  OrganizationId: 11235
}

}

it's colModel looks like:

colModel: [

 	{ name: 'LetterId', index: 'LetterId', width: 25 },
 	{ name: 'IncomingNumber', index: 'IncomingNumber', width: 100 },
      { name: 'Organization.OrganizationName', index: 'Organization.OrganizationName', width: 255, sortable: true },//...and so on

One day I wanted to add sorting to my grid. And what I've found: if the column name contains a point ('.') it cannot be sortable despite of “sortable: true” option. Option index does not affect this.

Removing point from value of 'name' brings sortability, but how to get data from subfields? (Letter.Organization.OrganizationName)

Am I doing something wrong? :)


Sorry for bad English

Zahar, 2011/03/30 05:39

So, some debugging shows that this column names are used in forming some HTML element id's. Such as

<th class=“ui-state-default ui-th-column ui-th-ltr” role=“columnheader” id=“Letters_Organization.OrganizationName” …

and it's children div has an id, also containing dots ('.'). And query like $(”#id.with.dots”) will give us nothing, even if we have an element with such id.

Zahar, 2011/03/30 06:39, 2011/03/30 06:42

Oh, yeah! I've changed line 1976 of grid.base.js from

thead += ”<th id='”+ts.p.id+“_”+ts.p.colModel[i].name + … to thead += ”<th id='”+ts.p.id+“_”+ts.p.colModel[i].name.replace(/\./g, “_”) + …

And it worx! But, i don't know, if it can affect somthing else :)

Dave, 2011/05/12 04:26

Hey I have had the same problem, but I decided to rearranged my JSON so their are no subObjects. But I can see how this method would not always be a valid solution. I think your name.replace(/\./g, “_”) is brilliant and if it doesn't have any side effects then it should be implemented by Jqgrid.

You should bring it to their attention. Nice work.

Dave.

Kandeeban, 2012/01/02 18:05

Hi all,

 I have a question can we have multiple file upload in grid?
laurence, 2012/01/29 22:05

Hello,

I've got a problem with my grid. I need to tape phonetic character in my input column. My JSP is encoding with UTF-8 and when I load my data the display is good. The problem is when I tape my data. I've had

ajaxGridOptions:{contentType: 'application/json; charset=UTF-8} in my grid property.

When I save my record the character aren't saved in the good charset ! Any idea ? Thank. Lolo1367

Patricia, 2012/03/09 14:10

Hello, I need to include quite long table headers, so I would rather them being showed in two lines. Is there any option to do this? Thanks

Tsahi, 2013/02/13 14:41

you can override (or change) the original CSS to allow word wraping. look at lines 14, 15 and 20 in ui.jqgrid.css.

jsnbill, 2012/06/27 08:32

Hi, there are two columns(column1 and column2) in jqgrid, the columns' edittype are select. I want to do this: when I select column1 , the content of column2 is changing . How can I do? thanks.

dorian cuentas, 2012/07/05 13:53

Hy all, is there a way to specify tablemodel from json object… i trying to define a java class that should have all properties of a table and use that “tablemodel” to define a grid, it could be done?

Jelena Antic, 2013/02/26 14:03, 2013/02/26 14:05

Hello everyone! Is there any option to set a class for a header columns? I set classes for all my grid columns, but that afects only body layer (not header layer), and now column width doesnt match with those columns in header.

Later, I would like them to follow eachother when I resize them manualy (if possible).

Thanks

You could leave a comment if you were logged in.