K4:Создание списков
From In-Portal Developers Guide
Path to article:
 |
This article is not finished yet! You see this message because current Article is finished yet or contains unverified information. How to write an Article. |
| ||
|---|---|---|
| Статьи в этой категории | ||
|
Данная статья посвящена созданию списков ( или Grid ) в стандартизированной административной части проекта.
Списки позволяют выводить сколь угодно большой объем табличных данных в виде списка, разбитого по страницам.
Каждый элемент списка можно
- сортировать по убыванию или возрастанию.
- устанавливать фильтр по значению.
- скрывать из списка.
- изменять местоположение относительно других элементов списка.
Дополнительно при помощи настроек списка можно
- изменять кол-во выводимых элементов на странице.
- выделять все элементы на текущей странице или все элементы списка на всех страницах.
- настраивать поле и порядок сортировки по умолчанию
- при помощи кнопок
SearchиResetможно фильтровать список по необходимому количеству фильтров.
Есть специальные кнопки для добавления, редактирования или удаления любого элемента списка.
| Пример списка |
|---|
 |
Contents |
Шаблон списка
Пример стандартного шаблона списка.
- Префикс:
demo. - Файл:
demo_list.tpl.
<inp2:m_include t="incs/header"/> <inp2:m_RenderElement name="combined_header" section="custom:demo" prefix="demo" pagination="1"/> <!-- ToolBar ---> <table class="toolbar" height="30" cellspacing="0" cellpadding="0" width="100%" border="0"> <tr> <td> <table width="100%" cellpadding="0" cellspacing="0"> <tr> <td> <script type="text/javascript"> a_toolbar = new ToolBar(); a_toolbar.AddButton( new ToolBarButton( 'new_item', '<inp2:m_phrase label="la_ToolTip_Newdemo" escape="1"/>::<inp2:m_phrase label="la_Add" escape="1"/>', function() { std_precreate_item('demo', 'custom/demo/demo_edit'); } ) ); function edit() { std_edit_item('demo', 'custom/demo/demo_edit'); } a_toolbar.AddButton( new ToolBarButton( 'edit', '<inp2:m_phrase label="la_ToolTip_Edit" escape="1"/>::<inp2:m_phrase label="la_ShortToolTip_Edit" escape="1"/>', edit ) ); a_toolbar.AddButton( new ToolBarButton( 'delete', '<inp2:m_phrase label="la_ToolTip_Delete" escape="1"/>', function() { std_delete_items('demo'); } ) ); a_toolbar.AddButton( new ToolBarSeparator('sep1') ); a_toolbar.AddButton( new ToolBarButton( 'view', '<inp2:m_phrase label="la_ToolTip_View" escape="1"/>', function(id) { show_viewmenu(a_toolbar,'view'); } ) ); a_toolbar.Render(); </script> </td> <inp2:m_RenderElement name="search_main_toolbar" prefix="demo" grid="Default"/> </tr> </table> </td> </tr> </table> <inp2:m_RenderElement name="grid" PrefixSpecial="demo" IdField="DemoId" grid="Default" grid_filters="1"/> <script type="text/javascript"> Grids['demo'].SetDependantToolbarButtons( new Array('edit', 'delete') ); </script> <inp2:m_include t="incs/footer"/>
Данный шаблон реализует самый простой вариант списка и состоит из следующих основных частей.
- вызов блока
combined_headerдля показа заголовка списка.
<inp2:m_RenderElement name="combined_header" section="custom:demo" prefix="demo" pagination="1"/>- иницилизация блока кнопок.
a_toolbar = new ToolBar();
- код для показа кнопки добавления новой записи.
a_toolbar.AddButton( new ToolBarButton( 'new_item', '<inp2:m_phrase label="la_ToolTip_Newdemo" escape="1"/>::<inp2:m_phrase label="la_Add" escape="1"/>', function() { std_precreate_item('demo', 'custom/demo/demo_edit'); } ) );
- код для показа кнопки редактирования записи.
function edit()
{
std_edit_item('demo', 'custom/demo/demo_edit');
}
a_toolbar.AddButton(
new ToolBarButton(
'edit',
'<inp2:m_phrase label="la_ToolTip_Edit" escape="1"/>::<inp2:m_phrase label="la_ShortToolTip_Edit" escape="1"/>',
edit
)
);- код для показа кнопки удаления записи.
a_toolbar.AddButton(
new ToolBarButton(
'delete',
'<inp2:m_phrase label="la_ToolTip_Delete" escape="1"/>',
function() {
std_delete_items('demo');
}
)
);- код для показа разделителя между кнопками.
a_toolbar.AddButton( new ToolBarSeparator('sep1') );- код для показа выпадающего меню с настройками списка.
a_toolbar.AddButton(
new ToolBarButton(
'view',
'<inp2:m_phrase label="la_ToolTip_View" escape="1"/>',
function(id) {
show_viewmenu(a_toolbar,'view');
}
)
);- вызов блока для показа кнопок
SearchиReset.
<inp2:m_RenderElement name="search_main_toolbar" prefix="demo" grid="Default"/>- вызов блока
grid, который собственно и печатает сам список. Этому блоку будет посвещен отдельный раздел в статье.
<inp2:m_RenderElement name="grid" PrefixSpecial="demo" IdField="DemoId" grid="Default" grid_filters="1"/>- настройка зависимых кнопок на панели инструментов, в зависимости от выбранных в списке записей.
Grids['demo'].SetDependantToolbarButtons( new Array('edit', 'delete') );Описание параметров блока "Grid"
Пример типичного вызова блока "Grid" с базовым набором параметров.
<inp2:m_ParseBlock name="grid" PrefixSpecial="demo" IdField="DemoId" grid="Default"/>Расширенный пример вызова блока "Grid". Добавлены параметры grid_filters, limited_heights, max_row_height.
<inp2:m_ParseBlock name="grid" PrefixSpecial="demo" IdField="DemoId" grid="Default" grid_filters="1" limited_heights="true" max_row_height="100"/>
Описание основных параметров блока "Grid".
| параметр | описание |
|---|---|
name (string) | Название блока для отображения списка, по умолчанию это "grid". |
PrefixSpecial (string) | Название текущего PrefixSpecial для текущего списка. |
IdField (string) | Название поля IDField из конфигурационного файла префикса demo.
|
grid (string) | Название текущего списка из раздела Grids конфигурационного файла префикса demo.
|
grid_filters (int) | Опция устанавливает показ фильтров на списке. |
limited_heights (boolean) | Опция устанавливает ограничение на высоту элементов списка ( измеряется в пикселях ). Параметр доступен с K4:RC_feb08_1. |
max_row_height (int) | Опция устанавливает максимальное значение для высоты элементов списка в пикселях ( измеряется в пикселях ). Параметр доступен с K4:RC_feb08_1. |
Описание дополнительных параметров блока "Grid".
| параметр | описание |
|---|---|
per_page (int) | Количество записей на 1 странице, по умолчанию это 10 записей. |
no_toolbar (string) | Опция убирает показ toolbar с фильтрами на списке. Нужно поставить значение no_toolbar="no_toolbar".
|
search (string) | Опция выводит отдельный общий элемент поиска по колонкам из списка. По умолчанию установлено значение on.
|
header_block (string) | Название блока для вывода заголовков колонок списка. По умолчанию установлено значение grid_column_title.
|
filter_block (string) | Название блока для вывода фильтра колонки. По умолчанию установлено значение grid_column_filter.
|
data_block (string) | Название блока для вывода значения записи. По умолчанию установлено значение grid_data_td.
|
totals_block (string) | Название блока для вывода суммарного значения записей в колонке. По умолчанию установлено значение grid_total_td.
|
row_block (string) | Название блока для вывода тега tr при печати списка. По умолчанию установлено значение _row.
|
totals (int) | Параметр указывает списку, что при печати будут выводиться блоки с суммарным значением. По умолчанию установлено значение 0. |
grid_height (string) | Параметр задает списку высоту. По умолчанию установлено значение auto чтобы использовать всю доступную высоту. Параметр доступен с K4:RC_aug08_1. Параметр измеряется в пикселях.
|
no_special (int) | Параметр устанавливает, будут ли специальные символы преобразовываться в HTML. Пример no_special="no_special". Пробовал на символе & quot - у меня сработало ( специально проверил). По умолчанию установлено значение 0. Параметр доступен с K4:RC_aug08_1.
|
selector (string) | Название HTML элемента для индикатора редактирования записи. По умолчанию установлено значение checkbox. Чтобы изменить значение параметра, надо в описание параметров текущего списка в конфигурационном файле указать в опции 'Selector' требуемый элемент. Например 'Selector' => 'radio'. Параметр доступен с K4:RC_aug08_1.
|
grid_status (int) | Параметр устанавливает, будут ли показан блок со статистикой количества записей. По умолчанию установлено значение 1. Параметер доступен с K4:RC_aug08_1. |
Настройка зависимых (от выбранных в списке записей) кнопок на панели инструментов
Есть ситуации, когда кнопки на панели инструментов могут быть доступны ( активны ) или не доступны ( не активны ).
Например:
- Кнопка
Add(добавить запись) доступна всегда, т.к. пользователь должен иметь возможность всегда добавить новую запись.
- Кнопка
Edit(редактировать запись) должна быть активна, только тогда когда пользователь выбрал запись из списка для редактирования.
Для регулирования данного процесса в шаблоне списка есть следующий код:
Grids['newsletter'].SetDependantToolbarButtons( new Array('delete', 'edit', 'move_up', 'move_down', 'new_review', 'e-mail') );В массиве нужно перечислить все названия кнопок которые зависимы от состояния выбранности записи, т.е. если запись не выбрана кнопка не активна, если выбрана, то активна.
Название кнопки, это 1 параметр для создания экземпляра класса new ToolBarButton.
Пример кнопки edit:
a_toolbar.AddButton( new ToolBarButton( 'edit', '<inp2:m_phrase label="la_ToolTip_Edit" escape="1"/>::<inp2:m_phrase label="la_ShortToolTip_Edit" escape="1"/>', edit ) );
Задание описания списка в unit config (ключ Grids)
Пример массива Grids.
'Grids' => Array( 'Default' => Array( 'Icons' => Array('default'=>'icon16_folder.gif'), 'Fields' => Array( 'DemoId' => Array( 'title'=>'la_col_Id', 'data_block' => 'grid_checkbox_td'), 'Title' => Array( 'title'=>'la_col_Title'), 'Image' => Array( 'title'=>'la_col_Image', 'data_block' => 'image_td'), 'Date' => Array( 'title'=>'la_col_Date', 'filter_block' => 'grid_date_range_filter') ), ), )
-
Default- это название списка, которое нужно указывать при вызове блоковgrid,search_main_toolbar
// grid <inp2:m_ParseBlock name="grid" PrefixSpecial="demo" IdField="DemoId" grid="Default" grid_filters="1" limited_heights="true" max_row_height="20" search="1"/> // search_main_toolbar <inp2:m_RenderElement name="search_main_toolbar" prefix="demo" grid="Default"/>
-
Icons- секция, где можно указать иконку по умолчанию, которая показываеться в начале каждой записи списка.
- массив
Fieldsслужит для описания списка выводимый на странице полей. Название элементов этого массива соответствует названиям полей из основного массива Fields.
Описание основных параметров элементов массива Fields
| название | описание |
|---|---|
title (string) | Название фразы для колонки поля |
data_block (string) | Можно указать название специального блока для отображения ячейки записи, например 'data_block' => 'image_td'.
Если не указан данный ключ, то используются название по умолчанию - |
filter_block (string) | Название блока для фильтра колонки. Значение по умолчанию grid_column_filter, т.е. фильтр типа LIKE. Доступны следующие блоки фильтров: grid_options_filter, grid_picker_filter, grid_like_combo_filter, grid_equals_filter, grid_range_filter, grid_float_range_filter, grid_date_range_filter
|
Описание блоков фильтров
| Фильтр | Изображение | Описание |
|---|---|---|
| Grid Column Filter |  | Фильтр по умолчанию, типа LIKE.
|
| Grid Options Filter |  | Фильтр в виде выпадающего списка для Field с kOptionFormatter. Например список размеров картинок.
|
| Grid Picker Filter | Аналогично Grid Options Filter | Фильтр позволяет устанавливать значения для поиска в поле, которое редактируется через блоки inp_edit_picker, inp_edit_multioptions, inp_edit_checkboxes.
|
| Grid Like Combo Filter |  | Модернизированная версия LIKE фильтра, которая по мере ввода значения, показывает результаты поиска.
|
| Grid Equals Filter |  | Фильтр для поиска по 1 значению. |
| Grid Range Filter |  | Фильтр для поиска по диапазону числовых значений. Например от 10 до 20. |
| Grid Float Range Filter | Аналогично Grid Range Filter | Фильтр для поиска по диапазону дробных значений. Например от 10.35 до 20.89. |
| Grid Date Range Filter |  | Фильтр для поиска по диапазону дат. При нажатие на иконку календаря, можно через удобный интерефейс выбрать необходимую дату и установить время. |
Задание сортировки списков в unit config
Сортировка для списка задается в массиве ListSortings. Для каждого special можно задать свои варианты сортировки. По умолчанию задается общая сортировка для префикса.
'ListSortings' => Array( '' => Array ( 'ForcedSorting' => Array('Priority' => 'desc'), 'Sorting' => Array('Name' => 'asc') ), 'front' => Array ( 'Sorting' => Array('Date' => 'desc', 'Name' => 'asc' ) ) )
- Секция
ForcedSortingиспользуеться для установки 1-го поля для сортировки и все остальные сортировки уже сортируют список, который был отсортирован по полю, указанному вForcedSorting. Отметить через интерфейс эту установку поиска нельзя.
Ключ элемента массива Priority - это поле сортировки.
Значение элемента массива desc - это направление сортировки.
- Секция
Sortingзадает поля и направления обычной сортировки по умолчанию. При нажатии на ссылку сортировки на списке записей поле сортировки и ее направление может быть изменено.
Массив ConfigMapping служит для задания значений полей, направлений сортировки и значений для разделения списка нс страницы, на основе опций конфигурации, которые хранятся в таблице ConfigurationValues.
'ConfigMapping' => Array( 'PerPage' => 'Comm_Perpage_Demos', 'ShortListPerPage' => 'Comm_Perpage_Demos_Short', 'DefaultSorting1Field' => 'demo_OrderDemoBy', 'DefaultSorting2Field' => 'demo_OrderDemoThenBy', 'DefaultSorting1Dir' => 'demo_OrderDemoByDir', 'DefaultSorting2Dir' => 'demo_OrderDemoThenByDir' )
Ключ элемента массива PerPage.
Значение элемента массива Comm_Perpage_Demos - переменная из таблицы ConfigurationValues.
| название | описание |
|---|---|
PerPage (string) | Колличество записей на страницу. Пример задания в шаблоне <inp2:demo_InitList per_page="per_page"/> |
ShortListPerPage (string) | Колличество записей на страницу для укороченного списка. Например нужно вывести на главной странице только 5 последних новостей, а на остальных страницах список выводит по 10 записей. Пример задания в шаблоне <inp2:demo_InitList per_page="per_page"/> |
DefaultSorting1Field (string) | Название 1 - го поля для сортировки. |
DefaultSorting2Field (string) | Название 2 - го поля для сортировки. |
DefaultSorting1Dir (string) | Направление сортировки для 1 - го поля. |
DefaultSorting2Dir (string) | Направление сортировки для 2 - го поля. |
Определение этого массива в конфигурационном файле demo_config.php нужно тогда, когда есть необходимость дать возможность администратору сайта настраивать эти параметры по умолчанию в администраторской части проекта.
Описание тэга IterateGridFields
Метод IterateGridFields из kDBTagProcessor предназначен для вывода элементов списка в администраторской части сайта таких как названия колонок, фильтров колонок, значений ширины колонок и т.д.
В общем виде вызов метода следующий
<inp2:$prefix_IterateGridFields grid="$grid" mode="$mode" block="$header_block" ajax="$ajax" no_special="$no_special"/>Метод может работать в 6 режимах.
- Выводит 1 ряд значений записей списка в режиме
mode="data"при помощи блокаgrid_data_td.
- Печатает заголовки колонок списка в режиме
mode="header"при помощи блокаgrid_column_title.
- Выводят фильтры для каждой колонки в режиме
mode="filter"при помощи блокаgrid_column_filter.
- Устанавливает ширину в пикселях для каждой колонки. Режим
mode="width".
- Получает список
Fieldsиз конфигурационного файла в виде массива. Режимmode="fields". При этом не используется блок. Результат в видеJavaScriptмассива с названиями полей.
- Выводит значение
totalsдля колонки в режимеmode="data", при этом используются блокgrid_total_td.
Рассмотрим что же делает метод IterateGridFields.
function IterateGridFields($params) { // Параметр $mode нужен для задания специального блока при вызове метода $mode = $params['mode']; // По умолчанию метод берет название блока из параметра block $def_block = isset($params['block']) ? $params['block'] : ''; // Если нужно жестко задать определенный блок, то есть параметр force_block для этого $force_block = isset($params['force_block']) ? $params['force_block'] : false; // метод получает массив Fields для текущего Grid $grids = $this->Application->getUnitOption($this->Prefix,'Grids'); $grid_config = $grids[$params['grid']]['Fields']; // вызывает ColumnPickerHelper $picker_helper =& $this->Application->RecallObject('ColumnPickerHelper'); /* @var $picker_helper kColumnPickerHelper */ $picker_helper->ApplyPicker($this->getPrefixSpecial(), $grid_config, $params['grid']); // возвращает результат в виде JavaScript массива с названиями полей в режиме $mode == 'fields' if ($mode == 'fields') { return "'".join("','", array_keys($grid_config))."'"; } // устанавливает стандартные параметры блока $std_params['pass_params'] = 'true'; $std_params['PrefixSpecial'] = $this->getPrefixSpecial(); // получает текущий экземпляр объекта kDBlist $object =& $this->GetList($params); $o = ''; $i = 0; // метод foreach проходит по массиву Fields и происходит работа с опциями полей foreach ($grid_config as $field => $options) { $i++; // установка параметров блока $block_params = Array(); // имя блока $block_params['name'] = $force_block ? $force_block : (isset($options[$mode.'_block']) ? $options[$mode.'_block'] : $def_block); // название поля $block_params['field'] = $field; // устанавливает значения sort_field, если оно есть в опциях этого поля $block_params['sort_field'] = isset($options['sort_field']) ? $options['sort_field'] : $field; // устанавливает значения filter_field, если оно есть в опциях этого поля $block_params['filter_field'] = isset($options['filter_field']) ? $options['filter_field'] : $field; // получаем ширину колонки из ColumnPickerHelper $w = $picker_helper->GetWidth($field); if ($w) $options['width'] = $w; // получает из опций текущего поля значение параметра use_phrases $field_options = $object->GetFieldOptions($field); if (array_key_exists('use_phrases', $field_options)) { $block_params['use_phrases'] = $field_options['use_phrases']; } // устанавливаем значения параметра is_last - последняя ли запись ? $block_params['is_last'] = ($i == count($grid_config)); // обьединение всех 3 массивов для параметров блока. $block_params = array_merge($std_params, $options, $block_params); // вывод текущего поля в блок с параметрами. $o.= $this->Application->ParseBlock($block_params, 1); } return $o; }
Заметки редактора
| текст | коррекция |
|---|---|
| totals_block, totals | Есть подозрение, что кроме декларации блока данные параметры нигде не используются. Это нужно проверить, как в прочем факт работы каждого из параметров блока и написать результат. Если параметр описан в декларации блока, но не работает, то это нужно указать. |
| selector | Если в качестве значений данного параметра можно передавать не только "checkbox", то их все нужно указать. Они кстати указаны в упомянутой в описании данного параметра статье. |
| no_special | Описание работы параметра не соответствует действительности. Не смотря на то, что он называется также как и параметр тэга Field, но делает он совсем не это. |
| grid_height | Не указано, в чём в данном случае измеряются единицы задания высоты. |
| no_toolbar, search | Нужно проверить, а работают-ли данные параметры так, как о них написано. |
- Фильтры описывать тут необязательно, т.к. о них уже написана отдельная статья. Желательно использовать картинки фильтров из неё.
