Термины

Конфигурация TN-объекта

TN-объект конфигурируется с типом объекта TUNABLE_OBJECT.

Обработка операций чтения и редактирования TN-объекта

Для обработки TN-объекта в CMJ используется классы

1. на уровне коннектора TunableObjectConnector;
2. на уровне доменного слоя TunableObjectImpl;
3. на уровне rest-слоя TunableObjectREST.

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

• StrategyGet, 
• StrategySave,
• StrategyCreateDraft,
• StrategyAfterSave,
• StrategyGetByCreate,
• StrategyRESTGet,
• StrategyRESTUpdate.

Стратегии работают каждый со своей схемой TN-объекта.
Интерфейс TN-объекта AnyTunableObject содержит методы setEntity(), entity() для установки и считывания объекта в прикладном интерфейсе. Метод setEntity необязателен при обработке.

Конфигурация меню действий TN-объекта, коллекции TN-объектов

Структура меню передается в едином формате Формы как для прикладного объекта, так и для коллекции. Элементы меню передаются в секции с идентификатором "RootMenu".
Действия задаются через Кнопки в секции "RootMenu". Для задания вложенности действия меню используются вложенные секции.

Конфигурация меню действий в TN-объекте

В форме НР-объекта задается секция с идентификатором "RootMenu".

Конфигурация меню действий в коллекции

Для коллекции вводится схема.  Схема задается в настройке дескриптора. Задача схемы - передача меню действий коллекции через форму. Таким образом, в форме схемы коллекции может быть только одна секция. Это секция с идентификатором "RootMenu". Когда для заполнения TN-карты меню коллекции требуется хардкод, то предлагается разработать класс-стратегию StrategyRESTGet (см. пример GetSOPersonCollectionRESTStrategy).

Правила конфигурации действий в секции "RootMenu"

В секции "RootMenu" можно задать действие. Через создание системного действия в  секции "RootMenu" можно переопределять некоторые визуальные параметры данного системного действия. Например, переопределить видимость, иконку, порядок следования. Для переопределения системного действия необходимо создать кнопку с аналогичным идентификатором в секции "RootMenu". Для переопределения порядка следования используется тег position. Идентификаторы системных действий, а также правила нумерации действий см. в  в таблице Таблица общесистемных действий меню.

Обработка основных клиентских операций с TN-объектом

Для конфигурации клиентской операции с TN-объектом используется кнопки создание, сохранение, открытие TN-объектов

Создание корневого TN-объекта

В теге create указывается схема нового объекта и тип БД + комплект.

В простом случае, когда нужно просто показать форму для ввода реквизитов нового TN-объекта, одной настройки достаточно.

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

Создание подчиненного TN-объекта

В теге create-child указывается схема нового объекта.

В схеме подчиненного TN-объекта должно быть предусмотрено свойство $parentunid с типом String.  При формировании черновика подчиненного TN-объекта система положит в это поле идентификатор родителя, чтобы при сохранении сделать его ответным к родительскому TN-объекту.

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

В иных случаях, когда нужно самостоятельно сформировать черновик, например, с предварительным набором диалогов или  информационных сообщений, требуется разработать класс-стратегию  StrategyCreateDraft. В этом случае установку значения в  $parentunid дочернего объекта следует выполнять в классе-стратегии самостоятельно при передаче ресурса черновика в результат. Идентификатор родителя в классе-стратегии можно получить из объекта params через data.resourceid

Создание sibling-объекта

Операция создания объекта в  той же БД,что и выделенный объект,  и на том же уровне иерархии, если выделенный объект - дочерний.

В теге create-sibling указывается схема нового объекта.

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

Когда нужен, например, набор диалогов или  информационных сообщений, требуется разработать класс-стратегию  StrategyCreateDraft. Идентификатор контекстного объекта в классе-стратегия можно получить из объекта params через data.resourceid

Создание копии (новый как копия)

В теге create-copy указывается схема нового объекта.

Cледует определить форму с mode=copy, как и ранее при настройке полей копирования.

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

Когда нужен, например, набор диалогов или  информационных сообщений требуется разработать  класс-стратегию  StrategyCreateDraft. Идентификатор контекстного объекта в классе-стратегия можно получить из объекта params через data.resourceid

Модификация (без сохранения) подобъекта через диалог

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

В теге change-subobject указывается схема диалога. В ресурсе диалога должно быть свойство mode с типом String и значением "dialog".  Для передачи подмножества полей из объекта в диалог и обратно в схеме диалога должно быть задано это же подмножество полей. Например, для свойства control.date из объекта должно быть такое же свойство в схеме диалога - control.date.  

Как работает сценарий:

1.  В соответствии с мэппингом полей клиент копирует значение полей из контекстного ресурса в ресурс диалога.
2.  При наличии среди измененных полей ресурса параметров recalc-полей, выполняется recalc для ресурса диалога.
3.  При нажатии на кнопку submit диалога выполняется обратный мэппинг данных из ресурса диалога в контекстный ресурс.
4.  При наличии среди измененных полей контекстного ресурса recalc-полей, выполняется recalc для контекстного ресурса.Поскольку результатом мэппинга полей является изменение нескольких полей, то клиент может передать в recalc несколько измененных полей.

Кнопка "Сохранить"

Для TN-объекта конфигурируется два действия сохранения: Сохранение нового объекта (тег save), Сохранение существующего объекта (тег save-existing). При конфигурации данных действий следует правильно установить условие применения. Действие "Сохранение нового объекта" (тег save) может быть доступно только в новом еще несохраненном объекте. Действие "Сохранение существующего объекта" (тег save-existing) может быть доступно только в сохраненному объекте. Оба действия не должны быть доступны в режиме чтения.

