Common functions and variables


Every serious application and component uses common functions and variables, which are available everywhere in the component scope. Guriddo jqGrid is not exception.

In order to overcome duplicate functions from other libraries we have created specific $.jgrid object. In this object we store all the common functions, variables, translation texts and other objects, which we use everywhere in our code.

It is very useful to overcome duplicate function names in case of using other libraries, which have their common function and variables too.

Convetions

All the calls in our common functions and variables are in format

$.jgrid.<name>(...)

where the <name> is the name of the function with parameters or variable

Example:

var msie = $.jgrid.msie; // return true if the used navigator is Microsoft Internet Explorer
var msiever = $.jgrid.msiever(); // return the version of Microsoft Internet Explorer if available

Most of the functions are stored in base grid module and common module - grid.base.js and grid.common.js.

When Gurrido jqGrid library is loaded you can use these functions everywhere in your application.

List of common objects

Note

Parameters enclosed in [ ] are not necessary to be specified.


version
Return the current version of Guriddo jqGrid used. The format meet the GitHub conventions of the version. Example "5.2.0"

type
variable

return
string


ajaxOptions
Common ajax options that can be used to extend every ajax request made in the grid including data obtaining, editing, searching and etc.

type
object

parameters

return
none


htmlDecode( string value )
The function converts some predefined HTML entities to characters.
HTML entities that will be decoded are:

&amp; becomes & (ampersand)
&quot; becomes " (double quote)
&lt; becomes < (less than)
&gt; becomes > (greater than)

type
function

parameters

  • string value - string to be decoded

return
decoded string


htmlEncode( string value )
The function converts some predefined characters to HTML entities.
The predefined characters are:

& (ampersand) becomes &amp;
" (double quote) becomes &quot;
< (less than) becomes &lt;
> (greater than) becomes &gt;

type
function

parameters

  • string value - string to be encoded

return
encoded string


template( string template, p1,...,pN)
Simple Template engine. The function accept as first parameter a template string. The variables in this template string are enclosed in {} as numbers starting from 0. The second, third and etc parameters are the actual values which will be replaced in string, following the order.
Example:

var my template = "Page {0} of {1}";
var result = $.jgrid.template( mytemplate, 10, 20);

Result will be: "Page 10 of 20".

The template can contain named variables. In this case the second parameter should be array of objects with nm and v properties, where the nm correspond to the variable and the v is the actual value to be replaced.

var my template = "Page {current} of {total}";
var result = $.jgrid.template( mytemplate, [{nm:'current', v: 10},{nm:'total', v: 20}]);

will give the same result

type
function

parameters
- string template - template to be parsed
- mixed p1...pN - string or array (see above)

return
formated string


msie
Return true if the current used browser is Microsoft Internet Explorer
type
variable

return
boolean


msiever()
String representing the version of Microsoft Internet Explorer if available

type
function

parameters
none

return
string


getCellIndex( string cellcontent)
Find the closest table data or table header cell in the given cell (td) htmlcontent and return its index, starting from 0

type
function

parameters

  • string cellcontent - cell content

return
integer cellindex


stripHtml( string value)
Strip HTML tags from the text. It will also strip embedded JavaScript code, style information.
Example:

$.grid.stripHtml("<div>ABC</div>");  ===> "ABC"

type
function

parameters

  • string value value to be formated

return
striped string


stripPref( string pref, string source)
Strip the given prefix from the source.
Example:

$.grid.stripPref("mypref_","mypref_grid"); ===> "grid"

type
function

parameters
- string pref - prefix to be removed
- string source - source string

return
striped string


parse (string jsonstring)
Parses a json string to object, optionally transforming the value produced by parsing. If the variable $.jgrid.useJSON is set to true a build in JSON.parse is used if available, otherwise eval is used.

type
function

parameters
- string jsonstring - JSON string to be parsed

return
JSON object


useJSON
Variable indicating the use of build in JSON.parse or eval() when parsing json string. Default is true.

type
variable

return
boolean


parseDate(string format, string date, string neformat, [object options])
Parses a date with a given format format to a new format newformat using the options. All the available options are available in the Guriddo jqGrid language file under the property formatter.date - See language file

