====== 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 [[:wiki:custom_formatter | 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 [[:wiki:download | 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.
<note>The default Formatter options are different for each language file.</note>

Here are the default Formatter options for the English file:
<code javascript>
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'
   }
...
</code>

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.

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

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:

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

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

<note>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.</note>

^Type^Options^Description^
|integer|thousandsSeparator,\\ defaulValue| thousandsSeparator determines the separator for the thousands, defaultValue set the default value if nothing in the data|
|number|decimalSeparator,\\ 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|
|currency|decimalSeparator,\\ 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|
|date|srcformat,\\ 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.|
|email|none|When a mail type is used we directly add a href with  mailto: before the  e-mail|
|link|target|The 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.|
|showlink|baseLinkUrl,\\ 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,|
|checkbox|disabled|The 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|
|select|none|this 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:

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

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

Now, with this setting

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

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

==== showlink Example ====

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

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

This will output the following:

<code html>
http://localhost/someurl.php?id=123&action=edit
</code>

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

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

this will output:

<code html>
http://localhost/someurl.php?myid=123&action=edit
</code>


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