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

Revision as of 17:48, 4 November 2009 by Alex (Talk | contribs)
(diff) ←Older revision | Current revision (diff) | Newer revision→ (diff)
Jump to: navigation, search

Компоненты Компоненты
Статьи в этой категории

Contents

Что такое компоненты

Компоненты - это основная единица хранения информации в K4. Компонент представляет собой набор полей для хранения информации и правил их обработки, набор тэгов специально предназначенных именно для этого компонента, и так же специального набора событий. Каждый компонент может содержать теоретически неограниченное кол-во полей. Поля - это своего рода ячейки, в которых хранится информация об отдельных свойствах компонента. Например, если бы задачей была реализация функциональности гостевой книги, это могло выглядеть так:

компонент "сообщение" с полями "автор", "дата размещения комментария", "сообщение".

Что можно делать с компонентами

Компоненты могут быть использованы для хранения, обработки и отображения информации.

Класс, содержащий специализированные тэги компонента, является наследником базового класса kDBTagProcessor, который уже содержит большинство необходимых тэгов для работы с компонентами. Однако, иногда может понадобиться добавить новый или изменить поведение какого-либо тэга для отдельного компонента - тогда изменения производятся в классе тэгов этого компонента. Таким образом, изменения не затронут основной класс и не повлияют на работу остальных существующих компонентов.

Описание работы с одним компонентом

Вывод данных компонента на шаблоне:

<inp2:sample_Field name="Title" />

В этом примере выводится содержимое поля "Title". Следует отметить, что данный код выполнится успешно только в том случае, если на странице загружен объект компонента "sample" или передан идентификатор, для его автоматической загрузки. Автозагрузка - это автоматическая загрузка компонента по переданному идентификатору. Например, если на страницу методом POST или GET была передана переменная "sample_id", то предыдущий пример выполнится успешно. Префикс "Авто" обозначает именно то, что объектом можно пользоваться без каких-либо подготовительных действий.

Создание экземпляра компонента путём вызова события "OnCreate". Необходимо учесть, что создание компонента по-умолчанию запрещено для всех пользователей фронт-части. Чтобы пользователь не получал ошибку при попытке создать какой-нибудь компонент, в обработчике событий данного компонента необходимо произвести следующие манипуляции:

function mapPermissions()
{
	parent::mapPermissions();
	$permissions = Array(
		'OnCreate'	=>	Array('self' => true),
	);
	$this->permMapping = array_merge($this->permMapping, $permissions);
}

Т.е. добавить событие "OnCreate" этого компонента в список публично доступных. При отображении полей компонента на фронт-части, в список публично доступных так же необходимо добавить событие "OnItemBuild".

Описание работы со списком

Для отображения списка компонентов применяется тэг PrintList2. Пример:

<inp2:sample_PrintList per_page="-1" render_as="block_name" columns="3" />

Приведённый выше код распечатает все компоненты "sample" внутри таблицы с тремя колонками. Каждая новая строка будет представлена результатом обработки блока "block_name".

Опция конфига ListSortings позволяет управлять последовательностью, в которой будут выводиться списки. Необходимо указать Special, поля и правила сортировки. Пример:

'ListSortings'	=> Array(
		'' => Array(
			'ForcedSorting' => Array('Priority' => 'desc'),
			'Sorting' => Array('OrderDate' => 'desc'),
		)
	),

Параметр ForcedSorting устанавливает принудительную сортировку.

Параметр конфига TitlePresets управляет различными заголовками в административной части сайта:

'TitlePresets'		=>	Array(
		'default'	=>	Array(
			'new_status_labels'		=> Array( 'order' => '!la_title_AddingOrder!' ),
			'edit_status_labels'	=> Array( 'order' => '!la_title_DetailsOfOrder!' ),
			'new_titlefield'		=> Array( 'order' => '!la_title_NewOrder!' ),
		),
 
		'order_list'=>Array(
			'prefixes'	=> Array('order_List'),
			'format' 	=>	"!la_title_purchases! (#order_recordcount#)",
		),
 
		'order_edit'=>Array(
			'prefixes'	=> Array('order'),
			'format'	=> "#order_status# #order_titlefield# - !la_title_General!",
		),
	),

#order_recordcount# - такая строка автоматически заменится на количество компонентов order (общее или количество отфильтрованных, если на гриде применены фильтры).


Гриды

Грид - это список компонентов, выводящийся в административной части сайта. Грид предоставляет полную свободу действий над компонентами: просмотр как деталей отдельного компонента, так и сортированного списка всех компонентов, а так же поиска по любому полю.


Редактирование

Редактирование компонента может осуществляться как с пользовательской части сайта, так и из административной. Разница лишь в том, что административная часть уже содержит все необходимые формы и требует только заполнения конфиг файла для компонента.

Чтобы редактировать компонент с пользовательской части сайта, нужно составить форму с полями, которые необходимо редактировать, а так же передать в скрытом поле название события, которое обработает изменения. Пример:

<form id="join_form" method="post" action="<inp2:m_FormAction m_cat_id="0" />" enctype="multipart/form-data">
</form>

Если форма содержит поля для загрузки файлов - обязательно нужно указать параметр enctype="multipart/form-data".

Основные типы полей

В полях компонентов можно хранить информацию самых различных типов. От строковых данных до изображений (фактически, всё же, изображения хранятся в специально отведённом месте, а в поле компонента записана только ссылка на файл изображения). Поля в конфигурации определяются следующим образом:

$config = Array(
	'Fields' => Array(
		'Title' => Array('type' => 'string', 'not_null' => 1, 'default' => '', 'max_len' => 255)
	)
)

В примере выше показана общая схема составления конфигурации полей. Ключ конфигурационного массива Fields указывает на то, что начинается декларация полей компонента. Сам массив Fields является ассоциативным и каждый ключ в нём является названием описываемого поля в базе данных (имена полей регистрозависимы и должны совпадать в шаблонах и в конфигурационном файле!). Массив 3-его уровня является описанием поля и перечисляет все его свойства и особенности. Далее в примерах будет приводиться только этот массив.

Текст

Пример определения текстового поля в конфигурационном файле компонента:

Array('type' => 'string', 'not_null' => 1, 'default' => '', 'max_len' => 255)

Таким массивом описывается простое текстовое поле. Обратите внимание на значение max_len, если этот параметр не указан - то в поле можно потенциально записать строку неограниченной длинны (т.е. потенциально она может не поместиться в отведённое для неё место в базе данных).

Дата

Пример определения поля с датой в конфигурационном файле компонента:

Array('type' => 'int', 'formatter' => 'kDateFormatter', 'not_null' => 1, 'default' => '#NOW#')

Дата хранится в виде timestamp, поэтому в базе необходимо поле для хранения целых чисел (длиной 11 символов). Обязательный в этом случае параметр formatter, указывающий каким форматтером будет обрабатываться поле (для даты - kDateFormatter). И ключевое слово #NOW# в качестве значения по-умолчанию, которое будет автоматически заменено на текущую дату при создании компонента.