This is an old revision of the document!


~~ODT~~

Single field searching

Single field searching is a way to search data (at server) on one field 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.  Singe Field serching

This method uses the url to post the search data and differ from the custom and toolbar search methods. The difference is that the posted search data is not in pair name:value. See below how data is posted.

Installation

In order to use this method the following modules should be included when downloading the grid: Common, Form Edit, Filter Plugin. For more information refer to Download

Calling Conventions

<script>
... 
jQuery("#grid_id").searchGrid( options );
...
</script>

or using the new API

<script>
... 
jQuery("#grid_id").jqGrid('searchGrid', options );
...
</script>

Where

  • grid_id is the id of the already constructed grid
  • options is an array of settings in name: value pairs format.

Typically when this method is called it launches the modal dialog and makes the grid inaccessible until the dialog is not closed.
This method is the default search method in the navigator if the search is enabled. The search parameters in navigator can be set the same way as the options described below.

<script>
...
jQuery("#grid_id").jqGrid({
...
   pager : '#gridpager',
...
}).navGrid('#gridpager',{view:true, del:false}, 
{}, //  default settings for edit
{}, //  default settings for add
{},  // delete instead that del:false we need this
{search_options}, // search options
{} /* view parameters*/
);
...
</script>

By default the dialog appears at upper left corner of the grid.

We add a new option overlay (default 10) in search dialog. If set to 0 the cover overlay is disabled and the user can interact with the grid.

Options

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"
   },
...
OptionTypeDescriptionDefault
afterShowSearchfunctionThis event fires (if defined) every time after the search dialog is shownnull
beforeShowSearchfunctionThis event fires (if defined) every time before the search dialog is shownnull
dragbooleanEnables or disables draging of the modaltrue
captionstringThe caption of the modalsee lang file
closeAfterSearchboolean If set to true this closes the search dialog after the user apply a search - i.e. click on Find buttonfalse
closeAfterResetboolean If set to true this closes the search dialog after the user apply a reset - i.e. click on Reset buttonfalse
closeOnEscapebooleanIf set to true the dialog is closed when the user pres ESC keyfalse
FindstringThe text in the find buttonsee lang file
groupOpsarray translations strings used in advanced searchingsee lang file
matchTextstring Translation text used in advanced searchingsee lang file
multipleSearchbooleanIf set to true this activates the advanced searchingfalse
cloneSearchRowOnAddboolean The option is valid only if multipleSearch is set to true. If set to false the cloned (added row when plus button is clicked) row is blank as opposite to true where the row is copiedtrue
odataarrayTranslation strings that corresponds to the sopt optionssee lang file
onClosefunctionIf defined this event fires when the dialog is closed. Can return true or false. If the event return false the dialog will not be closednull
onInitializeSearchfunctionThis event occurs only once when the modal is creatednull
recreateFilterbooleanWhen 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 effectfalse
ResetstringThe text for the clear (reset) buttonsee lang file
rulesTextstringTranslation text used in advanced searchingsee lang file
sFieldstringSee sopt descriptionsearchField
sFilterstringAplicable to advanced searching. See advanced searching filters
sOperstringSee sopt descriptionsearchOper
soptarrayUse 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.
sValuestringSee sopt descriptionsearchString
overlaybooleanIf this option is set to false the overlay in grid is disabled and the user can interact with the grid. true



As mentioned above posting search data differs from custom and toolbar searching. When the find button is clicked, jqGrid adds three parameters to the url (again with _search=true), in name=value pairs:

  • sField: the 'searchField', the value comes from the index in colModel
  • sValue: the 'searchString', the value is the entered value
  • sOper: the 'searchOper', the value is the type of search - see sopt array

For example if the field index is invid, operation is equal, and the searched value is 123, then the string that is posted to the server look like:

http://localhost/demo35/server.php?...&searchField=invid&searchString=123&searchOper=eq

colModel Options

As of 3.5 release jqGrid uses a common search options that can be used on every search method. Below is a list of these options that should be set in colModel. Note that some options are not applicable for particular method.

OptionTypeDescriptionDefault
searchbooleanDetermines if the field can be searched.true
stypestringDetermines the search type of the field. Can be text - also a input element with type text is created and select - a select element is createdtext
searchoptionsobject Object which contain definition, events and other properties for the searched field. See below
searchrulesobject Object which contain additional conditions for validating user input

The searchoptions object have the following properties:

