In-Portal Developers Guide

This is a wiki-based Developers Guide for In-Portal Open Source CMS. The purpose of this guide is to provide advanced users, web developers and programmers with documentation on how to expand, customize and improve the functionality and the code the In-Portal software. Please consider contributing to our documentation writing effort.

K4:Создание списков

From In-Portal Developers Guide

Jump to: navigation, search

Gleb (Talk)
(Описание тэга IterateGridFields: поправил ошибки)
Next diff →

Revision as of 14:34, 30 January 2009


Работа со списками Работа со списками
Статьи в этой категории

Данная статья посвящена созданию списков ( или 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'.

Если не указан данный ключ, то используются название по умолчанию - grid_data_td. Для поля, которое выводит колонку с значениями IDField нужно указывать блок grid_checkbox_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

Описание блоков фильтров

Задание сортировки списков в 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;
}

Заметки редактора

  • Фильтры описывать тут необязательно, т.к. о них уже написана отдельная статья. Желательно использовать картинки фильтров из неё.