Predefined Formatter

Formatter supports advanced formatting of the contents of cells in form, in-line and cell editing.

Formatter can be used in either of two ways: Predefined and Custom.

In this section, we discuss the Predefined Formatter.

jqGrid Module Requirements

In order to use the formatting features, make sure you check the box for the Formatter module when you download jqGrid. For more information refer to Download jqGrid.

Language options

Default language formatting options are defined in the language files e.g., grid.locale-xx (where xx is the two character code for your language, en for English).

That means that the Formatter options are loaded when the grid javascript files are loaded.

The default Formatter options are different for each language file.

Here are the default Formatter options for the English file:

jQuery.jgrid = {
...
   formatter : {
     integer : {thousandsSeparator: " ", defaultValue: '0'},
     number : {decimalSeparator:".", thousandsSeparator: " ", decimalPlaces: 2, defaultValue: '0.00'},
     currency : {decimalSeparator:".", thousandsSeparator: " ", decimalPlaces: 2, prefix: "", suffix:"", defaultValue: '0.00'},
     date : {
       dayNames: [
         "Sun", "Mon", "Tue", "Wed", "Thr", "Fri", "Sat",
         "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"
       ],
       monthNames: [
         "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
         "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"
       ],
       AmPm : ["am","pm","AM","PM"],
       S: function (j) {return j < 11 || j > 13 ? ['st', 'nd', 'rd', 'th'][Math.min((j - 1) % 10, 3)] : 'th'},
       srcformat: 'Y-m-d',
       newformat: 'd/m/Y',
       parseRe: /[Tt\\\/:_;.,\t\s-]/,
       masks : {
         ISO8601Long:"Y-m-d H:i:s",
         ISO8601Short:"Y-m-d",
         ShortDate: "n/j/Y",
         LongDate: "l, F d, Y",
         FullDateTime: "l, F d, Y g:i:s A",
         MonthDay: "F d",
         ShortTime: "g:i A",
         LongTime: "g:i:s A",
         SortableDateTime: "Y-m-d\\TH:i:s",
         UniversalSortableDateTime: "Y-m-d H:i:sO",
         YearMonth: "F, Y"
       },
       reformatAfterEdit : false
     },
     baseLinkUrl: '',
     showAction: '',
     target: '',
     checkbox : {disabled:true},
     idName : 'id'
   }
...

Here you will find all the settings that you may want to review or change before using the predefined formats. These settings can also be overridden for specific columns using the formatoptions parameter in the colModel.

The second step is to set the desired formatting in colModel. This is done using the option formatter. For example.

jQuery("#grid_id").jqGrid({
...
   colModel : [
   ...
      {name:'myname', ... formatter:'number', ...},
   ...
   ],
...
});

The example above will format the contents of the 'myname' column according to the rules set for 'number' in the active language file. For example, if the source value is “1234.1”, then the value that actually will be put in the grid will be “1 234.10” using the options above.

Column Specific Options

Formatter options can be defined for particular columns, overwriting the defaults from the language file. This is accomplished by using the formatoptions array in colModel. For example:

jQuery("#grid_id").jqGrid({
...
   colModel : [
   ...
      {name:'myname', ... formatter:'currency', formatoptions:{decimalSeparator:",", thousandsSeparator: ",", decimalPlaces: 2, prefix: "$ "} } ,
   ...
   ],
...
});

This definition will overwrite the default one from the language file. In formatoptions should be placed values appropriate for the particular format type

Predefined Format Types

Below is a list of the predefined format types

All predefined types are compatible with the editing modules. This means that the numbers, links, e-mails, etc., are converted so that they can be edited correctly.
TypeOptionsDescription
integerthousandsSeparator,
defaulValue
thousandsSeparator determines the separator for the thousands, defaultValue set the default value if nothing in the data
numberdecimalSeparator,
thousandsSeparator,
decimalPlaces,
defaulValue
thousandsSeparator determines the separator for the thousands, decimalSeparator determines the separator for the decimals, decimalPlaces determine how many decimal places we should have for the number, defaultValue set the default value if nothing in the data
currencydecimalSeparator,
thousandsSeparator,
decimalPlaces,
defaulValue,
prefix,
suffix
The same as number, but we add aditional two options - prefix: text that is inserted before the number and suffix: text that is added after the number
datesrcformat,
newformat,
parseRe
srcformat is the source format - i.e. the format of the date that should be converted, newformat is the new output format. The definition of the date format uses the PHP conversions. Also you can use a set of predefined date format - see the mask options in the default date formatting set. parseRe is a expression for parsing date strings.
emailnoneWhen a mail type is used we directly add a href with mailto: before the e-mail
linktargetThe default value of the target options is null. When this options is set, we construct a link with the target property set and the cell value put in the href tag.
showlinkbaseLinkUrl,
showAction,
addParam,
target,
idName
baseLinkUrl is the link.
showAction is an additional value which is added after the baseLinkUrl.
addParam is an additional parameter that can be added after the idName property.
target, if set, is added as an additional attribute.
idName is the first parameter that is added after the showAction. By default, this is id,
checkboxdisabledThe default value for the disabled is true. This option determines if the checkbox can be changed. If set to false, the values in checkbox can be changed
selectnonethis is not a real select but a special case. See note below
actions{
keys: false,
editbutton : true,
delbutton : true,
editformbutton: false,
onEdit : null,
onSuccess: null,
afterSave:null,
onError: null,
afterRestore: null,
extraparam: {oper:'edit'},
url: null,
delOptions: {},
editOptions : {}
}
This type of formatter is a easy way to add a buttons at certain column for inline editing. We add a two types of actions edit and delete. When the editformbutton parameter is set to true the form editing dialogue appear instead of in-line edit. The option editOptions will be used only for the form editing.

Formatter type "Select"

The select type is not real select. This is used when we use some editing module and have edittype:'select'. Before this release we pass the value of the select in grid and not the key. For example:

<script>
jQuery("#grid_id").jqGrid({
...
   colModel : [ {name:'myname', edittype:'select', editoptions:{value:"1:One;2:Two"}} ... ],
...
});
</script>

In this case, the data for the grid should contain “One” or “Two” to be set in the column myname.

Now, with this setting

<script>
jQuery("#grid_id").jqGrid({
...
   colModel : [ {name:'myname', edittype:'select', formatter:'select', editoptions:{value:"1:One;2:Two"}} ... ]
...
});
</script>

the data should contain the keys (“1” or “2”), but the value (“One”, or “Two”) will be displayed in the grid.

Let's suppose that we have the following definition in colModel for the format type showlink:

<script>
jQuery("#grid_id").jqGrid({
...
   colModel: [ {name:'myname', formatter:'showlink', formatoptions:{baseLinkUrl:'someurl.php', addParam: '&action=edit'}, ...} 
      ... 
   ]
...
});
</script>

This will output the following:

http://localhost/someurl.php?id=123&action=edit

If you want to overwrite the id setting in the link and replace this with myid, then the following should be set

<script>
jQuery("#grid_id").jqGrid({
...
   colModel: [ {name:'myname', formatter:'showlink', formatoptions:{baseLinkUrl:'someurl.php', addParam: '&action=edit', idName:'myid'}, ...} 
      ... 
   ]
...
});
</script>

this will output:

http://localhost/someurl.php?myid=123&action=edit

But i don't know where from is value'123' ;

Discussion

Hector, 2010/09/04 07:17

It would be nice to be compatible with search modules.

For example: currently the format of my field ”date” on the grid is: “d/m/Y”, but in the database is “Y-m-d”; so I have to make PHP conversion.

Diosney Sarmiento Herrera, 2011/01/15 04:08, 2011/01/15 04:25

Hi!

It would be great if you made a new predefined formatter, called “password”.

This formatter would take a a password string as input and the output would be a string with the same length that the original but with masked characters(asterisksm for example).

The data can be saved in the password cell using the jquery “data” utility function, for instance.

Dean Hoover, 2011/07/29 14:06

I am building a grid with just a delete icon in the first column instead of both edit and delete as in your example. I assume that the server should emit an empty <cell> for that column. Also, I am not quite sure exactly how to construct the jqGrid call so that the delete icon does the right thing. Obviously it needs to call the server to tell it to delete a particular row. Also, is the grid automatically refreshed after the delete?

Jeffen, 2012/04/12 07:18

how to be shown in 24 hour time format ?

formatter : 'date', formatoptions : {

srcformat : 'Y-m-d H:i:s',
newformat : 'Y-m-d H:i:s'

}

Crystal, 2012/04/17 12:49

anyway that while adding new record, the column with formatter='date' can be displayed as datepicker field?????FIXME

RussellG, 2012/06/12 15:10

you can use the jqueryUI DatePicker with jqgrid like this: {

          name: 'PremiumDate',
          index: 'PremiumDate',
          align: 'left',
          sortable: true,
          formatter: 'date',
          formatoptions: {
              srcformat: 'ISO8601Long',
              newformat: 'm/d/Y',
              defaultValue:null
          },
          width: 70,
          editable: true,
          edittype: 'text',
          editoptions: {
              size: 12,
              maxlengh: 12,
              dataInit: function (element) {
                  $(element).datepicker({ dateFormat: 'mm/dd/yy' }
                            )
              }
          },
          editrules: {
              date: true
          }
      },
RussellG, 2012/06/12 15:11, 2012/06/12 15:19

How can I get jqgrid to send null to the server if a user does not enter any value in a date field? I'ts currenly sending a space for the date. My ciurrent code is this:

      {
          name: 'PremiumDate',
          index: 'PremiumDate',
          align: 'left',
          sortable: true,
          formatter: 'date',
          formatoptions: {
              srcformat: 'ISO8601Long',
              newformat: 'm/d/Y',
              defaultValue:null // does nothing!
          },
          width: 70,
          editable: true,
          edittype: 'text',
          editoptions: {
              size: 12,
              maxlengh: 12,
              dataInit: function (element) {
                  $(element).datepicker({ dateFormat: 'mm/dd/yy' }
                            )
              }
          },
          editrules: {
              date: true
          }
      },
sangho Jin, 2012/09/18 09:06

There's a mistype in Predefined Format Types list. “defaulValue” ⇒ “defaultValue”

hendry hsieh, 2012/11/20 14:51

I'm using formatter: actions, formatoptions:{ editformbutton: true }

It seems that the “actions” is showing (become editable with input type text) in the edit form.

Aren't this supposed to be hidden by default ? I believe nobody want to edit the actions in the form.

And giving option “editable: false” doesn't work. Strange, is it a bug ?

I'm doing workaround in event afterShowForm to hide the actions input.

Nice plugin by the way, love it.

You could leave a comment if you were logged in.