Структура формата — различия между версиями

Материал из Mid Office Manager Help
Перейти к: навигация, поиск
(Экранирование служебных символов)
(Внутренние форматы)
Строка 80: Строка 80:
 
<p style="text-align:justify;">
 
<p style="text-align:justify;">
 
При описании блока ключевого слова, отмечалось, что для атрибутов отвечающих за дату и число можно воспользоваться атрибутом ''pattern''. Есть еще один случай, когда этот атрибут необходим. Для начала рассмотрим объект '''''Паспорт'''''. Зададим для него формат, где будет задействован тип паспорта и его номер:
 
При описании блока ключевого слова, отмечалось, что для атрибутов отвечающих за дату и число можно воспользоваться атрибутом ''pattern''. Есть еще один случай, когда этот атрибут необходим. Для начала рассмотрим объект '''''Паспорт'''''. Зададим для него формат, где будет задействован тип паспорта и его номер:
 +
</p>
 
<pre>{id=type} - {id=number}</pre>
 
<pre>{id=type} - {id=number}</pre>
 
После применения формата итоговое представление паспорта может, например, выглядеть так:
 
После применения формата итоговое представление паспорта может, например, выглядеть так:
 
<pre>Внутренний паспорт - 1234567890</pre>
 
<pre>Внутренний паспорт - 1234567890</pre>
 +
<p style="text-align:justify;">
 
Теперь рассмотрим объект '''''Физическое лицо'''''. Для него зададим формат, где нужно отображать фамилию, имя, а также список его паспортов, указанных в скобках:
 
Теперь рассмотрим объект '''''Физическое лицо'''''. Для него зададим формат, где нужно отображать фамилию, имя, а также список его паспортов, указанных в скобках:
 +
</p>
 
<pre>{id=last_name} - {id=first_name} ({id=passports})</pre>
 
<pre>{id=last_name} - {id=first_name} ({id=passports})</pre>
 +
<p style="text-align:justify;">
 
Очевидно, что паспорт является комплексным объектом, и в свою очередь может состоять из нескольких составляющих. Возникает желание каким-то образом указать формат и для самого паспорта. В таких случаях, можно также задействовать атрибут ''pattern''. В этом примере воспользуемся форматом паспорта из примера выше и укажем его в качестве значения атрибута ''pattern'':
 
Очевидно, что паспорт является комплексным объектом, и в свою очередь может состоять из нескольких составляющих. Возникает желание каким-то образом указать формат и для самого паспорта. В таких случаях, можно также задействовать атрибут ''pattern''. В этом примере воспользуемся форматом паспорта из примера выше и укажем его в качестве значения атрибута ''pattern'':
 +
</p>
 
<pre>{id=last_name} - {id=first_name} ({id=passports|pattern={id=type} - {id=number}})</pre>
 
<pre>{id=last_name} - {id=first_name} ({id=passports|pattern={id=type} - {id=number}})</pre>
 +
<p style="text-align:justify;">
 
В случае, если у форматируемого физического лица есть два паспорта, то результат применения формата может выглядеть так:
 
В случае, если у форматируемого физического лица есть два паспорта, то результат применения формата может выглядеть так:
 
<pre>Иванов Иван (Внутренний паспорт - 1234567890, Загранпаспорт - 701234560)</pre>
 
<pre>Иванов Иван (Внутренний паспорт - 1234567890, Загранпаспорт - 701234560)</pre>
 
</p>
 
</p>
 +
 
==Ключевые слова==
 
==Ключевые слова==
 
<p style="text-align:justify;">
 
<p style="text-align:justify;">

Версия 17:51, 13 августа 2018


Содержание


Требования

Для прочтения данной статьи ознакомление с другими документами не требуется

Введение

В Mid Office Manager в различных документах содержится информация о других объектах в программе. Например, документы могут содержать данные о продуктах, сборах или реализациях. Информация об этих объектах должна иметь определенный вид. При этом требования к виду отображаемых данных различается от агентства к агентству. Для управления форматом данных была разработана система, позволяющая назначать произвольный формат для создания строкового представления объекта. Система может быть использована для построения описания объекта, формирования его номера и т.д. На данный момент система форматов имеет ограниченное применение, но со временем использование этой системы будет расширяться.

Формат

Формат представляет собой некий строковый шаблон по которому будет сформирован итоговый результат. Результатом применения формата также будет строка. Она будет отражать представление объекта в соответствии с заданным шаблоном, в котором все указанные ключевые слова будут преобразованы в значения. Например, если в шаблоне наименования документа указано ключевое слово для его даты, то оно будет заменено на дату документа.

