Search Options and Events

As of version 4.0 the following new features are available

Support multiple grouping which means that a complex search crieteria can be build something like:
WHERE ( (field1 > 1 AND field1 < 10) OR (field1 LIKE 'a%') )
Search templates which simplify the user searching on most used search expressions
Validating user input when search. In irder to do this a searchrules property should be set
Showing the builded query

Searching is a way to search data (at server) on one or more field(s) at a time. When using this method we construct a modal form where the user can select a field and condition to apply the search. By default the search dialog is configured to use searching on multiple fields.
In order to change a option or event connected with the serching the following two methods should be used

setNavEvent
setNavOptions

with first parameter 'search'

By example if you want that the modal window should be not draggable do this

$grid->setNavOptions('search',array("drag"=>false));

This method uses the following properties from language file grid.locale-xx and the can be passed in the options array of the serch method

$.jgrid = {
...
   search : {
     caption: "Search...",
     Find: "Find",
     Reset: "Reset",
     odata : ['equal', 'not equal', 'less', 'less or equal','greater','greater or equal', 'begins with','does not begin with','is in','is not in','ends with','does not end with','contains','does not contain'],
     groupOps: [ { op: "AND", text: "all" }, { op: "OR", text: "any" } ],
     matchText: " match",
     rulesText: " rules"
   },
...

Option	Type	Description	Default
afterShowSearch	function	This event fires (if defined) every time after the search dialog is shown	null
beforeShowSearch	function	This event fires (if defined) every time before the search dialog is shown	null
drag	boolean	Enables or disables draging of the modal	true
caption	string	The caption of the modal	see lang file
closeAfterSearch	boolean	If set to true this closes the search dialog after the user apply a search - i.e. click on Find button	false
closeOnEscape	boolean	If set to true the dialog is closed when the user pres ESC key	false
Find	string	The text in the find button	see lang file
groupOps	array	translations strings used in advanced searching	see lang file
matchText	string	Translation text used in advanced searching	see lang file
modal	boolean	Set if the search dialog shopuld be modal	false
overlay	integer	Set the overlay of the search dialog. If set to 0 no overlay and the dialog can stay interactive allowing any other interactions into the page	10
multipleSearch	boolean	If set to true this activates the advanced searching	false
multipleGroup	boolean	If set to true this activates searching with multiple complex groups	false
top	integer	The top position of the dialog relative to grid upper left corner	0
left	integer	The left position of the dialog relative to grid upper left corner	0
showQuery	boolean	If set to true show the builded query to the user below the caption of the modal	false
errorcheck	boolean	This option determines if the validation should be performed - i.e if a rules are defined and there is a error in user input then the search is not performed	true
showOnLoad	boolean	The option is valid if the dialog is a part of the pager. Setting this option to true activates the search dialog if the grid is constructed	false
tmplNames	array	The option should be used wit tmplFilters and sets the names of the user defined search template criterias	empty
tmplFilters	empty array	Stores the diffterent user defined templates. Every element in the array is object with the appropriate setting. See the exmples how to set up templates	empty array
odata	array	Translation strings that corresponds to the sopt options	see lang file
onClose	function	If defined this event fires when the dialog is closed. Can return true or false. If the event return false the dialog will not be closed	null
onInitializeSearch	function	This event occurs only once when the modal is created	null
recreateFilter	boolean	When set to true the entry filter is destroyed unbinding all the events and it is constructed again. Use this option if you change dynamically some properties in colModel, so that they have effect	false
Reset	string	The text for the clear (reset) button	see lang file
rulesText	string	Translation text used in advanced searching	see lang file
sField	string	See sopt description	searchField
sFilter	string	Aplicable to multiple searching.	filters
sOper	string	See sopt description	searchOper
sopt	array	Use this option to set common search rules. If not set all the available options will be used. All available option are: ['eq','ne','lt','le','gt','ge','bw','bn','in','ni','ew','en','cn','nc'] The corresponding texts are in language file and mean the following: ['equal','not equal', 'less', 'less or equal','greater','greater or equal', 'begins with','does not begin with','is in','is not in','ends with','does not end with','contains','does not contain'] Note that the elements in sopt array can be mixed in any order.
sValue	string	See sopt description	searchString

Property	Type	Description
dataUrl	string	This option is valid only for the elements of type select - i.e stype:'select'. The option represent the url from where we load the select element. When this option is set the element will be filled with values from the ajax request. The data should be a valid html select element with the desired options. By example the request should contain <select><option value=“1”>One</option> <option value=“2”>Two</option></select>. This is called only once.
buildSelect	function	This option have sense only if the dataUrl parameter is set. In case where the server response can not build the select element you can use your on function to build the select. The function should return a string containing the select and options value(s) as described in dataUrl option. Parameter passed to this function is the server response
dataInit	function	If set this function is called only once when the element is created. To this function we pass the element object. dataInit: function(elem) { do something } Also use this function to attach datepicker, time picker and etc. Example: dataInit : function (elem) { $(elem).datepicker(); }
dataEvents	array	List of events to apply to the data element; uses $(”#id”).bind(type, [data], fn) to bind events to data element. Should be described like this: dataEvents: [ { type: 'click', data: { i: 7 }, fn: function(e) { console.log(e.data.i); }}, { type: 'keypress', fn: function(e) { console.log('keypress'); } } ]
attr	object	attr is object where we can set valid attributes to the created element. By example: attr : { title: “Some title” } Will set a title of the searched element
searchhidden	boolean	By default hidden elemnts in the grid are not searchable . In order to enable searching when the field is hidden set this option to true
sopt	array	This option is used only in advanced single field searching and determines the operation that is applied to the element. If not set all the available options will be used. All available option are: ['eq','ne','lt','le','gt','ge','bw','bn','in','ni','ew','en','cn','nc'] The corresponding texts are in language file and mean the following: ['equal','not equal', 'less', 'less or equal','greater','greater or equal', 'begins with','does not begin with','is in','is not in','ends with','does not end with','contains','does not contain'] Note that the elements in sopt array can be mixed in any order.
defaultValue	string	If not empty set a default value in the search input element.
value	mixed	The option is used only for stype select and defines the select options in the search dialogs. When set for stype select and dataUrl option is not set, the value can be a string or object. If the option is a string it must contain a set of value:label pairs with the value separated from the label with a colon (:) and ended with(;). The string should not ended with a (;)- editoptions:{value:“1:One;2:Two”}.If set as object it should be defined as pair name:value - editoptions:{value:{1:'One';2:'Two'}}

This option add additional properties to the search element and should be used in colModel. It is used to validate the user input before submitting the search(s) to the server.

Syntax:

<?php
....
$grid->setColModel(...);
$grid->setColProperty('somefield',array( "searchrules"=>array("searchhidden"=>true, "required"=>true...), ..));
...

$grid->renderGrid(...);
...
?>

Below is the list of available options:

Option	Type	Description
searchhidden	boolean	This option is valid only in search module. By default the hidden fields are not searchable. If the field is hidden in the grid and searchhidden is set to true, the field appear in search
required	boolean	(true or false) if set to true, the value will be checked and if empty, an error message will be displayed.
number	boolean	(true or false) if set to true, the value will be checked and if this is not a number, an error message will be displayed.
integer	boolean	(true or false) if set to true, the value will be checked and if this is not a integer, an error message will be displayed.
minValue	number(integer)	if set, the value will be checked and if the value is less than this, an error message will be displayed.
maxValue	number(integer)	if set, the value will be checked and if the value is more than this, an error message will be displayed.
email	boolean	if set to true, the value will be checked and if this is not valid e-mail, an error message will be displayed
url	boolean	if set to true, the value will be checked and if this is not valid url, an error message will be displayed
date	boolean	if set to true a value from datefmt option is get (if not set ISO date is used) and the value will be checked and if this is not valid date, an error message will be displayed
time	boolean	if set to true, the value will be checked and if this is not valid time, an error message will be displayed. Currently we support only hh:mm format and optional am/pm at the end
custom	boolean	if set to true allow definition of the custom checking rules via a custom function. See below
custom_func	function	this function should be used when a custom option is set to true. Parameters passed to this function are the value, which should be checked and the name - the property from colModel. The function should return array with the following parameters: first parameter - true or false. The value of true mean that the checking is successful false otherwise; the second parameter have sense only if the first value is false and represent the error message which will be displayed to the user. Typically this can look like this [false,”Please enter valid value”]