Поиск по одному полю в jqGrid

Цикл статей «Документация jqGrid на русском».

Следующая статья — «Расширенный поиск в jqGrid».
Предыдущая статья — «Пользовательский поиск в jqGrid».

Поиск по одному полю — это способ искать данные (на сервере) только по одному полю. При использовании этого метода создаётся модальная форма, где пользователь может выбрать поле и условие для поиска.

Этот метод использует url для отправки запроса на поиск и отличается от поиска в панели инструментов. Отличие в том, что отправляемые данные НЕ в формате «имя:значение». Смотрите ниже, как отправляются данные.

Установка

Для того чтобы использовать этот метод поиска, следующие модули должны быть включены при скачивании таблицы: Common, Form Edit, Filter Plugin.

Соглашения о вызове

Или используя новый API:

Где

  • grid_id — это id уже инициализированной таблицы
  • options — это массив настроек вида «имя:значение».

Обычно при вызове этого метода он создаёт диалоговую (модальную) форму и делает таблицу недоступной, пока диалоговое окно не закроется.

Этот метод является методом поиска по умолчанию в навигаторе при включении поиска. Параметры поиска в навигаторе могут быть заданы как свойства, перечисленные ниже.

По умолчанию диалоговое окно появляется в левом верхнем углу таблицы.

В диалоговом окне есть новое свойство overlay (по умолчанию 10). Если установить в 0, то пользователь сможет взаимодействовать с таблицей.

Свойства

Этот метод использует следующие свойства из языкового файла grid.locale-xx. Они могут быть переданы в объекте настроек в методе поиска.

Свойство: 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" (равенство), то строка, отправляемая на сервер будет выглядеть так:

Свойства 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

searchrules

Добавляет дополнительные свойства в элемент поиска и должно использоваться в colModel. Обычно используется для проверки пользовательского ввода перед отправкой значений на сервер. Синтаксис:

Список доступных свойств:

Свойство: 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]

Пример пользовательской проверки

Цикл статей «Документация jqGrid на русском».

Следующая статья — «Расширенный поиск в jqGrid».
Предыдущая статья — «Пользовательский поиск в jqGrid».

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *