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.

Hint

You can redefine these functions with your on. It is needed to put your definition after the jqGrid JavaScript file is loaded.

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

any valid ajax settings according to jQuery ajax docs

return
none

isNull( mixed value, boolean strict )
Return true if value is null or undefined. If strict parameter if set to true, then the checking is strict (===) and return is true only if the value is null.
type
function

parameters

mixed value - value to be compared
boolean strict (default false) - is set to tru the comparation is strict (===)

return
boolean true or false

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 only exception is key property - validation. If this key in option is set to true, the parseDate function acts as validator returning true or false. The true result mean that the format passed the date value in the parameters.

The format of the dates follow the PHP conventions.

type
function

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

return
date string formatted 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 dialog 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

getTextWidth( string text, [string font])
Calculate the width of text string using the canvas. This function is used to calculate the max
width when the grid parameter autoResizing is enabled and re-sizing option in colModel is set to true.
This function can be replaced with your own. It is needed to redefine it after loading the grid file

type
function

parameters

string text - the text which width should be determined.
string file - the font used for the calculation. The font is a string which contain:
font-style, font-size and font-family separated with space.(see getFont function below)

return
width in pixels of the text

getFont( instance )
Return string of the instance specified, which contain: font-style, font-size and font-family separated with space.

type
function

parameters

instance - the HTML element

return
string

getFirstVisibleCol( grid instance )
Return the first visible column in the grid.

type
function

parameters

instance - the jqGrid object

return
index of the first visible column, -1 in other cases.

getLastVisibleCol( grid instance )
Return the last visible column in the grid.

type
function

parameters

instance - the jqGrid object

return
index of the last visible column, -1 in other cases.

Common functions and variables ¶

Convetions¶

List of common objects¶

Common functions and variables
¶