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:Using "TitlePresets" Option

From In-Portal Developers Guide

(Difference between revisions)
Jump to: navigation, search

Alex (Talk)
(категория)
Next diff →

Revision as of 15:26, 25 December 2008

Unit Configs Unit Configs
Статьи в этой категории

Практически на каждой странице сайта присутствует такой элемент как заголовок (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. Желательно в качестве ключа выбирать строку, соответствующую по смыслу страницам, на которых заголовок будет показываться. Например

Ключи настройки

название описание
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#'),
),
Image:Tipbox Icon.gif Данный ключ обычно используется вместе с ключами edit_status_labels и new_titlefield (только в In-Portal) для получения полноценных форм создания и редактирования записей.
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#'),
),
Image:Tipbox Icon.gif Данный ключ обычно используется вместе с ключами new_status_labels и new_titlefield (только в In-Portal) для получения полноценных форм создания и редактирования записей.
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#'),
),
Image:Tipbox Icon.gif Данный ключ в In-Portal обычно используется вместе с ключами new_status_labels и edit_status_labels для получения полноценных форм создания и редактирования записей.
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
	),
),
Image:Infobox Icon.gif Стоит отдельно подчеркнуть, что в ключе tag_params существует по ассоциативному массиву на каждый префикс, которому они нужны.
format (string) Это главный ключ, представляющий из себя строку, из которой получается итоговый заголовок на странице после замены всех специальных элементов на их значения. Эта строка может содержать:
  • просто текст;
  • фразы;
  • информацию об объектах типа Item, использующихся на странице;
    • статус объекта - создание или редактирование;
    • значение поля, настроенного как заголовочное (TitleField);
    • значение любого поля;
  • информацию об объектах типа List, использующихся на странице;
    • количество записей с фильтрами и без оных.

Простой текст в итоге отображается как есть. Фразы - заменяются на их перевод. Фразы должны экранироваться с помощью восклицательных знаков, например "!la_title_OrderShipping!". Прочие элементы экранируются знаком "#", например "#ord.denied_recordcount#".

Особые возможности ключа "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. Таким образом обеспечивается что код вида "#prefix[.special]_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#)"

Когда в списке нет фильтров, этот код заменится на количество записей. Если же фильтры имеются, то код заменится на строку, включающую количество записей с фильтром и количество записей без фильтра, например: "25 of 79".

Заголовок "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"/>
Image:Tipbox Icon.gif Для платформы заголовок списка главного префикса не задаётся и не используется.

Редактирование главного префикса

Конфигурация: 

'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"/>
Image:Tipbox Icon.gif Для платформы убирается код, содежащий "'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"/>
Image:Tipbox Icon.gif Для платформы убирается " (#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"/>
Image:Tipbox Icon.gif Для платформы убирается код, содежащий "'new_titlefield'".
Retrieved from "http://guide.in-portal.org/eng/index.php/K4:Using_%22TitlePresets%22_Option"