The searchoptions are not applicable to custom search method. This method uses separate options.
PropertyTypeDescription
dataUrlstringThis 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.
buildSelectfunctionThis 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
dataInitfunctionIf 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();
}
dataEventsarrayList 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'); } }
]
attrobjectattr 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
searchhiddenboolean By default hidden elements in the grid are not searchable . In order to enable searching when the field is hidden set this option to true
soptarrayThis option is used only in advanced , single and toolbar field searching and determines the operation that is applied to the element. If not set all the available options will be used. When used in toolbar searching the first element is 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.
defaultValuestringIf not empty set a default value in the search input element.
valuemixed 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 end with a (;)- editoptions:{value:“1:One;2:Two”}.If set as object it should be defined as pair value:name - editoptions:{value:{1:'One',2:'Two'}}
clearSearchbooleanWhen set to false the X icon at end of search field which is responsible to clear the search data is disabled. the default value is true
Note: when the dataUrl in searchoptions object is not used for the search type select, the definitions for the select are taken first from searchoptions value property and if this is not defined a editoptions value property is used- i.e editoptions:{value:“1:one;2:two”,…}. See below how to use these options in different search methods.
2018/01/14 15:02

Discussion

atefano Romoli Fenu, 2009/09/07 08:13

How to obtain the same result as the “cancel” button of the search dialog via my own script ?

Problem to solve: If i close the search dialog the grid continue showing the last result. If i want the grid to show all the records without any filters i need to reload the entire page or reopen the search dialog and use the clear button to reset the last search. I've tried to use the onClose event to reload grid but the post data of the search remain active: _search=true and filters=[…..] . So i tried to removePostDataItem(“filters”) and it seems to work but the _search variable remain true. Suggestions ?

Tony Tomov, 2009/09/07 08:25

Hello, The same way you remove the filters - just set (since you use postext module) search parameter to false (note - not _search). Something like setPostDataItem(“search”,false);

Stefano Romoli Fenu, 2009/09/07 12:51

I've tried but doesn't work ! In the way you suggest you set only another variable named “search” (not _search) ? In the PHP code, the check is made on _search. I could change the PHP code but before doing this i prefere to know if there is a way to change the value of the _search variable ? Since the “cancel” button of the search dialog do what i want, i think there is a function that was called by the button and i would like to refere to that function from my own script.

Ken, 2009/09/16 20:07

datepicker showing up behind search.

To ensure the datepicker is on top of the search, it is important to set the z-index to something high.

<style> .ui-datepicker {z-index:1200;} </style>

See this in action on the demo page http://www.trirand.com/jqgrid/jqgrid.html (page source, line 36)

Props to Schmitty who blogged this on http://blog.schmitty.me/?p=129

Diptendu Dutta, 2009/11/26 08:08

We need new option “ResetOnClose”

Most users expect the original grid data to display when they close the search dialog. Could we add a new option ResetOnClose with default value “true” to enable this behaviour.

Having to write code on OnCLose event and mucking around in postdata to achieve this effect seems too much.

fivesixcolor, 2010/04/15 03:41

We need new option “ResetOnClose”too

There is a option “closeAfterSearch” if set to true this closes the search dialog after the user click on Find button. But this wouldnot work after user click on Reset button. There no way to ResetOnClose by writing code.

Richard Fine, 2010/01/21 15:25

This doesn't work for clientside stuff, does it?

Peter Kleynjan, 2010/06/03 09:03

Re ResetOnClose / cancel button:

I guess it's not part of the official API, but I've found one thing that works (in 3.6.5 at least; “$” is my JQuery function):

resetFilter = function(){ $(”.ui-reset”).click(); };

inside the JQ function:

  $("#mygrid").searchGrid({ onClose: resetFilter } );

Feel free to set me straight it there is a better way… -Peter

Thibault, 2011/05/29 14:42

I have a problem with the Single field searching. The display is okay but when I click the Find button nothing happens. I feel he does not know where to look, or he gets no value .. Help!

Nicolas Machado, 2011/09/21 20:39, 2011/09/22 13:42

Hi, I have the same problem, I'm trying SINGLE search and nothing happens. I thing that the samples are incomplete, as I think that $where variable sould be completed with this values: $sField = $_GET['searchField']; $sValue = $_GET['searchString']; $sOper = $_GET['searchOper'];

Am I right ? Regards Hi Again, I added those variables to the ^PHP and it works, is a good idea that a snippet code should be added to the Documentation.

You could leave a comment if you were logged in.

QR Code
QR Code wiki:singe_searching (generated for current page)