K4:Using "TitlePresets" Option
From In-Portal Developers Guide
Path to article:
(Translation) |
|||
| Line 1: | Line 1: | ||
{{toc | category = Unit Configs | sortkey = 006.001}} | {{toc | category = Unit Configs | sortkey = 006.001}} | ||
<!-- Пишите ПОСЛЕ этой строки, пожалуйста. Ничего не стирать! --> | <!-- Пишите ПОСЛЕ этой строки, пожалуйста. Ничего не стирать! --> | ||
| - | + | Virtually every page of the site there is an element such as a [[K4:Работа с блоком "combined_header"|Title]] (<code>title</code>. This is the text in abbreviated form explaining what kind of information is displayed on the page. The title may just be the text, translated depending on the selected [[K4:Language|language]] interface, as well as information about the data displayed on the page. For example, if a page displays the [[K4:PortalUser|пользователя]] data, then the title is appropriate to show [[K4:PortalUser#Login|Username]] of the user. If the page contains a list of orders, then the title can show the number of orders. | |
| - | + | Thus, the title page can be composed of a small number of typical elements. This allows in almost all cases use a standard method for formation of the page title, and so the standard way of In-Portal is setting the header by setting the [[K4:Unit Configs#TitlePresets|TitlePresets]] option in [[K4:Unit Configs|Unit Config]] file and then output using [[K4:Работа с блоком "combined_header"|combined_header]]. This block contains [TagProcessor:SectionTitle|SectionTitle]] tag, which collects all header elements in the string and displays it in a standard, designed specifically for this site way. | |
| - | + | Since, the [[TagProcessor:SectionTitle|SectionTitle]] tag is called in [[K4:Работа с блоком "combined_header"|combined_header]] block with ''pass_params="true"'' parameter, then through [[K4:Работа с блоком "combined_header"|combined_header]] block can be set any parameters for the [[TagProcessor:SectionTitle|SectionTitle]] tag, except for [[#cut_first|cut_first]], which has already been set within that block. | |
| - | == | + | == How to Define == |
<source lang="php"> | <source lang="php"> | ||
'TitlePresets' => Array ( | 'TitlePresets' => Array ( | ||
| Line 22: | Line 22: | ||
</source> | </source> | ||
| - | |||
| - | |||
| - | |||
| - | === | + | In the above example the keys of the first level displayed in summarized/brief form. There is only one "<code>title_preset_name</code>" title. There can be any number of titles, of course, each must have a unique key in the [[K4:Unit Configs#TitlePresets|TitlePresets]] array. It's highly recommended, as a title key to pick a string related to the sense of the pages on which title will be displayed. For example: |
| + | |||
| + | * "<code>user_edit</code>" - for edit template for [[K4:PortalUser|Users]]; | ||
| + | * "<code>denied_order_list</code>" - for list of denied [[K4:Orders|Orders]]. | ||
| + | |||
| + | === Keys === | ||
{| class="prettytable" | {| class="prettytable" | ||
| - | ! | + | ! key name || description |
|- | |- | ||
| {{ConfigProperty|new_status_labels|array}} | | {{ConfigProperty|new_status_labels|array}} | ||
| - | | | + | | In this key, '''each''' used in the title [[K4:Unit Configs#Prefix|Unit prefix]] sets the text to indicate that a new record will be created. This text (usually a phrase if the form "<code>!la_title_AddingOrder!</code>") will later be inserted instead of the "<code>#prefix_status#</code>" code within the value of [[#format|format]] key, but only when, a new record is created the [[K4:Работа с базой данных|database]]. This is shown in the example below. |
<source lang="php"> | <source lang="php"> | ||
'order_edit' => Array ( | 'order_edit' => Array ( | ||
| Line 38: | Line 40: | ||
), | ), | ||
</source> | </source> | ||
| - | {{TipBox| | + | {{TipBox|This key is usually used in conjunction with [[#edit_status_labels|edit_status_labels]] and [[#new_titlefield|new_titlefield]] keys to get the most complete forms of creating and editing records.}} |
|- | |- | ||
| {{ConfigProperty|edit_status_labels|array}} | | {{ConfigProperty|edit_status_labels|array}} | ||
| - | | | + | | In this key, '''each''' used in the title [[K4:Unit Configs#Prefix|Unit prefix]] sets the text to indicate that currently is editing a previously created record. This text (usually a phrase if the form "<code>!la_title_EditingOrder!</code>") will later be inserted instead of the "<code>#prefix_status#</code>" code within the value of [[#format|format]] key, but only when, editing a previously existing in the [[K4:Работа с базой данных|database]] record. This is shown in the example below. |
<source lang="php"> | <source lang="php"> | ||
'order_edit' => Array ( | 'order_edit' => Array ( | ||
| Line 48: | Line 50: | ||
), | ), | ||
</source> | </source> | ||
| - | {{TipBox| | + | {{TipBox|This key is usually used in conjunction with [[#new_status_labels|edit_status_labels]] and [[#new_titlefield|new_titlefield]] keys to get the most complete forms of creating and editing records.}} |
|- | |- | ||
| {{ConfigProperty|new_titlefield|array}} | | {{ConfigProperty|new_titlefield|array}} | ||
| - | | | + | | In this key, '''each''' used in the title [[K4:Unit Configs#Prefix|Unit prefix]] sets the text to shown instead of '''empty field value''' specified in the [[K4:Unit Configs#TitleField|TitleField]] option. This text (usually a phrase if the form "<code>!lla_title_NewOrder!</code>") will later be inserted instead of the "<code>#prefix_titlefield#</code>" code within the value of [[#format|format]] key, but only when, a new record is created the [[K4:Работа с базой данных|database]]. This is shown in the example below. |
<source lang="php"> | <source lang="php"> | ||
'order_edit' => Array ( | 'order_edit' => Array ( | ||
| Line 58: | Line 60: | ||
), | ), | ||
</source> | </source> | ||
| - | {{TipBox| | + | {{TipBox|This key is usually used in conjunction with [[#edit_status_labels|edit_status_labels]] and [[#new_titlefield|new_titlefield]] keys to get the most complete forms of creating and editing records.}} |
|- | |- | ||
| {{ConfigProperty|prefixes|array}} | | {{ConfigProperty|prefixes|array}} | ||
| - | | | + | | In this key, given a list of [[K4:Unit Configs#Prefix|Unit prefix]]es used to display this title. Note that prefixes for <code>Item</code> object types these are not different are written as it is, but for [[K4:Unit Configs#Prefix|Unit prefix]]es with <code>List</code> object of types is appended the word "<code>_List</code>". For example, this is how how prefixes for single [[K4:Orders|Order]] record and list of archived orders should be defined if both needs to have the same title: |
| - | + | ||
<source lang="php"> | <source lang="php"> | ||
'prefixes' => Array ('ord', 'ord.archived_List') | 'prefixes' => Array ('ord', 'ord.archived_List') | ||
| Line 68: | Line 69: | ||
|- | |- | ||
| {{ConfigProperty|tag_params|array}} | | {{ConfigProperty|tag_params|array}} | ||
| - | | | + | | This optional key can be used to set initialization parameters for '''each''' of the objects used in the title. Initialization of objects occurs at the first call from a <code>kApplication::recallObject</code> method. As the third parameter this method takes an array of initialization parameters "<code>$event_params</code>". This key is just provided to set these parameters if needed. For example, to change (<code>override</code>) specified by the default number of entries displayed per page on the list. For this you can use "<code>per_page</code>" parameter which will be used as described above: |
| - | + | ||
<source lang="php"> | <source lang="php"> | ||
'prefixes' => Array ('conf'), | 'prefixes' => Array ('conf'), | ||
| Line 78: | Line 78: | ||
), | ), | ||
</source> | </source> | ||
| - | {{InfoBox| | + | {{InfoBox|Note that in [[#tag_params|tag_params]] key exists in an associative array for each [[K4:Unit Configs#Prefix|Unit prefix]], which they need.}} |
|- | |- | ||
| {{ConfigProperty|format|string}} | | {{ConfigProperty|format|string}} | ||
| - | | | + | | This is the main key which contains a string with all text and other keys listed above, and as result of parsing outputs the actual title. This is kind of pattern of yje title. This string may contain:: |
| - | * | + | * plain text; |
| - | * | + | * language phrases; |
| - | * | + | * information about <code>Item</code> type objects used on the page; |
| - | ** | + | ** status of object - adding or editing; |
| - | ** | + | ** value of the field set in [[K4:Unit Configs#TitleField|TitleField]]; |
| - | ** | + | ** value of any field; |
| - | * | + | * any information about <code>List</code> type objects, used on this page; |
| - | ** | + | ** record counts with filters or without them. |
| + | |||
| + | Plain text is displayed as is. Language [[K4:Phrase|Phrases]] - replaced with their translations. All language phrases must be escaped using exclamation marks <code>!</code> (eg. "<code>!la_title_OrderShipping!</code>". Other elements are escaped with a "<code>#</code>" (ie. <code>#ord.denied_recordcount#</code>). | ||
| - | |||
|- | |- | ||
| {{ConfigProperty|toolbar_buttons|array}} | | {{ConfigProperty|toolbar_buttons|array}} | ||
| - | | | + | | In this key are listed buttons names (without the module, ie. "<code>sample_button</code>", not "<code>custom:sample_button</code>") that will be used on the toolbar, and can be hidden with [[K4:Site Configs|Site Configs]] functionality. This is shown in the example below: |
| + | |||
<source lang="php"> | <source lang="php"> | ||
'toolbar_buttons' => Array ('new_item', 'edit', 'delete', 'view'), | 'toolbar_buttons' => Array ('new_item', 'edit', 'delete', 'view'), | ||
</source> | </source> | ||
| - | + | Available since [[K4:Core v 5.0.0|In-Portal v 5.0.0]]. | |
|} | |} | ||
| - | === | + | === Special Functionality of "format" Key === |
{| class="prettytable" | {| class="prettytable" | ||
| - | ! | + | ! name || description |
|- | |- | ||
| <code>#prefix[.special]_status#</code> | | <code>#prefix[.special]_status#</code> | ||
| Line 292: | Line 294: | ||
{{TipBox|Для платформы убирается код, содежащий "<code>'new_titlefield'</code>".}} | {{TipBox|Для платформы убирается код, содежащий "<code>'new_titlefield'</code>".}} | ||
| + | |||
| + | |||
| + | [[en:{{FULLPAGENAME}}]] | ||
| + | [[ru:K4:Работа с опцией TitlePresets]] | ||
| + | |||
| + | |||
| + | Translated from: [http://guide.in-portal.org/rus/index.php?title=K4:%D0%A0%D0%B0%D0%B1%D0%BE%D1%82%D0%B0_%D1%81_%D0%BE%D0%BF%D1%86%D0%B8%D0%B5%D0%B9_TitlePresets&oldid=1077 revision 1077] | ||
Revision as of 21:52, 28 November 2010
| ||
|---|---|---|
| Статьи в этой категории | ||
|
Virtually every page of the site there is an element such as a Title (title. This is the text in abbreviated form explaining what kind of information is displayed on the page. The title may just be the text, translated depending on the selected language interface, as well as information about the data displayed on the page. For example, if a page displays the пользователя data, then the title is appropriate to show Username of the user. If the page contains a list of orders, then the title can show the number of orders.
Thus, the title page can be composed of a small number of typical elements. This allows in almost all cases use a standard method for formation of the page title, and so the standard way of In-Portal is setting the header by setting the TitlePresets option in Unit Config file and then output using combined_header. This block contains [TagProcessor:SectionTitle|SectionTitle]] tag, which collects all header elements in the string and displays it in a standard, designed specifically for this site way.
Since, the SectionTitle tag is called in combined_header block with pass_params="true" parameter, then through combined_header block can be set any parameters for the SectionTitle tag, except for cut_first, which has already been set within that block.
Contents |
How to Define
'TitlePresets' => Array ( 'title_preset_name' => Array ( 'new_status_labels' => Array (), 'edit_status_labels' => Array (), 'new_titlefield' => Array (), 'prefixes' => Array (), 'tag_params' => Array (), 'format' => '', ) )
In the above example the keys of the first level displayed in summarized/brief form. There is only one "title_preset_name" title. There can be any number of titles, of course, each must have a unique key in the TitlePresets array. It's highly recommended, as a title key to pick a string related to the sense of the pages on which title will be displayed. For example:
Keys
| key name | description | ||
|---|---|---|---|
new_status_labels (array)
| In this key, each used in the title Unit prefix sets the text to indicate that a new record will be created. This text (usually a phrase if the form "!la_title_AddingOrder!") will later be inserted instead of the "#prefix_status#" code within the value of format key, but only when, a new record is created the database. This is shown in the example below.
'order_edit' => Array ( 'new_status_labels' => Array ('ord' => '!la_title_AddingOrder!'), 'prefixes' => Array ('ord'), 'format' => '#ord_status#'), ),
| ||
edit_status_labels (array)
| In this key, each used in the title Unit prefix sets the text to indicate that currently is editing a previously created record. This text (usually a phrase if the form "!la_title_EditingOrder!") will later be inserted instead of the "#prefix_status#" code within the value of format key, but only when, editing a previously existing in the database record. This is shown in the example below.
'order_edit' => Array ( 'edit_status_labels' => Array ('ord' => '!la_title_EditingOrder!'), 'prefixes' => Array ('ord'), 'format' => '#ord_status#'), ),
| ||
new_titlefield (array)
| In this key, each used in the title Unit prefix sets the text to shown instead of empty field value specified in the TitleField option. This text (usually a phrase if the form "!lla_title_NewOrder!") will later be inserted instead of the "#prefix_titlefield#" code within the value of format key, but only when, a new record is created the database. This is shown in the example below.
'order_edit' => Array ( 'new_titlefield' => Array ('ord' => '!la_title_NewOrder!'), 'prefixes' => Array ('ord'), 'format' => '#ord_titlefield#'), ),
| ||
prefixes (array)
| In this key, given a list of Unit prefixes used to display this title. Note that prefixes for Item object types these are not different are written as it is, but for Unit prefixes with List object of types is appended the word "_List". For example, this is how how prefixes for single Order record and list of archived orders should be defined if both needs to have the same title:
'prefixes' => Array ('ord', 'ord.archived_List') | ||
tag_params (array)
| This optional key can be used to set initialization parameters for each of the objects used in the title. Initialization of objects occurs at the first call from a kApplication::recallObject method. As the third parameter this method takes an array of initialization parameters "$event_params". This key is just provided to set these parameters if needed. For example, to change (override) specified by the default number of entries displayed per page on the list. For this you can use "per_page" parameter which will be used as described above:
'prefixes' => Array ('conf'), 'tag_params' => Array ( 'conf' => Array ( 'per_page' => -1 ), ),
| ||
format (string)
| This is the main key which contains a string with all text and other keys listed above, and as result of parsing outputs the actual title. This is kind of pattern of yje title. This string may contain::
Plain text is displayed as is. Language Phrases - replaced with their translations. All language phrases must be escaped using exclamation marks | ||
| In this key are listed buttons names (without the module, ie. "sample_button", not "custom:sample_button") that will be used on the toolbar, and can be hidden with Site Configs functionality. This is shown in the example below:
'toolbar_buttons' => Array ('new_item', 'edit', 'delete', 'view'), Available since In-Portal v 5.0.0. |
Special Functionality of "format" Key
| name | description |
|---|---|
#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'".
|
Translated from: revision 1077