The format of the dates follow the PHP conventions.

type
function

parameters
- string format - the actual format of the date
- strind date - the date string
- string newformat - the new format to conver to
- object options - options taken from language file

return
date string formated to new format


jqID( string id )
If the id contains characters like periods or colons the function escape those characters with backslashes.
Example:

// This does not work
$( "#some:id" );

// but this works
$("#" + jqID("some:id") );

type
function

parameters
- string id - string to be escaped

return
escaped string


uidPref
The prefix which will be added in randId function. See below. Default value is 'jqg'

type
variable

return
string


randId( [string prefix] )
Return a unique string using the prefix param. If the prefix parameter is not set $.jgrid.uidPref is used.

type
function

parameters
- string prefix - string to be escaped

return
string


getAccessor(object obj, mixed expr)
On the given JSON object obj and property expr return the value. In case the expr is a function we return the apply this function to the object - i.e expr(obj);

Example:

var myobj = { "a":1, "b":2, "c": { "some": "val" } }
$.jgrid.getAccessor( myobj, "c.some" );  ===> "val"
$.jgrid.getAccessor( myobj, "c" );  ===> { "some": "val"}

type
function

parameters

  • object obj - JSON object
  • mixed expr - string or function

return
mixed value - scalar or object


getXmlData(xmlobject obj, string expr, [boolean returnObj])
On the given XML object obj and property expr return the XML object or string.
If the returnObj is true a xml object is returned, else the text representation.
If the expr is function we call that function with parameter obj - expr(obj)

type
function

parameters

  • xmlobject obj - XML object
  • mixed expr - string or function
  • boolen returnObj - boolean. default false.

return
mixed value - scalar or xml object


cellWidth()
Return true if the border and margins are included in the cell width calculation. This function is historical created for some problems in old Chrome versions.

type
function

parameters

none

return
boolean


isLocalStorage()
Return true if the localStorage is supported in the browser used.

type
function

parameters

none

return
boolean


getRegional(object inst, string param, [mixed def_val])
Return the specified content from the loaded language file specified in param. The function uses the regional parameter from the grid. The first argument is inst - reference to jqGgrid, the second is the requested parameter. If the default value is specified and is valid the function return this values instead of other settings.

Example:
If the language file is set to en (regional parameter in grid)- English and the grid has a reference like

var grid = $("#grid_id");
$.jgrid.getRegional( grid, "edit.addCaption");

will return: "Add Record"

type
function

parameters

  • object inst - jqGrid instance
  • string param - string in dot notation
  • mixed def_val - any value to be returned

return
string


isMobile
Return true if the grid is used on mobile device.

type
variable

return
boolean


from( array source)
A Hugo Bonacci jLinq port to jqGrid.
Allows you to work with sets of data using query style syntax to select, order and sort records.

The code is especially useful if you have medium sized sets of information that could be sorted or searched, but you don't want to have to use a server side call to resort your records.

type
function

parameters

  • array source - array to apply select operations

return
array with the requested results.


getMethod(string method)
Return the jqGrid method set as string in method parameter. This allow us to overcome multiple calls to a method used several time in scope.

Example:

var groupingPrepare = $.jgrid.getMethod("groupingPrepare");

will return .jqGrid('groupingPrepare') method

type
function

parameters

  • string method - valid jqGrid method

return
method


clearBeforeUnload(string grid_id)
Clear the grid data unbinding all events to it. The function is used in gridUnload and gridDestroy functions.

type
function

parameters

  • string grid_id - the id of the grid to apply the operation

return
no return value


gridUnload(string grid_id)
Removes the entrie grid, data events and parameters saving only the grid_id and pager for in DOM for future using.

type
function

parameters

  • string grid_id - the id of the grid to apply the operation

return
no return value


gridDestroy(string grid_id)
Removes the grid from the DOM.

type
function

parameters

  • string grid_id - the id of the grid to apply the operation

return
no return value


styleUI
Defines the classes used in grid for the different CSS Frameworks. The first property is the name of the CSS framework, the second property is the grid module. For more information and setting refer to CSS Frameworks guide

