K4:Using "TitlePresets" Option
From In-Portal Developers Guide
(дополнение) |
Revision as of 20:20, 28 November 2010
| ||
|---|---|---|
| Статьи в этой категории | ||
|
Практически на каждой странице сайта присутствует такой элемент как заголовок (title). Это текст, в краткой форме поясняющий что за информация отображается на странице. В заголовке может быть просто текст, переводимая в зависимости от выбранного языка интерфейса фраза, а также информация о данных, отображаемых на странице. Например, если на странице отображаются данные пользователя, то в заголовке уместно показать имя этого пользователя. Если на странице имеется список заказов, то в заголовке можно показать количество заказов.
Итак, заголовок страницы можно составить из небольшого количества типичных элементов. Это позволяет практически во всех случаях использовать стандартный способ для формирования заголовка страницы и таким стандартным способом в K4 является настройка заголовков посредством задания опции TitlePresets в unit Configs и последующего вывода на странице стандартным блоком combined_header. Этот блок содержит тэг SectionTitle, который собирает элементы заголовка в строку и показывает её в стандартном, именно для этого предназначенном месте дизайна.
Поскольку тэг SectionTitle в блоке combined_header вызывается с параметром pass_params="true", то через блок combined_header можно задать любые параметры для тага SectionTitle, кроме cut_first, который уже задан внутри этого блока.
Contents |
Настройка
'TitlePresets' => Array ( 'title_preset_name' => Array ( 'new_status_labels' => Array (), 'edit_status_labels' => Array (), 'new_titlefield' => Array (), 'prefixes' => Array (), 'tag_params' => Array (), 'format' => '', ) )
В приведённом выше примере отображены ключи первого уровня, записанные в обобщённой форме. Там имеется только один заголовок "title_preset_name". Заголовков может быть сколь угодно много но, естественно, каждый из них должен иметь уникальный ключ в массиве TitlePresets. Желательно в качестве ключа выбирать строку, соответствующую по смыслу страницам, на которых заголовок будет показываться. Например
- "
user_edit" - для шаблона редактирования пользователей; - "
denied_order_list" - для списка отклонённых заказов.
Ключи настройки
| название | описание | ||
|---|---|---|---|
new_status_labels (array)
| В данном ключе для каждого, используемого в заголовке, префикса задаётся текст, обозначающий, что происходит создание новой записи. Данный текст (обычно это фраза вида "!la_title_AddingOrder!") в последствии будет вставлен вместо кода "#prefix_status#" в значении ключа format, но только когда происходит создание новой записи в базе данных. Это подробнее показано на приведённом ниже примере.
'order_edit' => Array ( 'new_status_labels' => Array ('ord' => '!la_title_AddingOrder!'), 'prefixes' => Array ('ord'), 'format' => '#ord_status#'), ),
| ||
edit_status_labels (array)
| В данном ключе для каждого, используемого в заголовке, префикса задаётся текст, обозначающий, что происходит редактирование созданной ранее записи. Данный текст (обычно это фраза вида "!la_title_EditingOrder!") в последствии будет вставлен вместо кода "#prefix_status#" в значении ключа format, но только когда происходит редактирование созданной ранее записи в базе данных. Это подробнее показано на приведённом ниже примере.
'order_edit' => Array ( 'edit_status_labels' => Array ('ord' => '!la_title_EditingOrder!'), 'prefixes' => Array ('ord'), 'format' => '#ord_status#'), ),
| ||
new_titlefield (array)
| В данном ключе для каждого, используемого в заголовке, префикса задаётся текст, показываемый вместо пустого значения поля, указанного в опции TitleField. Данный текст (обычно это фраза вида "!la_title_NewOrder!") в последствии будет вставлен вместо кода "#prefix_titlefield#" в значении ключа format, но только когда происходит создание новой записи в базе данных. Это подробнее показано на приведённом ниже примере.
'order_edit' => Array ( 'new_titlefield' => Array ('ord' => '!la_title_NewOrder!'), 'prefixes' => Array ('ord'), 'format' => '#ord_titlefield#'), ),
| ||
prefixes (array)
| В данном ключе задаётся список префиксов, используемых для вывода заголовка. При этом префиксы для объектов типа Item пишутся как есть, а к префиксам объектов типа List дописывается слово "_List". Например так задаются префиксы для одного заказа и для списка архива заказов если выходит что они оба нужны в одном заголовке:
'prefixes' => Array ('ord', 'ord.archived_List') | ||
tag_params (array)
| В этом необязательном ключе можно задать параметры инициализации для каждого из объектов, использующихся в заголовке. Инициализация объектов происходит в момент первого обращения к ним из метода kApplication::recallObject. Этот метод в качестве третьего параметра принимает массив параметров инициализации "$event_params". Данный ключ как раз и предусмотрен для того, чтобы эти параметры можно было задать. Например, чтобы изменить (override) прописанное по умолчанию количество записей, показываемых на одной странице списка, для префикса этого списка можно задать параметр "per_page":
'prefixes' => Array ('conf'), 'tag_params' => Array ( 'conf' => Array ( 'per_page' => -1 ), ),
| ||
format (string)
| Это главный ключ, представляющий из себя строку, из которой получается итоговый заголовок на странице после замены всех специальных элементов на их значения. Эта строка может содержать:
Простой текст в итоге отображается как есть. Фразы - заменяются на их перевод. Фразы должны экранироваться с помощью восклицательных знаков, например " | ||
| В этом ключе перечисляются названия (без модуля, т.е. "sample_button", а не "custom:sample_button") тех кнопок на панели инструментов, которые возможно будет в последствии прятать через Site Configs функциональность. Это будет показано на ниже приведённом примере.
'toolbar_buttons' => Array ('new_item', 'edit', 'delete', 'view'), Данная опция доступна начиная с Core v 5.0.0. |
Особые возможности ключа "format"
| название | описание |
|---|---|
#prefix[.special]_status#
| Данный код заменится на текст, заданный в массиве ключа new_status_labels, если объект находится в статусе "новый" (его ID <= 0) и на текст, заданный в массиве ключа edit_status_labels во всех остальных случаях. Эти ключи задаются с указанием префиксов в качестве ключей подмассива:
'new_status_labels' => Array ('ord' => '!la_title_AddingOrder!'), 'edit_status_labels' => Array ('ord' => '!la_title_EditingOrder!'), 'prefixes' => Array ('ord'), 'format' => '#ord_status#'), |
#prefix[.special]_titlefield#
| Данный код замениться на значение поля, определённого в конфигурации соответствующего префикса как TitleField. Подробнее это будет видно на ниже приведённом примере.
'prefixes' => Array ('ord'), 'format' => "#ord_titlefield#' - !la_title_General!", В результате выполнения выше приведённого примера в заголовке будет показано значение поля, заданного в ключе TitleField у префикса ord, то есть, поле OrderNumber от текущего заказа. Может случиться, что открыт шаблон создания записи, и поле, заданное в ключе TitleField у префикса имеет пустое значение. Для того, чтобы и в этом случае заголовок страницы выглядел содержательным, можно настроить ключ new_titlefield. Таким образом обеспечивается что код вида " 'new_titlefield' => Array ('ord' => '!la_title_NewOrder!') |
#prefix[.special]_<FieldName>#
| Также присутствует возможность вывести значение любого поля объекта указав его следующим образом: "#prefix[.special]_FieldName#". В ниже приведённом примере будет отображено значение поля OrderNumber текущего заказа.
'format' => "#ord_status# '#ord_OrderNumber#' - !la_title_General!" |
#prefix[.special]_recordcount#
| Когда для заголовка настроен объект типа List, то в заголовке можно показать количество записей. Подробнее это будет видно на ниже приведённом примере.
'prefixes' => Array ('ord.denied_List'), 'format' => "!la_title_OrdersDenied! (#ord.denied_recordcount#)" Когда в списке нет фильтров, этот код заменится на количество записей. Если же фильтры имеются, то код заменится на строку, включающую количество записей с фильтром и количество записей без фильтра, например: " |
#section_label#
| Данный код замениться на перевод опции label в описании секции, переданной в параметре section блока combined_header, который в итоге и будет показывать title preset. Это будет показано на ниже приведённом примере.
'format' => "#section_label#" Данный формат доступен начиная с Core v 5.0.0. |
Заголовок "default"
Также есть специальный заголовок "default", данные которого будут автоматически скопированы в каждый созданный заголовок. Его можно использовать для конфигурации элементов, повторяющихся в прочих заголовках. Например, такую конфигурацию, где все заголовки настроены одинаково, кроме ключа format:
'TitlePresets' => Array ( 'order_edit_general' => Array ( 'new_status_labels' => Array ('ord' => '!la_title_AddingOrder!'), 'edit_status_labels' => Array ('ord' => '!la_title_EditingOrder!'), 'new_titlefield' => Array ('ord' => '!la_title_NewOrder!'), 'prefixes' => Array ('ord'), 'format' => "#ord_status# '#ord_titlefield#' - !la_title_General!" ), 'order_edit_billing' => Array ( 'new_status_labels' => Array ('ord' => '!la_title_AddingOrder!'), 'edit_status_labels' => Array ('ord' => '!la_title_EditingOrder!'), 'new_titlefield' => Array ('ord' => '!la_title_NewOrder!'), 'prefixes' => Array ('ord'), 'format' => "#ord_status# '#ord_titlefield#' - !la_title_OrderBilling!", ), 'order_edit_shipping' => Array ( 'new_status_labels' => Array ('ord' => '!la_title_AddingOrder!'), 'edit_status_labels' => Array ('ord' => '!la_title_EditingOrder!'), 'new_titlefield' => Array ('ord' => '!la_title_NewOrder!'), 'prefixes' => Array ('ord'), 'format' => "#ord_status# '#ord_titlefield#' - !la_title_OrderShipping!" ), ),
можно заменить эквивалентной конфигурацией, убрав повторяющиеся настройки в ключ default:
'TitlePresets' => Array ( 'default' => Array ( 'new_status_labels' => Array ('ord' => '!la_title_AddingOrder!'), 'edit_status_labels' => Array ('ord' => '!la_title_EditingOrder!'), 'new_titlefield' => Array ('ord' => '!la_title_NewOrder!'), 'prefixes' => Array ('ord'), ), 'orders_edit_general' => Array ('format' => "#ord_status# '#ord_titlefield#' - !la_title_General!"), 'orders_edit_billing' => Array ('format' => "#ord_status# '#ord_titlefield#' - !la_title_OrderBilling!"), 'orders_edit_shipping' => Array ('format' => "#ord_status# '#ord_titlefield#' - !la_title_OrderShipping!"), ),
Избегая с помощью ключа default дублирования кода, облегчаются последующие изменения - изменения придётся делать только в одном месте.
Примеры использования
Заголовки в In-Portal и платформы формируются по одной схеме, но в платформе имеется 3 основных отличия:
- не используется ключ new_titlefield;
- не используется конструкция "
#prefix[.special]_recordcount#" (т.к. её результат уже виден под списком); - для главных префиксов не задаются заголовки (т.к. в них только и показывается количество записей из предыдущего пункта).
Список главного префикса
Конфигурация:
'product_list' => Array ('prefixes' => Array ('p_List'), 'format' => "!la_title_Products! (#p_recordcount#)")
Код в шаблоне:
<inp2:m_RenderElement name="combined_header" prefix="p" section="in-commerce:products" title_preset="product_list"/> 
| Для платформы заголовок списка главного префикса не задаётся и не используется. |
Редактирование главного префикса
Конфигурация:
'default' => Array ( 'new_status_labels' => Array ('p' => '!la_title_AddingProduct!'), 'edit_status_labels' => Array ('p' => '!la_title_EditingProduct!'), 'new_titlefield' => Array ('p' => '!la_title_NewProduct!'), ), 'product_edit' => Array ('prefixes' => Array ('p'), 'format' => "#p_status# '#p_titlefield#' - !la_title_General!"),
Код в шаблоне:
<inp2:m_RenderElement name="combined_header" prefix="p" section="in-commerce:products" title_preset="product_edit"/>|
| Для платформы убирается код, содежащий "'new_titlefield'".
|
Список подчинённого префикса
Конфигурация:
'default' => Array ( 'new_status_labels' => Array ('p' => '!la_title_AddingProduct!'), 'edit_status_labels' => Array ('p' => '!la_title_EditingProduct!'), 'new_titlefield' => Array ('p' => '!la_title_NewProduct!'), ), 'image_list' => Array ('prefixes' => Array ('p', 'img_List'), 'format' => "#p_status# '#p_titlefield#' - !la_title_Images! (#img_recordcount#)"),
Код в шаблоне:
<inp2:m_RenderElement name="combined_header" prefix="p" section="in-commerce:products" title_preset="image_list"/>|
| Для платформы убирается " (#img_recordcount#)" из значения ключа format и код, содежащий "'new_titlefield'".
|
Редактивание подчинённого префикса
Конфигурация:
'default' => Array ( 'new_status_labels' => Array ('p' => '!la_title_AddingProduct!'), 'edit_status_labels' => Array ('p' => '!la_title_EditingProduct!'), 'new_titlefield' => Array ('p' => '!la_title_NewProduct!'), ), 'image_edit' => Array ( 'new_status_labels' => Array ('img' => '!la_title_AddingImage!'), 'edit_status_labels' => Array ('img' => '!la_title_EditingImage!'), 'new_titlefield' => Array ('img' => '!la_title_NewImage!'), 'prefixes' => Array ('p', 'img'), 'format' => "#p_status# '#p_titlefield#' - #img_status# '#img_titlefield#'", )
Код в шаблоне:
<inp2:m_RenderElement name="combined_header" prefix="p" section="in-commerce:products" title_preset="image_edit"/>|
| Для платформы убирается код, содежащий "'new_titlefield'".
|
