3.1. Применение Компонентов
- Alex
Что такое компоненты
Компоненты - это основная единица хранения информации в 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, поля и правила сортировки. Пример:
Параметр ForcedSorting устанавливает принудительную сортировку.
Параметр конфига TitlePresets управляет различными заголовками в административной части сайта:
#order_recordcount# - такая строка автоматически заменится на количество компонентов order (общее или количество отфильтрованных, если на гриде применены фильтры).
Гриды
Грид - это список компонентов, выводящийся в административной части сайта. Грид предоставляет полную свободу действий над компонентами: просмотр как деталей отдельного компонента, так и сортированного списка всех компонентов, а так же поиска по любому полю.
Редактирование
Редактирование компонента может осуществляться как с пользовательской части сайта, так и из административной. Разница лишь в том, что административная часть уже содержит все необходимые формы и требует только заполнения конфиг файла для компонента.
Чтобы редактировать компонент с пользовательской части сайта, нужно составить форму с полями, которые необходимо редактировать, а так же передать в скрытом поле название события, которое обработает изменения. Пример:
Если форма содержит поля для загрузки файлов - обязательно нужно указать параметр enctype="multipart/form-data".
Основные типы полей
В полях компонентов можно хранить информацию самых различных типов. От строковых данных до изображений (фактически, всё же, изображения хранятся в специально отведённом месте, а в поле компонента записана только ссылка на файл изображения). Поля в конфигурации определяются следующим образом:
В примере выше показана общая схема составления конфигурации полей. Ключ конфигурационного массива Fields указывает на то, что начинается декларация полей компонента. Сам массив Fields является ассоциативным и каждый ключ в нём является названием описываемого поля в базе данных (имена полей регистрозависимы и должны совпадать в шаблонах и в конфигурационном файле!). Массив 3-его уровня является описанием поля и перечисляет все его свойства и особенности. Далее в примерах будет приводиться только этот массив.
Текст
Пример определения текстового поля в конфигурационном файле компонента:
Таким массивом описывается простое текстовое поле. Обратите внимание на значение max_len, если этот параметр не указан - то в поле можно потенциально записать строку неограниченной длинны (т.е. потенциально она может не поместиться в отведённое для неё место в базе данных).
Дата
Пример определения поля с датой в конфигурационном файле компонента:
Дата хранится в виде timestamp, поэтому в базе необходимо поле для хранения целых чисел (длиной 11 символов). Обязательный в этом случае параметр formatter, указывающий каким форматтером будет обрабатываться поле (для даты - kDateFormatter). И ключевое слово #NOW# в качестве значения по-умолчанию, которое будет автоматически заменено на текущую дату при создании компонента.