Цикл статей «Документация jqGrid на русском».
Следующая статья — «Расширенный поиск в jqGrid».
Предыдущая статья — «Пользовательский поиск в jqGrid».
Поиск по одному полю — это способ искать данные (на сервере) только по одному полю. При использовании этого метода создаётся модальная форма, где пользователь может выбрать поле и условие для поиска.
Этот метод использует url для отправки запроса на поиск и отличается от поиска в панели инструментов. Отличие в том, что отправляемые данные НЕ в формате «имя:значение». Смотрите ниже, как отправляются данные.
Установка
Для того чтобы использовать этот метод поиска, следующие модули должны быть включены при скачивании таблицы: Common, Form Edit, Filter Plugin.
Соглашения о вызове
1 2 3 4 5 |
<script> ... jQuery("#grid_id").searchGrid( options ); ... </script> |
Или используя новый API:
1 2 3 4 5 |
<script> ... jQuery("#grid_id").jqGrid('searchGrid', options ); ... </script> |
Где
- grid_id — это id уже инициализированной таблицы
- options — это массив настроек вида «имя:значение».
Обычно при вызове этого метода он создаёт диалоговую (модальную) форму и делает таблицу недоступной, пока диалоговое окно не закроется.
Этот метод является методом поиска по умолчанию в навигаторе при включении поиска. Параметры поиска в навигаторе могут быть заданы как свойства, перечисленные ниже.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
<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> |
По умолчанию диалоговое окно появляется в левом верхнем углу таблицы.
В диалоговом окне есть новое свойство overlay (по умолчанию 10). Если установить в 0, то пользователь сможет взаимодействовать с таблицей.
Свойства
Этот метод использует следующие свойства из языкового файла grid.locale-xx. Они могут быть переданы в объекте настроек в методе поиска.
1 2 3 4 5 6 7 8 9 |
$.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'] }, ... |
Свойство: afterShowSearch
Тип: function
Это свойство возникает каждый раз после отображения диалогового окна поиска.
По умолчанию: null
Свойство: beforeShowSearch
Тип: function
Это событие возникает каждый раз перед отображением диалогового окна поиска.
По умолчанию: null
Свойство: closeAfterSearch
Тип: boolean
Если установлено в true, то диалоговое окно поиска закрывается после осуществления поиска (например, после нажатия пользователем кнопки поиска).
По умолчанию: false
Свойство: closeAfterReset
Тип: boolean
Если установлено в true, то диалоговое окно поиска закрывается после нажатия на кнопку сброса фильтра.
По умолчанию: false
Свойство: drag
Тип: boolean
Включает/выключает возможность перетаскивать диалоговое окно.
По умолчанию: true
Свойство: jqModal
Тип: boolean
Если установлено в true, то использует плагин jqModal (если доступен) для создания диалогового окна. Если установлено в true, и плагин недоступен, то jqGrid использует свою внутреннюю функцию для создания диалогового окна.
По умолчанию: true
Свойство: resize
Тип: boolean
Включает/выключает возможность изменения размера диалогового окна.
По умолчанию: true
Свойство: modal
Тип: boolean
Если установлено в true, то диалоговое окно становится модальным.
По умолчанию: false
Свойство: width
Тип: integer
Определяет ширину диалогового окна поиска.
По умолчанию: 450
Свойство: height
Тип: смешанный
Определяет высоту диалогового окна поиска.
По умолчанию:
"auto"
Свойство: top
Тип: integer
Начальная позиция по вертикали. Значение по умолчанию 0 означает позицию верхней грани от верхнего левого угла таблицы. Если свойство jqModal равно true, и плагин jqModal доступен, то любое значение отличное от 0 означает позицию верхней грани от левого верхнего угла window.
По умолчанию: 0
Свойство: left
Тип: integer
Начальная позиция по горизонтали. Значение по умолчанию 0 означает позицию левой грани от левого верхнего угла таблицы. Если свойство jqModal равно true и плагин jqModal доступен, то любое значение отличное от 0 означает позицию левой грани от левого верхнего угла window.
По умолчанию: 0
Свойство: caption
Тип: string
Заголовок диалогового окна.
По умолчанию: смотрите языковый файл
Свойство: showQuery
Тип: boolean
Если установлено в true, то отображается запрос, который генерируется при определении пользователем условий поиска. Только для расширенного поиска. С этим свойством появляется кнопка рядом с кнопкой поиска, которая позволяет пользователю отобразить и скрыть строк с запросом интерактивно.
По умолчанию: false
Свойство: searchOnEnter
Тип: boolean
Определяет, должен ли поиск происходить при нажатии клавиши «Ввод».
По умолчанию: false
Свойство: Find
Тип: string
Надпись на кнопке поиска.
По умолчанию: смотрите языковый файл
Свойство: multipleSearch
Тип: boolean
Если установлено в true, то включает расширенный поиск.
По умолчанию: false
Свойство: multipleGroup
Тип: boolean
Если установлено в true,то включает расширенный поиск с возможностью определения составных условий.
По умолчанию: false
Свойство: odata
Тип: array
Переведённые строки, соответствующие свойствам sopt.
По умолчанию: смотрите языковый файл
Свойство: onClose
Тип: function
Если определено, то это событие возникает при закрытии диалогового окна поиска. Может вернуть true или false. Если обработчик события возвращает false, то диалоговое окно НЕ закрывается.
По умолчанию: null
Свойство: afterRedraw
Тип: function
Эта функция, если определена, запускается каждый раз при перерисовке фильтра. Фильтр перерисовывается каждый раз при добавлении или удалении правил или полей. В эту функцию передаются параметры поиска в качестве параметра.
По умолчанию: null
Свойство: onSearch
Тип: function
Если определено, то это событие возникает при нажатии кнопки поиска.
По умолчанию: null
Свойство: onReset
Тип: function
Если определено, то это событие возникает при нажатии кнопки сброса фильтра.
По умолчанию: null
Свойство: closeOnEscape
Тип: boolean
Если это свойство установлено в true, то диалоговое окно поиска закрывается при нажатии пользователем на клавишу Esc.
По умолчанию: false
Свойство: onInitializeSearch
Тип: function
Это событие возникает только один раз — при инициализации модального окна.
По умолчанию: null
Свойство: recreateForm
Тип: boolean
При установке в true форма пересоздаётся каждый раз при активации диалогового окна с новыми свойствами из colModel (если они были изменены).
По умолчанию: false
Свойство: showOnLoad
Тип: boolean
Это свойство корректно только в свойствах навигатора. Если установлено в true, то диалоговое окно появляется автоматически при первоначальном создании таблицы.
По умолчанию: false
Свойство: errorcheck
Тип: boolean
Если searchrules определены, то это свойство включает проверку ошибок. Если есть ошибка в вводе, то фильтр не отправляется на сервер, и отображается сообщение об ошибке.
По умолчанию: true
Свойство: Reset
Тип: string
Текст для кнопки сброса фильтра.
По умолчанию: смотрите языковый файл
Свойство: sField
Тип: string
Смотрите описание sopt.
По умолчанию:
"searchField"
Свойство: sFilter
Тип: string
Применяется при расширенном поиске. Смотрите статью «Расширенный поиск в jqGrid».
По умолчанию: filters
Свойство: sOper
Тип: string
Смотрите описание sopt.
По умолчанию:
searchOper
Свойство: sopt
Тип: array
Используйте это свойство для установки общих правил поиска. Если это свойство не установлено, то все доступные варианты используются. Доступные варианты:
['eq','ne','lt','le','gt','ge','bw','bn','in','ni','ew','en','cn','nc','nu','nn']. Соответствующие надписи в находятся в языковом файле и означают следующее:
['равно','не равно', 'меньше', 'меньше или равно','больше','больше или равно', 'начинается с','не начинается с','содержится в','не содержится в','оканчивается на','не оканчивается на','содержит','не содержит','равно null','не null']. Элементы в sopt могут быть перемешаны в любом порядке.
Свойство: sValue
Тип: string
Смотрите описание sopt.
По умолчанию:
"searchString"
Свойство: overlay
Тип: integer
Если это свойство установлено в 0, то слой, перекрывающий таблицу, отключён, и пользователь может взаимодействовать с таблицы при активном диалоговом окне поиска.
По умолчанию: 10
Свойство: layer
Тип: string
Если определено, то должно быть корректным id в DOM. Также если это свойство определено, то фильтр вставляется как дочерний к этому элементу.
По умолчанию: null
Свойство: tmplNames
Тип: array
Определяет имена шаблонов, используемых для облегчения пользовательского ввода. Пример:
['Template1', 'Template2',…]. Смотрите пример таблицы, чтобы узнать, как определять шаблоны.
По умолчанию: null
Свойство: tmplFilters
Тип: массив объектов
Если определён, то должен быть связан с tmplNames. Смотрите пример таблицы, чтобы узнать, как определять шаблоны.
По умолчанию: null
Свойство: tmplLabel
Тип: string
Если это свойство определено, то элемент select появляется между кнопкой сброса и поиска. Это текст, описывающий select.
По умолчанию: Template:
Свойство: zIndex
Тип: integer
Начальный z-index диалогового окна. Если вы видите диалоговую форму под другими элементами или диалогами, то вам нужно использовать в качестве этого параметра какое-нибудь большее значение, 1000 — значение по умолчанию для jQuery UI диалогов.
По умолчанию: 950
Как упоминалось выше, отправка запроса на поиск отличается от отправки запроса с панели поиска и с пользовательского поиска. При нажатии кнопки поиска jqGrid добавляет три параметра к url (вместе с _search=true), в виде пар «имя=значение»:
- sField — имя поля, по которому идёт поиск. Значение index из colModel.
- sValue — строка поиска. Введённое значение.
- sOper — операция. Смотрите свойство sopt.
Например если index равен "invid", операция равна "eq" (равенство), то строка, отправляемая на сервер будет выглядеть так:
1 |
http://localhost/demo35/server.php?...&searchField=invid&searchString=123&searchOper=eq |
Свойства colModel
Начиная с версии 3.5, jqGrid использует общие свойства поиска, которые могут быть использованы любым методом поиска. Ниже приведён список этих свойств, которые могут быть установлены в colModel. Обратите внимание, что некоторые свойства не применимы к некоторым методам.
Свойство: search
Тип: boolean
Можно ли искать по этому полю.
По умолчанию: true
Свойство: stype
Тип: string
Определяет тип поиска по полю. Может быть text (элемент ввода input type text) или select (элемент ввода input type select).
По умолчанию: text
Свойство: searchoptions
Тип: object
Объект, который содержит описание, события и другие свойства для поля, по которому происходит поиск. Смотрите ниже.
По умолчанию:
Свойство: searchrules
Тип: object
Объект, содержащий дополнительные условия для проверки пользовательского ввода. Смотрите ниже.
По умолчанию:
Объект searchoptions имеет следующие свойства:
Свойство searchoptions не применимо к пользовательскому поиску. Этот метод использует другие свойства.
Свойство: dataUrl
Тип: string
Это свойство корректно только для элементов с stype равным select. Свойство содержит url, из которого будет загружаться элемент select. Если это свойство установлено, то элемент будет заполнен значениями из AJAX-запроса. Данные должны быть корректным элементом select с желанными элементами option. Например:
<select><option value="1">One</option> <option value="2">Two</option></select>. Запрос выполняется только один раз.
Свойство: buildSelect
Тип: function
Это свойство имеет смысл только в случае, когда установлено свойство dataUrl. В случае когда ответ сервера не может построить элемент select, вы можете использовать свою функцию для построения select. Функция должна вернуть строку, содержащую select и option-ы, как они описаны в свойстве dataUrl. Функция имеет один параметр — ответ сервера.
Свойство: dataInit
Тип: function
Если установлено, то эта функция вызывается только один раз при создании элемента. В эту функцию передаётся объект элемента.
dataInit: function(elem) {do something}
Также используйте эту функцию для присоединения datepicker-а, time picker-а и т. д. Пример:
dataInit : function (elem) {$(elem).datepicker();}
Свойство: dataEvents
Тип: array
Список событий для элемента. Используется
$("#id").bind(type, [data], fn) для привязки событий к элементу. Должно быть описано примерно так:
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 — это объект, где мы устанавливаем атрибуты для созданного элемента. Пример:
attr : { title: "Some title" }
Установит атрибут title (всплывающую подсказку) для элемента поиска.
Свойство: searchhidden
Тип: boolean
По умолчанию поиск по скрытым элементам в таблице не происходит. Для того чтобы включить поиск по скрытому элементу, установите это свойство в true.
Свойство: sopt
Тип: array
Это свойство используется только в расширенном поиске, поиске по одному полю и панели поиска и определяет операцию, применяемую к элементу. Если не указано, то все доступные варианты будут использованы. При использовании панели поиска первый элемент будет использован. Все доступные варианты:
['eq','ne','lt','le','gt','ge','bw','bn','in','ni','ew','en','cn','nc']
Связанные с этим строки находятся в языковом файле и означают следующее:
[‘равно’,’не равно’, ‘меньше’, ‘меньше или равно’,’больше’,’больше или равно’, ‘начинается с’,’не начинается с’,’содержится в’,’не содержится в’,’оканчивается на’,’не оканчивается на’,’содержит’,’не содержит’]
Обратите внимание, что элементы в массиве sopt могут быть перемешаны в любом порядке.
Свойство: defaultValue
Тип: string
Если не пусто, то устанавливает значение по умолчанию для элемента ввода.
Свойство: value
Тип: смешанный
Свойство используется только для stype равного select и определяет свойства элемента select в диалоге поиска. Если stype равен select и dataUrl не установлено, то значение может быть строкой или объектом.
Если свойство является строкой, то оно должно содержать множество значений «значение:надпись» со значениями, отделёнными от надписей двоеточием и заканчивающимися точкой с запятой (;). Строка НЕ должна заканчиваться на «;». Пример:
editoptions:{value:"1:One;2:Two"}
Если указан объект, то он должен содержать пары «значение:имя»:
editoptions:{value:{1:'One',2:'Two'}}
Свойство: clearSearch
Тип: boolean
При установке в false иконка X в конце поля поиска, позволяющая очистить поле поиска, недоступна. Значение по умолчанию true.
Примечание: если свойство dataUrl в searchoptions не используется в stype select, то данные для select сначала берутся из свойства value в searchoptions, а если это не указано, то из свойства value в editoptions. Например: editoptions:{value:"1:one;2:two",…}. Смотрите ниже как использовать эти опции в различных методах поиска.
Соглашения colModel
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
<script> jQuery("#grid_id").jqGrid({ ... colModel: [ ... {name:'price', index:'price', width:60, search:true, stype:'text', searchoptions:{dataInit:datePick, attr:{title:'Select Date'}} }, ... ] ... }); datePick = function(elem) { jQuery(elem).datepicker(); } </script> |
searchrules
Добавляет дополнительные свойства в элемент поиска и должно использоваться в colModel. Обычно используется для проверки пользовательского ввода перед отправкой значений на сервер. Синтаксис:
1 2 3 4 5 6 7 8 9 10 11 |
<script> jQuery("#grid_id").jqGrid({ ... colModel: [ ... {name:'price', ..., searchrules:{required:true....}, search:true }, ... ] ... }); </script> |
Список доступных свойств:
Свойство: required
Тип: boolean
(true или false). Если установлено в true, то значение будет проверяться на пустоту. Если пусто, то отображается сообщение об ошибке.
Свойство: number
Тип: boolean
(true или false) Если установлено в true, то значение будет проверяться на то, является ли оно числом. Если введено не число, то отображается сообщение об ошибке.
Свойство: integer
Тип: boolean
(true или false) Если установлено в true, то значение будет проверяться на то, является ли оно целым числом. Если оно не является целым числом, то отображается сообщение об ошибке.
Свойство: minValue
Тип: number(integer)
Если указано, то значение проверяется на то, что оно не меньше этого числа. Если оно меньше его, то отображается сообщение об ошибке.
Свойство: maxValue
Тип: number(integer)
Если установлено, то значение проверяется, и если оно больше этого, то выводится сообщение обо ошибке.
Свойство: email
Тип: boolean
Если установлено в true, то значение проверяется, и если оно не является корректным e-mail, то отображается сообщение об ошибке.
Свойство: url
Тип: boolean
Если установлено в true, то значение проверяется, и если оно не является корректным url, то отображается сообщение об ошибке.
Свойство: date
Тип: boolean
Если установлено в true, то берётся значение из свойства datefmt (если не установлено, что используется дата в формате ISO) и значение проверяется на корректность даты. Если оно неверно, то отображается сообщение об ошибке.
Свойство: time
Тип: boolean
Если установлено в true, то значение проверяется на корректность введённого времени. Если оно не является корректным временем, то отображается сообщение об ошибке. На текущий момент поддерживается только формат hh:mm и опционально am/pm в конце.
Свойство: custom
Тип: boolean
Если установлено в true, то разрешает объявление пользовательских правил проверки с помощью пользовательской функции. Смотрите custom_func.
Свойство: custom_func
Тип: function
Эта функция должна использоваться при свойстве custom установленном в true. Параметры этой функции: значение, которое нужно проверить, и name — свойство из colModel. Функция должна вернуть массив с параметрами: первый — true или false. Значение true означает, что проверка прошла успешно, иначе — false. Второй параметр имеет смысл, только когда первый параметр равен false и содержит сообщение для пользователя. Обычно это выглядит как:
[false,"Please enter valid value"]
Свойства searchrules будут использоваться только в диалоге поиска, но не в панели поиска. Смотрите по ссылке [http://stackoverflow.com/a/9011733]
Пример пользовательской проверки
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
<script> function mypricecheck(value, colname) { if (value < 0 || value >20) return [false,"Please enter value between 0 and 20"]; else return [true,""]; } jQuery("#grid_id").jqGrid({ ... colModel: [ ... {name:'price', ..., searchrules:{custom:true, custom_func:mypricecheck....}, search:true }, ... ] ... }); </script> |
Цикл статей «Документация jqGrid на русском».
Следующая статья — «Расширенный поиск в jqGrid».
Предыдущая статья — «Пользовательский поиск в jqGrid».