type
object

return
object


inlineEdit
Object which can be used to overwrite all Inline editing options.

type
object

return
object


findPos( string DOM element )
Find the top and left position of the jQuery object. The function return array, where the first element is the left position and the second is the top position.

type
function

parameters

  • string DOM element - the dom element

return
array


createModal( ... )
This function use jqModal plugin to create modal windows used in Guriddo jqGrid.

type
function

parameters

return
none


hideModal( string selector, [object options])
Hide a modal dialog defined with createModal function - see above.

type
function

parameters

  • string selector - the id of the modal created with createModal
  • object options - various options when hide the modal

return
none


viewModal( string selector, [object options])
Show a modal dialog defined with createModal function - see above.

type
function

parameters

  • string selector - the id of the modal created with createModal
  • object options - various options when show the modal

return
none


info_dialog( string caption, string content, [string button], [object options])
Create a modal with id = info_dialog and open it automatically.

type
function

parameters

  • string caption - caption of the modal
  • string content - content of the modal.
  • string button - button is a string for the close dialog - if not present no button appear.
  • object options - various options for the dialog - see below default options.
options = {
  width:290,
  height:'auto',
  dataheight: 'auto',
  drag: true,
  resize: false,
  left:250,
  top:170,
  zIndex : 1000,
  modal : false,
  closeOnEscape : true,
  align: 'center',
  buttonalign : 'center',
}

return
none


createEl( string type, object options, [string value])
Create a input element defined by type (text, select and etc.) and options set with options and default value set by value.

type
function

parameters

  • string type - input type to be created - select, text, textarea,...
  • object options - various options for element.
  • string value - default value to be set when the elemt is created.

return
DOM element


checkDate( string format, string date)
The function return true if the date has the format specifies in format parameter.

type
function

parameters

  • string format - format of the date to be checked
  • string data - date string value

return
boolean


isEmpty( string value)
Return true if the vallue set by val is empty.

type
function

parameters

  • string value - value to be checked

return
boolean


checkTime( string value )
Return true if the value is a valid time string.

type
function

parameters

  • string value - value to be checked

return
boolean


checkValues( string value, string colname, [object custom])
Performs validation of the value in edit modules with rules defined in colModel editrules.
When a custom object with editrules object is set the colModel rules are omitted.
The function perform check for the following (set as true in the object):

  • required - check if the field is empty
  • number
  • minValue
  • maxValue
  • email
  • integer
  • date
  • time
  • url

The functions checkTime and checkDate should be present.

The function return array with the following 3 items:
[ true if rule meet the condition, message in case the rule is false, item for internal use]
and need the language file, where the '...edit.msg' object is read.

type
function

parameters

  • string value - value to be chacked

return
boolean


stringify( object json )
The function extend JSON.stringify with a possibility to include functions in the object parameter

type
function

parameters

  • object json - JSON object to stringify

return
string


parseFunc( string str )
Parses a JSON string and return its JSON representation. The difference from JSON.parse is that this functions can parse functions in the string.

type
function

parameters

  • string str - JSON string to parse

return
JSON object


jsonToXML( object json, [object options])
Convert JSON object to XML string

type
function

parameters

  • object json - JSON object to convert
  • object options - various options, which default values are:
{
  xmlDecl : '<?xml version="1.0" encoding="UTF-8" ?>\n',
  attr_prefix : '-',
  encode : true
}

return
XML string


xmlToJSON( string root, [object options] )
Convert xml string to JSON object

type
function

parameters

  • string root - XML string to be converted
  • object options - various options, which default values are:
{
  force_array : [], //[ "rdf:li", "item", "-xmlns" ];
  attr_prefix : "-"
}

return
JSON object


saveAs( mixed data, [string file], [object options])
Opens a dilog to save the data on the local computer with file name file.

type
function

parameters

  • mixed data - data to be saved on local computer. Can be anything.
  • string file - file name which will be associated with this data. default jqGridFile.txt
  • object options - the parameter contain only one property type which indicates the type of the filename to be saved. Use the appropriate type for the different files. Default is for text files:
{
  type : 'plain/text;charset=utf-8'
}

return
none