Строка формата состоит из набора блоков. Блоки бывают трех типов: простой, ключевое слово и опциональный. Каждый блок имеет свою структуру. Рассмотрим каждый блок в отдельности.

  1. Простой - в полном соответствии своему названию, является самым простым блоком. Он используется для указания статичных частей формата. Например, если нужно в формате использовать набор символов, который будет всегда присутствовать в итоговом результате.
    Представим, что требуется задать формат для наименования объекта Финансовый документ с типом Счет, в котором оно будет состоять просто из слова Счет. Строка формата при этом будет выглядеть так:
    Счет
    Для простого блока не требуется каким-либо образом выделять свою структуру. Статичные символы просто вносятся в формат как есть.
  2. Ключевое слово - является блоком, в котором ключевое слово, при применении формата, будет заменено на определенное значение. Этот блок имеет следующую структуру:
    {<наименование_атрибута>=<значение_атрибута>}
    Как видно, блок начинается с символа { (открывающая фигурная скобка) и заканчивается символом } (закрывающая фигурная скобка). Внутри блока расположены атрибуты. При задании атрибута необходимо внести его наименование, затем символ = (равно), после чего указать значение атрибута. Блок ключевого слова поддерживает несколько атрибутов:

    * id - наименование ключевого слова
    * default - значение по умолчанию, используемое в случае, если вычисленное значение пустое
    * separator - используется для указания разделителя значений, в случае если ключевое слово отвечает за коллекцию значений
    * pattern - шаблон, для форматирования вычисленного значения, например, если ключевое слово отвечает за дату или число

    Из всех указанных атрибутов, обязательным к указанию является лишь атрибут id. Остальные атрибуты являются опциональными. Если в блоке нужно указать несколько атрибутов, они должны быть отделены друг от друга символом | (вертикальная черта). При этом, последовательность, в которой выстраиваются атрибуты, не имеет значения. Предположим, что нужно задать формат наименования для счета, содержащего его номер. Формат, при этом, будет выглядеть так:
    {id=number}
    Вернемся к примеру из описания простого блока. После слова Счет требуется указать его номер, а в случае если номер отсутствует, вместо номера нужно подставить значение без номера. Формат примет следующий вид:
    Счет {id=number|default=без номера}
    Усложним пример, добавив требование, чтобы в конце была подставлена еще и дата счета, отделенная от номера символом - (тире):
    Счет {id=number|default=без номера} - {id=date}
    Возникает вопрос: в каком виде дата будут отображена в итоговой строке? Как упоминалось ранее, для дат и чисел можно задать атрибут pattern, который как раз и позволяет задать шаблон для их отображения. Воспользуемся этим атрибутом:
    Счет {id=number|default=без номера} - {id=date|pattern=yyyy.MM.dd}
    В этом примере было определено, что дата будет отображаться в виде четырех цифр года и двух цифр для месяца и дня, отделенные между собой символом . (точка). Итоговый результат может выглядеть, например, так:
    Счет 00000123 - 2018.05.17
  3. Опциональный - специальный блок, который в случае пустого значения будет исключен из итоговой строки. Его полезно использовать, когда в формат нужно включить определенные данные, отсутствие которых у форматируемого объекта является допустимым. Этот блок имеет структуру, схожую со структурой предыдущего блока:
    [<наименование_атрибута>=<значение_атрибута>]
    Блок начинается с символа [ (открывающая квадратная скобка) и заканчивается символом ] (закрывающая квадратная скобка). Внутри блока расположены атрибуты, имеющие идентичный формат. Опциональный блок поддерживает следующие атрибуты:

    * value - значение
    * padding - набор статичных символов, подставляемых перед значением
    * prefix - набор статичных символов, подставляемых перед значением, аналог padding
    * suffix - набор статичных символов, подставляемых после значения

    В указанном наборе атрибутов обязательным является только атрибут value. В качестве его значения можно указывать любой набор блоков. Например, можно использовать блок ключевое слово. Снова вернемся к прошлому примеру. Последняя версия формата выглядела так:
    Счет {id=number|default=без номера} - {id=date|pattern=yyyy.MM.dd}
    Посмотрим как будет выглядеть итоговая строка в случае, если дата у счета не задана:
    Счет 00000123 - 
    В силу того, что даты в документе нет, ее значение в итоговую строку подставлено не будет. Однако символ - (тире) отделяющий дату от номера останется, т.к. он задан как статичный. Хочется этого избежать. Исправим формат и внесем в него опциональный блок:
    Счет {id=number|default=без номера}[padding= - |value={id=date|pattern=yyyy.MM.dd}]
    Как видно, символ - (тире) был внесен в качестве значения padding, а блок ключевого слова был полностью перенесен в значение атрибута value. Теперь, в случае, если дата в документе есть, вычисленное значение атрибута value будет не пустым, следовательно опциональный блок будет использован. Итоговое значение, при этом, будет выглядеть так:
    Счет 00000123 - 2018.05.17
    Если же дата в документе отсутствует, то значение value будет пустым и опциональный блок будет полностью исключен из формата. В итоге получится строка:
    Счет 00000123
    В силу того, что символ - (тире) теперь является частью опционального блока, этот символ не будет добавлен в итоговую строку.

