10. Структура формата (шаблон наименования)

Введение

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

Формат

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

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

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

Для простого блока не требуется каким-либо образом выделять свою структуру. Статичные символы просто вносятся в формат как есть.

2. Ключевое слово - является блоком, в котором указанное ключевое слово, при применении формата, будет заменено на определенное значение. Этот блок имеет следующую структуру:

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

• id - наименование ключевого слова

• default - значение по умолчанию, используемое в случае, если вычисленное значение пустое

• separator - используется для указания разделителя значений, в случае если ключевое слово отвечает за коллекцию значений

• pattern - шаблон, для форматирования вычисленного значения, например, если ключевое слово отвечает за дату или число

• locale - используется для указания языка, на котором отображать локализуемое значение

Из всех указанных атрибутов, обязательным к указанию является лишь атрибут id. Остальные атрибуты являются опциональными. В качестве значения, указываемого для атрибута default можно использовать любой набор блоков. Если в блоке нужно указать несколько атрибутов, они должны быть отделены друг от друга символом | (вертикальная черта). При этом, последовательность, в которой выстраиваются атрибуты, не имеет значения. Предположим, что нужно задать формат наименования для продукта, содержащего его номер. Формат, при этом, будет выглядеть так:

Как видно из примера, значение для атрибута id указывается в виде двух элементов, соединенных символом : (двоеточие):

Элемент объект определяет, какому объекту принадлежит свойство, которое необходимо отобразить, а элемент свойство определяется какое именно свойство этого объекта нужно отобразить. В примере выше, указано, что нужно отобразить свойство number, принадлежащее объекту product (список всех объектов и их свойств приведен в конце документа).

Вернемся к примеру из описания простого блока. После слова Авиабилет требуется указать его номер, а в случае, если номер отсутствует, вместо номера нужно подставить значение без номера. Формат примет следующий вид:

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

А в случае, если у билета номера нет, то вместо номера будет подставлено указанное значение по умолчанию:

Чтобы не загромождать шаблон, уберем из него атрибут default и немного усложним пример, добавив новое требование: в конце строки должна быть подставлена дата вылета, отделенная от номера символом - (тире):

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

В этом примере, было определено что дата будет отображаться в виде четырех цифр года и двух цифр для месяца и дня, отделенные между собой символом . (точка). Итоговый результат может выглядеть, например, так:

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

При этом, если атрибут locale указать у элемента, значение которого является не локализуемым, то такое значение будет транслитерировано с кириллицы на латиницу в соответствии с ГОСТ Р 52535.1-2006.  

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

Блок начинается с символа [ (открывающая квадратная скобка) и заканчивается символом ] (закрывающая квадратная скобка). Внутри блока расположены атрибуты, имеющие идентичный формат. Опциональный блок поддерживает следующие атрибуты:

• value - значение

• padding - набор статичных символов, подставляемых перед значением, но только в случае, если это не первая запись в строке

• prefix - набор статичных символов, подставляемых перед значением

• suffix - набор статичных символов, подставляемых после значения

В указанном наборе атрибутов обязательным является только атрибут value. В качестве его значения можно указывать любой набор блоков. Например, можно использовать блок ключевое слово. Снова вернемся к прошлому примеру. Последняя версия формата выглядела так:

Посмотрим, как будет выглядеть итоговая строка в случае, если дата вылета у авиабилета не задана:

Авиабилет 1234567890 -

В силу того, что даты вылета в авиабилете нет, ее значение в итоговую строку подставлено не будет. Однако символ - (тире), отделяющий дату от номера останется, т.к. он задан как статичный. Хочется этого избежать. Исправим формат и внесем в него опциональный блок:

Авиабилет {id=product:number}[padding= - |value={id=product:start_date|pattern=yyyy.MM.dd}]

Как видно, символ - (тире) был внесен в качестве значения padding, а блок ключевого слова был полностью перенесен в значение атрибута value. Теперь, в случае если дата в билете есть, вычисленное значение атрибута value будет не пустым, следовательно опциональный блок будет использован. Итоговое значение, при этом, будет выглядеть так:

Авиабилет 1234567890 - 2018.05.17

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

Авиабилет 1234567890

В силу того, что символ - (тире) теперь является частью опционального блока, этот символ не будет добавлен в итоговую строку.

4. Условный блок - предназначен для вывода разных результатов, которые зависят от вычисленного значения. Работа данного блока заключается в том, что сначала вычисляется значение, а затем проверяется набор указанных ожидаемых результатов для этого значения. В случае, если вычисленное значение совпадает с одним из указанных результатов, тогда в итоговую строку будет выведено значение, назначенное этому результату. Этот блок имеет структуру, схожую со структурой предыдущих блоков:

<<наименование_атрибута>=<значение_атрибута>>

Блок начинается с символа < (открывающая угловая скобка) и заканчивается символом > (закрывающая угловая скобка). Внутри блока расположены атрибуты, имеющие идентичный формат. Опциональный блок поддерживает следующие атрибуты:

• value - значение

• default - значение по умолчанию, используемое в случае, если значение не совпало ни с одним из ожидаемых результатов.

В указанном наборе атрибутов обязательным является только атрибут value. В качестве его значения можно указывать любой набор блоков. Помимо указанных атрибутов, можно задавать атрибуты ожидаемых результатов.

Рассмотрим снова пример из описания простого блока. После слова Авиабилет требуется указать слово электронный или бумажный в зависимости от того, является ли билет электронным или нет. У продукта нет ключевого слова тип билета, однако есть ключевое слово с признаком электронный билет. При вычислении значения этого признака можно получить два результата: true – в случае электронного билета и false – в случае если билет не электронный. Воспользуемся этим признаком и условным блоком для построения формата:

Авиабилет <value=product:eticket|true=электронный|false=бумажный>

Как видно в формате были перечислены варианты для всех ожидаемые результатов. В случае если вычисленное значение будет равно true, в итоговую строку будет подставлено слово электронный, при значении равном false – будет подставлено слово бумажный.

Совсем не обязательно указывать все варианты ожидаемых результатов. Если в наборе атрибутов не будет найден ожидаемый результат равный вычисленному значению, будет использовано значение из атрибута default. А если атрибут default не указан, то блок будет попросту проигнорирован.

По аналогии с атрибутом value в качестве значений, указываемых в атрибутах для ожидаемых результатов, а также для атрибута default можно использовать любой набор блоков.

И еще одно важно замечание: в качестве самого ожидаемого результата можно применять регулярные выражения.

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

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

{id=product:start_date|pattern=yyyy|MM|dd}

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

{id=product:start_date|pattern=yyyy'|'MM'|'dd}

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

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

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

{id=passport:type} - {id=passport:number}

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

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

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

{id=person:last_name} {id=person:first_name} ({id=person:passports})

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

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

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

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

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

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

Элемент реализации (billing_item)

Заказ (booking_file)

Бронирование (reservation)

Продукт (product)

Путешественник (traveller)

Паспорт (passport)

Организация (organization)

Физическое лицо (person)

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

Договор (contract)

Реализация (shipment)

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

Позиция в чеке (receipt_line)

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

Так, например, для указания номера договора в шаблоне заголовка финансового документа воспользуемся форматом:

{id=finance_document:contract|pattern={id=contract:number}}

В данном формате ключевое слово finance_document будем считать внешним, а contract — внутренним.

В таблице ниже указаны типы ключевых слов и их применение

Таблица применимости ключевых слов объекта Product к продуктам MOM