Цикл статей «Документация jqGrid на русском».
Следующая статья — «Подтаблица как таблица в jqGrid».
Предыдущая статья — «Метод FormToGrid в jqGrid».
В некоторых случаях возникает необходимость отображать (или редактировать) данные, которые являются дочерними к выбранной строке родительской таблицы. Хочется, конечно, отображать только те записи, которые связаны с выбранной записью таблицы, а не записи, которые являются дочерними ко всем записям таблицы.
jqGrid предлагает два способа обработки дочерних записей:
- subGrid
- таблица как subGrid
Установка
Для того чтобы использовать этот модуль нужно выбрать Subgrid при скачивании таблицы. Для получения большей информации обратитесь к статье «Установка jqGrid».
Разработчики могут найти исходные коды в файле grid.subgrid.js в каталоге src.
Свойства
Подтаблицы используют следующие свойства, события и методы родительской таблицы, то есть вы должны устанавливать эти свойства в свойствах таблицы.
Свойство: subGrid
Тип: boolean
Если установлен в true, то включает использование подтаблиц. Если подтаблицы включены, то добавляется дополнительная колонка в левой части родительской таблицы. Эта колонка содержит картинку
'plus' (плюсик), которая показывает, что пользователь может кликнуть на неё, чтобы развернуть строку. По умолчанию все строки свёрнуты.
По умолчанию: false
Свойство: subGridOptions
Тип: object
Множество свойств для подтаблицы. Ниже перечислены все свойства с их значениями по умолчанию:
{plusicon : "ui-icon-plus",minusicon : "ui-icon-minus",openicon: "ui-icon-carat-1-sw",expandOnLoad: false,selectOnExpand : false,reloadOnExpand : true}
plusicon и minusicon определяют иконки для случаев, когда таблица свёрнута и развёрнута. Должно быть корректным именем иконки из темы.
openicon иконка под иконкой minusicon, когда подтаблица развёрнута.
expandOnLoad если установлено в true, то делает так, что все строки будут автоматически развёрнуты при загрузке новый данных.
selectOnLoad если установлено в true, то строка становится выбранной, когда происходит клик мышкой на иконке plusicon.
reloadOnExpand Если установлено в false, то данные в подтаблице загружаются только один раз, и все последующие клики просто скрывают/показывают данные, но AJAX-вызовов не происходит.
По умолчанию:
Свойство: subGridModel
Тип: array
Это свойство описывает модель данных подтаблицы, имеет эффект, только когда свойство subGrid равно true. Это массив, описывающий колонки подтаблицы. Синтаксис:
subGridModel : [{ name : ['name_1','name_2',…,'name_n'],width : [width_1,width_2,…,width_n] ,align : ['left','center',…,'right'] ,params : [param_1,…,param_n],mapping:['name_1_map','name_2_map',…,'name_n_map']}
Где
name — массив, содержащий надписи для колонок подтаблицы.
width — массив, содержащий значения ширины колонок. Этот массив должен иметь то же количество элементов, что и массив name.
align — массив, содержащий выравнивание колонок. Возможные значения:
"left",
"center" или
"right". Если пропущено, то используется выравнивание
"left".
params — массив, в который передаётся name из colModel, чтобы передавать в качестве дополнительного параметра в subGridUrl.
mapping — этот параметр используется только когда repeatitems в подтаблице установлено в false. Если указано, то используются имена из этого массива, чтобы отображать их в имена колонок подтаблицы. Если не указано, и repeatitems равно false, то используется свойство name.
По умолчанию:
Свойство: subgridtype
Тип: смешанный
Это свойство позволяет загружать подтаблицу как сервис. Если не указано, то используется свойство datatype из родительской таблицы. Смотрите пример ниже.
По умолчанию: null
Свойство: subGridWidth
Тип: integer
Определяет ширину добавленной колонки для подтаблицы, если подтаблица включены.
По умолчанию: 20
Свойство: subGridUrl
Тип: string
Это свойство имеет эффект, только если свойство subGrid установлено в true. Это свойство указывает на URL, из которого берутся данные для подтаблицы. JqGrid добавляет id строки к url в качестве параметра. Если требуется указать дополнительные параметры, то используйте свойство params из subGridModel.
По умолчанию: пустая строка
Свойство: ajaxSubgridOptions
Тип: object
Это свойство позволяет устанавливать глобальные настройки AJAX для подтаблицы. С помощью этого свойства можно переопределить все текущие настройки AJAX в подтаблице, включая событие complete.
По умолчанию: пустой объект
Для того чтобы настроить подтаблицу, вам нужно настроить subgrid в xmlReader или jsonReader. Настройки по умолчанию такие:
|
1 2 3 4 5 6 7 8 9 |
xmlReader : { ... subgrid: { root: "rows", row: "row", repeatitems: true, cell: "cell" } } |
и свойство jsonReadoer:
|
1 2 3 4 5 6 7 8 |
jsonReader : { ... subgrid: { root: "rows", repeatitems: true, cell: "cell" } } |
Правила отображения такие же, как и в обычной таблице. Для получения большей информации обратитесь к статье «Манипуляция данными в jqGrid».
Для того чтобы использовать правильный subGridType как сервис, ниже приведён простой код, который показывает, как это может быть достигнуто:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
jQuery("#grid_id").jqGrid({ ... subgridtype: function(rowidprm) { jQuery.ajax({ url:'url_to_the_service', data:rowidprm, dataType:"json", complete: function(jsondata,stat){ if(stat=="success") { var thegrid = jQuery("#grid_id")[0]; thegrid.subGridJson(eval("("+jsondata.responseText+")"),rowidprm.id); } } }); },subgrid ... }); |
где rowidprm — это массив, содержащий id строки и другие параметры, необходимые для subGridModel. И subGridJson — это метод, описанный ниже.
Использование переменной thegrid.
События
В этих событиях:
- pID — уникальный id элемента div, где можно разместить содержимое, когда включена подтаблица.
- id — id строки.
- sPostData — данные, отправляемые в запросе получения данных для подтаблицы.
Событие: subGridBeforeExpand
Параметры: pID, id
Событие возникает перед развёртыванием подтаблицы. Если установлено, то это событие должно возвращать true или false. Если оно возвращает false, то строка подтаблицы не развёртывается, и подтаблица не открывается.
Событие: subGridRowExpanded
Параметры: pID, id
Это событие возникает, когда подтаблица включена, и пользователь кликает на иконку плюса в таблице. Может использоваться для вставки произвольных данных в подтаблицу.
Событие: subGridRowColapsed
Параметры: pID, id
Это событие возникает, когда пользователь кликает на иконку минуса. Событие должно вернуть true или false. Если возвращает false, то строка не сворачивается.
Событие: serializeSubGridData
Параметры: sPostData
Если установлено, то это событие может сериализовать данные, отправляемые в AJAX-запрос. Функция должна вернуть сериализованные данные. Это событие может использоваться, когда нужно передать на сервер JSON или XML.
Методы
Метод: expandSubGridRow
Параметры: rowid
Возвращает: объект jqGrid
Развёртывает подтаблицу с id=rowid.
Метод: collapseSubGridRow
Параметры: rowid
Возвращает: объект jqGrid
Сворачивает подтаблицу для строки с id = rowid.
Метод: toggleSubGridRow
Параметры: rowid
Возвращает: объект jqGrid
Сворачивает/разворачивает строку с id = rowid.
Метод: subGridJson
Параметры: json, rowid
Возвращает: false
Добавляет строку в подтаблицу. Параметр json — это JSON-объект, параметр rowid — id строки, после которой нужно добавить данные.
Метод: subGridXml
Параметры: xml, rowid
Возвращает: false
Добавляет строку в подтаблицу. Параметр xml — это объект XML, параметр rowid — id строки, после которой нужно добавить данные.
Пример
Продолжаем использовать пример из статьи «Моя первая таблица в jqGrid». Предположим, что нам нужно отображать строки для инвойсов в подтаблице. Javascript-код для этого выглядит так:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
<script type="text/javascript"> jQuery(document).ready(function(){ jQuery("#list").jqGrid({ url:'example.php', datatype: 'xml', mtype: 'GET', colNames:['Inv No','Date', 'Amount','Tax','Total','Notes'], colModel :[ {name:'invid', index:'invid', width:55}, {name:'invdate', index:'invdate', width:90}, {name:'amount', index:'amount', width:80, align:'right'}, {name:'tax', index:'tax', width:80, align:'right'}, {name:'total', index:'total', width:80, align:'right'}, {name:'note', index:'note', width:150, sortable:false} ], pager: '#pager', rowNum:10, rowList:[10,20,30], sortname: 'invid', sortorder: 'desc', viewrecords: true, caption: 'My first grid', subGrid: true, subGridUrl : "subgrid.php", subGridModel : [ { name : ['No', 'Item', 'Qty', 'Unit', 'Line Total'], width : [55, 200, 80, 80, 80], align : ['left','left','right','right','right'], params: ['invdate'] } ] }); }); </script> |
Следующим шагом будет создание subgrid.php. Этот пример для PHP и MySQL.
Мы предполагаем, что имя таблицы, хранящей данные для элемента инвойсов, invlines, и эта таблица содержит следующие колонки: invid, item_num, item, qty, unit.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 |
subgrid <?php // get the id passed automatically to the request $id = $_GET['id']; // get the invoice date passed to this request via params array in //subGridModel. We do not use it here - this is only demostration $date_inv = $_GET['invdate']; suboptions = { plusicon : "ui-icon-plus", minusicon : "ui-icon-minus", openicon: "ui-icon-carat-1-sw", expandOnLoad: false, delayOnLoad : 50, selectOnExpand : false, reloadOnExpand : true }; // connect to the database $db = mysql_connect($dbhost, $dbuser, $dbpassword) or die("Connection Error: " . mysql_error()); mysql_select_db($database) or die("Error conecting to db."); // construct the query suboptions = { plusicon : "ui-icon-plus", minusicon : "ui-icon-minus", openicon: "ui-icon-carat-1-sw", expandOnLoad: false, delayOnLoad : 50, selectOnExpand : false, reloadOnExpand : true }; $SQL = "SELECT item_num, item, qty, unit FROM invlines WHERE invid=".$id." ORDER BY item"; $result = mysql_query( $SQL ) or die("Couldn?t execute query.".mysql_error()); // set the header information if ( stristr($_SERVER["HTTP_ACCEPT"],"application/xhtml+xml") ) { header("Content-type: application/xhtml+xml;charset=utf-8"); } else { header("Content-type: text/xml;charset=utf-8"); } echo "<?xml version='1.0' encoding='utf-8'?>"; echo "<rows>"; // be sure to put text data in CDATA while($row = mysql_fetch_array($result,MYSQL_ASSOC)) { echo "<row>"; echo "<cell>". $row[item_num]."</cell>"; echo "<cell><![CDATA[". $row[item]."]]></cell>"; echo "<cell>". $row[qty]."</cell>"; echo "<cell>". $row[unit]."</cell>"; echo "<cell>". number_format($row[qty]*$row[unit],2,'.',' ')."</cell>"; echo "</row>"; } echo "</rows>"; ?> |
Включение/выключение подтаблиц
Подтаблица может быть включена и выключена динамически (например, чтобы соответствовать данным в главной таблице).
Чтобы выключить подтаблицу:
|
1 |
jQuery("#grid_id").hideCol('subgrid'); |
Чтобы включить подтаблицу:
|
1 |
jQuery("#grid_id").showCol('subgrid'); |
Где
- grid_id — id таблицы
- subgrid — имя колонки подтаблиц. Нужно оставить, как есть.
Чтобы это работало, свойство subGrid должно быть равно true в свойствах jqGrid, только потом можно включать и выключать подтаблицу кодом, приведённым выше.
Цикл статей «Документация jqGrid на русском».
Следующая статья — «Подтаблица как таблица в jqGrid».
Предыдущая статья — «Метод FormToGrid в jqGrid».