Экранирование служебных символов

В описанных выше блоках используется строгая структура. При этом, для описания структуры используются различные служебные символы такие как { (открывающая фигурная скобка), } (закрывающая фигурная скобка), | (вертикальная черта) и т.д. Порой бывает нужным использовать эти символы в формате не как служебные, а как обычные символы. Например, внутри блока с ключевым словом требуется задать шаблон для даты с использованием символа вертикальной черты:

{id=date|pattern=yyyy|MM|dd}

Система формата при разборе блока на составляющие разобьет его на четыре части, и выдаст ошибку о том, что структура блока нарушена. Она воспримет части MM и dd как отдельные атрибуты, которые не соответствуют ожидаемому формату, т.к. после наименования атрибута должен следовать символ = (равно) и его значение. Чтобы исправить ситуацию, нужно пометить символы | (вертикальная черта) в значении pattern как обычные символы. Для выделения последовательности обычных символов используется символ ' (одинарная кавычка). Все что будет находиться между этим символами будет интерпретировано системой не как служебные символы, а как обычные. Внесем исправления в формат:

{id=date|pattern=yyyy'|'MM'|'dd}

Теперь структура блока будет считаться корректной. В случае, если нужно в качестве обычного символа указать сам символ ' (одинарная кавычка), нужно внести его два раз подряд.

Внутренние форматы

При описании блока ключевого слова, отмечалось, что для атрибутов отвечающих за дату и число можно воспользоваться атрибутом pattern. Есть еще один случай, когда этот атрибут необходим. Для начала рассмотрим объект Паспорт. Зададим для него формат, где будет задействован тип паспорта и его номер:

{id=type} - {id=number}

После применения формата итоговое представление паспорта может, например, выглядеть так:

Внутренний паспорт - 1234567890

Теперь рассмотрим объект Физическое лицо. Для него зададим формат, где нужно отображать фамилию, имя, а также список его паспортов, указанных в скобках:

{id=last_name} - {id=first_name} ({id=passports})

Очевидно, что паспорт является комплексным объектом, и в свою очередь может состоять из нескольких составляющих. Возникает желание каким-то образом указать формат и для самого паспорта. В таких случаях, можно также задействовать атрибут pattern. В этом примере воспользуемся форматом паспорта из примера выше и укажем его в качестве значения атрибута pattern:

{id=last_name} - {id=first_name} ({id=passports|pattern={id=type} - {id=number}})

В случае, если у форматируемого физического лица есть два паспорта, то результат применения формата может выглядеть так:

Иванов Иван (Внутренний паспорт - 1234567890, Загранпаспорт - 701234560)

Ключевые слова

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

Реализация

Ключевое слово Описание
date Дата реализации
number Номер реализации
number_generate Специальное ключевое слово обеспечивающее генерацию следующего номера
category Категория реализации


Финансовый документ

Ключевое слово Описание
date Дата финансового документа
number Номер финансового документа
number_generate Специальное ключевое слово обеспечивающее генерацию следующего номера


Платежный документ

Ключевое слово Описание
date Дата платежного документа
number Номер платежного документа
number_generate Специальное ключевое слово обеспечивающее генерацию следующего номера


Физическое лицо

Ключевое слово Описание
last_name Фамилия физического лица
first_name Имя физического лица
second_name Второе имя физического лица
middle_name Отчество физического лица
passports Список паспортов физического лица


Паспорт

Ключевое слово Описание
type Тип паспорта
number Номер паспорта
issued Дата выдачи паспорта
last_name Фамилия, указанная в паспорте
first_name Имя, указанное в паспорте
second_name Второе имя, указанное в паспорте
middle_name Отчество, указанное в паспорте

Личные инструменты
Пространства имён

Варианты
Действия
Навигация
Печать/экспорт
Инструменты