Группировка данных в jqGrid

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

Следующая статья — «Группировка заголовков столбцов в jqGrid».
Предыдущая статья — «Непрокручиваемые колонки в jqGrid (Frozen columns)».

На текущий момент jqGrid поддерживает одноуровневую группировку данных.

Самый простой способ группировать данные в jqGrid — это включить группировку с помощью свойства таблицы grouping:true и указать имя поля, по которому будет происходить группировка. Имя должно быть корректым name из colModel. Поля указываются в массиве groupField, который является частью другого свойства таблицы groupingView.

Важно знать, что для того чтобы группировка происходила правильно, данные должны приходить с сервера отсортированными по этому полю. Если мы в локальном режиме (данные являются массивом), то данные группируются (сортируются) автоматически, и здесь нет необходимости дополнительно указывать сортировку по колонке.

Для того чтобы показать серверу, что мы хотим иметь группированные данные, jqGrid добавляет к параметру sidx имя поля, по которому нам необходимо группировать данные. Это происходит только в том случае, когда группировка включена и данные берутся с сервера, а не с клиента.

Например, если группировка настроена так:

То на сервер будет отправляться:

sidx = name asc, invdate

sord = desc

Как видно, в параметре sidx добавлено поле, по которому происходит группировка (name asc). При обработке запроса на сервере нужно учитывать это.

Ограничения

Когда группировка данных включена, то автоматически устанавливаются следующие свойства:

• scroll = false;
• rownumbers = false;
• treeGrid = false;
• gridview = true (также afterInsertRow не возникает);

Свойства и методы

Все свойства группировки устанавливаются как свойства таблицы и могут быть изменены динамически с помощью метода setGridParam. Два свойства отвечают за группировку данных:

1. grouping
2. groupingView

Свойство grouping логического типа и включает/выключает группировку данных в таблице. Значение по умолчанию для этого свойства — false. Чтобы включить группировку его нужно установить в true ( grouping : true).

Свойство groupingView является объектом и содержит другие свойства. Пример использования:

Список свойств groupingView:

Свойство: groupField
Тип: array
Имя name из colModel, по которому будет происходить группировка. Первое значение — первый уровень, второе значение — второй уровень и т.д.
По умолчанию: пусто

Свойство: groupOrder
Тип: array
Определяет начальную сортировку для уровней группировки. Может быть asc (по возрастанию) и desc (по убыванию). Если группировка включена, то значение по умолчанию равно asc.
По умолчанию: пусто

Свойство: groupText
Тип: array
Определяет текст заголовка для уровня группировки, который будет отображён в таблице. По умолчанию равен {0}. Значение {0} заменяется на имя, {1} заменяется на общее количество записей в этой группе. Можно указать здесь любое корректное HTML-содержимое.
По умолчанию: пусто

Свойство: groupColumnShow
Тип: array
Показывает/скрывает колонку, по которой происходит группировка. Значение здесь должно быть логического типа для уровня группировки. Если группировка включена, то это значение устанавливается в true.
По умолчанию: пусто

Свойство: groupSummary
Тип: array
Включает/выключает строку итогов (сумм) для текущего уровня группировки. Если группировка включена, то значение по умолчанию false.
По умолчанию: пусто

Свойство: groupSummaryPos
Тип: array
Указывает позицию строки итогов для текущего уровня группировки. Возможные значения: "header" , "footer". Если установлено в "header", то итоги (суммарные значения) располагаются в той же строке, что и значение группировки. Если "footer", то добавляется дополнительная строка в конец уровня группировки, и итоги отображаются в ней.
По умолчанию: "footer"

Свойство: hideFirstGroupCol
Тип: boolean
Если установлен в true, то значения в первой колонке заменяются на пустые для более красивого внешнего вида. Это обычно устанавливается в случае, когда первая колонка является колонкой группировки.
По умолчанию: false

Свойство: showSummaryOnHide
Тип: boolean
Показывает/скрывает строку итогов при сворачивании группы.
По умолчанию: false

Свойство: groupCollapse
Тип: boolean
Определяет, должна таблица первоначально показывать или скрывать строки группировки.
По умолчанию: false

Свойство: plusicon
Тип: string
Устанавливает иконку из темы jQuery UI, которая будет использоваться для строки при свёрнутой группировке.
По умолчанию: 'ui-icon-circlesmall-plus'

Свойство: minusicon
Тип: string
Устанавливает иконку из темы jQuery UI, которая будет использоваться для строки при развёрнутой группировке.
По умолчанию: 'ui-icon-circlesmall-minus'

Свойство: isInTheSameGroup
Тип: array
Количество элементов в этом массиве равно количество групп. Каждый элемент в этом массиве является функцией, которая должна возвращать true или false. В случае когда она возвращает false, элемент добавляется в группу (начинается новая группа?). В функцию передаются параметры: предыдущее значение, текущее значение, индекс группы, объект группировки.
По умолчанию: null

Свойство: formatDisplayField
Тип: array
Количество элементов в этом массиве равно количеству групп. Каждый элемент должен возвращать значение, которое будет отображать поле группировки. В функцию передаются параметры: текущее значение, исходное значение, свойство colModel, индекс группировки и объект группировки.
По умолчанию: null

Свойства colModel

Если строка итогов группировки включена, то используются дополнительные свойства из colModel: summaryType, summaryTpl, summaryRound и summaryRoundType.

summaryType
Это свойство может быть строкой с определёнными значениями или пользовательской функцией. Пример использования:

Это свойство определяет способ вычисления итогового значения. На текущий момент поддерживаются следующие встроенные функции:

• sum — вычисляет сумму значений в этой группе.
• count — вычисляет количество значений в этой группе.
• avg — вычисляет среднее арифметическое в этой группе.
• min — вычисляет минимальное значение в этой группе.
• max — вычисляет максимальное значение в этой группе.

Это свойство может быть определено как функция. В этом случае в неё передаются три параметра: текущее значение, name и объект записи. Функция должна вернуть значение.

Пример использования функции:

summaryTpl
Шаблон для строки итогов. По умолчанию используется значение "{0}", что означает вывод значения итогов. Может содержать любой HTML-код.

summaryRound

По умолчанию это свойство не определено в colModel при включённой группировке.

Значение по умолчанию для number_of_digits не определено.

Это свойство определяет количество символов после десятичной точки.

summaryRoundType

Это свойство работает только в случае, когда summaryRound определено.

Это выбор метода округления.

Значение "round" означает: «просто округли это и не храни конечные нули», "fixed" означает «округли и сохрани последние цифры, даже если они являются нулями».

Значение по умолчанию — "round" .

Методы

Метод: groupingToggle
Параметры: groupid
Возвращает: ничего
Включает/выключает группировку, указанную groupid. Параметр groupid является комбинацией идентификатора таблицы, 'ghead_' и индекса в gridView. Например, если идентификатор таблицы "mygrid", то второе значение группировки в таблице будет равно "mygridghead_1".

Метод: groupingGroupBy
Параметры: name, options
Возвращает: объект таблицы
Группирует по имени (name). Дополнительные свойства могут быть установлены с помощью второго параметра. Объект groupingView расширяется параметром options.

Метод: groupingRemove
Параметры: current
Возвращает: объект таблицы
Удаляет текущую группировку и устанавливает свойство grouping в false. Если параметр current установлен в true, то все заголовки и итоги удаляются без triggering-а таблицы. Если параметра равен false, то таблица trigger-ется.

 

 

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

Следующая статья — «Группировка заголовков столбцов в jqGrid».
Предыдущая статья — «Непрокручиваемые колонки в jqGrid (Frozen columns)».