Настройка TreeGrid в jqGrid

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

Следующая статья — «TreeGrid Nested Set Model в jqGrid».
Предыдущая статья — «Подтаблица как таблица в jqGrid».

Treegrid — это способ отображать иерархические данные в таблице в виде дерева.
Treegrid поддерживает Nested Set model и Adjacency model. Хорошие статьи, описывающие эти модели можно найти по ссылкам:

http://ftp.ntu.edu.tw/MySQL/tech-resources/articles/hierarchical-data.html
http://www.sitepoint.com/article/hierarchical-data-database

Установка

Для того чтобы использовать этот модуль нужно выбрать Treegrid при скачивании таблицы. Для получения более подробной информации смотрите статью «Установка jqGrid».
Разработчики могут посмотреть исходные коды в файле grid.treegrid.js в каталоге src.

Свойства

Следующие свойства могут быть установлены в свойствах таблицы для настройки treeGrid.

Свойство: ExpandColClick
Тип: boolean
Если установлено в true, то дерево будет развёртываться/сворачиваться при клике на текст развёрнутой колонки, а не только картинке.
По умолчанию: true

Свойство: ExpandColumn
Тип: string
Указывает name колонки из colModel, которая будет использоваться для развёртывания дерева. Если не указано, то используется первая колонка. Имеет смысл только при свойстве treeGrid, установленном в true.
По умолчанию: null

Свойство: treedatatype
Тип: смешанный
Определяет начальный тип данных (смотрите свойство datatype). Обычно это свойство не должно меняться. В процессе считывания значение этого свойства равно свойству datatype.
По умолчанию: null

Свойство: treeGrid
Тип: boolean
Включает/выключает treeGrid (иерархическое представление данных).
По умолчанию: false

Свойство: treeGridModel
Тип: string
Определяет метод, используемый для treeGrid. Может быть 'nested' и 'adjacency'.
По умолчанию: 'nested'

Свойство: treeIcons
Тип: array
Этот массив устанавливает иконки для дерева. Иконки должны быть корректными именами из темы. Значения по умолчанию: {plus:'ui-icon-triangle-1-e',minus:'ui-icon-triangle-1-s',leaf:'ui-icon-radio-off'}.
По умолчанию:

Свойство: treeReader
Тип: array
Расширяет colModel базовой таблицы. Описанные здесь поля добавляются в конец массива colModel и они скрыты (hidden). Это означает, что данные, возвращённые с сервера, должны иметь значения для этих полей. Полное описание всех возможных значений смотрите ниже.
По умолчанию:

Свойство: tree_root_level
Тип: numeric
Определяет уровень, на котором начинается корневой элемент при включённом treeGrid.
По умолчанию:

Если свойство gridview в таблице установлено в true, то treeGrid не будет создаваться, даже если свойство treeGrid установлено в true.

Свойство treeReader динамически добавляет колонки в colModel базовой таблицы, когда свойство treeGrid установлено в true.

Свойство treeReader добавляет разные колонки в colModel в зависимости от свойства treeGridModel, то есть мы имеем разные конфигурации для разных моделей Nested Set Model и Adjacency Model.

Сейчас jqGrid может работать только с данными, возвращёнными с сервера. Есть некоторые трюки, которые позволяют работать с локальными данными.

Важно знать, что данные, возвращённые сервером, должны быть отсортированы подходящим способом. Например:

Методы

В методах ниже record означает текущую запись, которая может быть получена с помощью метода getInd вот так:

Заметьте: Это больше не работает с версии 3.7.x. Используйте var record = jQuery("#grid_id").getRowData(rowid);.

Где rowid — это id строки. Обратите внимание на второй параметр в методе. Если второй параметр опущен или установлен в false (по умолчанию), то возвращается индекс строки. Если строку не удалось найти, то возвращается false.

Метод: addChildNode
Параметры: nodeid, parentid, data
Добавляет узел в таблицу в соответствии с параметром parentid. Параметр nodeid — уникальные значения в строке. Если пусто, то метод получает следующее значение max number + 1 из данных. Если parendid равен null, то узел добавляется как корневой. Если parentid является корректными id существующей строки, то данные добавляются как дочерние к этой строке. Параметр data — это данные для вставки.

Метод: collapseNode
Параметры: record
Сворачивает узел соответствующей записи.

Метод: collapseRow
Параметры: record
Сворачивает текущую строку.

Метод: delTreeNode
Параметры: rowid
rowid — это id строки. Удаляет указанный узел и все дочерние узлы. Не удаляет узел с сервера.

Метод: expandNode
Параметры: record
Разворачивает узел указанной записи.

Метод: expandRow
Параметры: record
Разворачивает текущую строку.

Метод: getNodeAncestors
Параметры: record
Возвращает массив родителей для указанной записи.

Метод: getNodeDepth
Параметры: record
Возвращает глубину указанной записи.

Метод: getNodeParent
Параметры: record
Возвращает родительский узел указанной записи.

Метод: getNodeChildren
Параметры: record
Возвращает массив дочерних узлов указанной записи. Возвращает пустой массив, если их нет.

Метод: getRootNodes
Параметры: нет
Возвращает массив с текущими корневыми узлами.

Метод: isNodeLoaded
Параметры: record
Возвращает true, если узел уже загружен.

Метод: isVisibleNode
Параметры: record
Возвращает true, если узел видим, и false в противном случае.

Метод: setTreeRow
Параметры: rowid, data
Такой же, как и setRowData.

Метод: SortTree
Параметры: direction
Направление сортировки. Значение direction равное 1 (означает по возрастанию) или -1 (означат по убывания. Сортировка происходит в соответствии с текущим свойством sortname из свойств таблицы.

Предупреждения и ограничения

• На текущий момент добавление узлов с помощью addRowData не поддерживается.
• На текущий момент не рекомендуется комбинировать редактирования строки и редактирование в форме с treeGrid, или развёрнутая колонка будет нередактируемой.
• Добавление узлов на текущий момент не поддерживается.
• Постраничная навигация на текущий момент отключена для treeGrid.
• Локальный поиск не поддерживается на текущий момент.
• При инициализации таблицы и считывании данных datatype автоматически устанавливается в 'local'. Это необходимо, так как treeGrid поддерживает автоматическую загрузку узлов дерева. Это означает, что вы можете загружать данные сперва только для корневого уровня для скорости и эффективности, и вы можете подгружать данные для конкретного дочернего узла только при клике на этот узел. Таблица будет определять, что там нет данных и пытаться загрузить этот узел с сервера, но в этом случае данные, отправляемые на сервер, должны иметь дополнительные параметры. Установка datatype в local' даёт возможность делать промежуточные действия перед запросом, чтобы построить правильный запрос. Смотрите Nested Set Model и Adjacency Model, чтобы узнать, что отправляется на сервер.

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

Следующая статья — «TreeGrid Nested Set Model в jqGrid».
Предыдущая статья — «Подтаблица как таблица в jqGrid».