Создается тег save или save-existing. Задается соответствующее условие применения.

В rest-ресурсе объекта должна быть предусмотрена ссылка с rel=edit. Объект ссылки должен быть сформирован через  TunableObjectREST.Reference.

Кнопка "Редактировать"

Данное действие может быть сконфигурировано для: 1) TN-объекта в режиме чтения,  2) для выделенного в коллекции документа.

Создается тег open-edit. Задается соответствующее условие применения.

Для случая конфигурации кнопки на форме открытого объекта: В простом случае, когда на форме TN-объекта не нужно задавать сложное УП на кнопку "Редактировать" не обязательно создавать данное действие.  Кнопка "Редактировать" является системной и подгружается в меню на основании наличия ссылки с rel=edit. Но, если в меню (секции RootMenu) решили задать данное действие, то системную кнопку "Редактировать" следует скрыть, иначе на форме появятся две кнопки Редактировать.

Для случая, когда нужно по кнопке открыть документ в режиме редактирования из коллекции, настройка в секции RootMenu обязательна.

Обработка произвольной бизнес-операции над TN-объектом

Для данной операции на сервере предусмотрен обработчик, имплементирующий интерфейс TunableOperation.

В теге operation указывается название вызываемого обработчика операций:

1. Описание интерфейса TunableOperation. Интерфейс TunableOperation содержит два метода: TunableObjectREST.Resource process(); TunableObjectREST.Resource process(TunableObjectREST.Resource paramsResource);
   Метод process() вызывается при первой итерации обработки сценария, когда нужно запросить клиентский контекст (передать серверу id выделенного документа, например) или поднять диалог или и то, и другое вместе. Про передачу клиентского контекста см. Передача параметров с клиента на сервер. Для поднятия диалога метод process() должен вернуть ресурс диалога, в котором свойство mode = dialog. Диалог можно передать и через метод  process(TunableObjectREST.Resource paramsResource).
2. Вторая и последующие итерации обработки операции будут вызывать метод  process(TunableObjectREST.Resource paramsResource).  В зависимости от ответа сервера предыдущей итерации параметр paramsResource  может содержать ресурс диалога, ids выбранных документов, контекстный ресурс. В случае, когда после выполнения операции нужно выполнить закрытие контекстного объекта, требуется вернуть пустой ответ.
3. В первой итерации (обработчик Get) запрещено производить модификацию состояний объектов на сервере.
   Изменения в систему вносятся серверным обработчиком сценария только на одном из его этапов (в одном из последовательности POST-запросов). Обоснование: клиент/пользователь в любой момент может отказаться от продолжения сценария, или даже "забыть" про него, поэтому целостное выполнение всего сценария ничем не гарантируется. Но исключения возможны, если логика сценария допускает частичное его выполнение.

Добавление  диалогов или информационных сообщений при сохранении TN-объекта

1. Если в сценарии сохранения объекта требуется добавить диалог(и), то нужно разработать класс-стратегию StrategyRESTUpdate.

2. В стратегии в result нужно передать ресурс диалога  через метод setDialog. В этом случае клиент отобразит диалог и сохранения объекта не произойдет. 

3. Схема диалога должна наследовать со схемы DialogForSave.

4. При нажатии на кнопку submit диалога клиент повторно отправляет запрос на сохранение объекта. В этом случае в метод стратегии внутри ресурса сохраняемого объекта в элементе $clientContext придет ресурс диалога с клиента с введенными пользователем данными.

5. В схеме сохраняемого объекта должно быть предусмотрено свойство с фиксированным  именем  $clientContext (см. пример схема SOEmployee). Схема $clientContext соответствовать структуре ClientContext (см. Передача параметров с клиента на сервер) в части задания элемента data.resource. Схема диалога  задается в data.resource.

6. Каждый раз по кнопке submit диалога клиент будет возвращать внутри ресурса сохраняемого объекта в элементе $clientContext структуру, в поле data.resource которой будет ресурс диалога с клиента. 

7. Далее при повторных попытках сохранить объект из  диалога по кнопке submit,  в ресурс диалога можно передавать порядковый номер диалога (если диалогов более одного) для последующей обработки в стратегии. 

8. Если в диалог не передать кнопку submit, то пользователь не сможет вызвать операцию сохранения повторно. По кнопке cancel диалог закрывается.
   См. пример в объекте "Справочник должностей". Схема PositionClassifier. В схеме PositionClassifier свойство. $clientContext. Через св. $clientContext идет обмен ресурсом диалога между клиентом и сервером при сохранении. См. обработчик сохранения UpdateBeforePositionClassifierRESTStrategy.

Правило разработки класса-стратегии  получения черновика объекта

1. Для разработки класса-стратегии получения черновика используется интерфейс StrategyCreateDraft .
2. Метод класса-стратегия должен вернуть в объект события результат CreateFormActionResult запроса на получение черновика объекта. Это может быть сам черновик или  ресурс диалога.  
3. Схема  диалога должна удовлетворять одному из требований:
   
   1. Схема диалога должна наследовать со схемы Dialog.
   2. В ресурсе диалога должен быть реквизит  mode со значением «dialog». В схеме диалога должен быть предусмотрен реквизит mode с типом String.
4. Данные диалога передаются с клиента на сервер по кнопке submit (см. Термины). Ресурс диалога приходит в параметре params объекта события TunableObjectCreateDraftEvent (см. Передача клиентского контекста).  Таким образом, можно добавить интерактив из нескольких диалогов в клиентский сценарий получения черновика объекта.
5. По кнопке cancel диалога сценарий получения черновика прекращается.

Конфигурация коллекций

Коллекции TN-объектов конфигурируются так же, как и для других объектов. Единственное отличие - это передача в self идентификатора в формате TN_UNID.