Настройка редакторов и источников объектов

Редактор собирает значения полей и отправляет запрос для объекта, Link или метода. Редактор описывают внутри действия или варианта панели для редактирования; самостоятельным вариантом панели он не является.

Сначала определите, что именно изменяется и откуда берётся каждый объект, который участвует в операции. Затем выберите режим отображения и поля. Такой порядок не даёт внешне готовой форме отправить GUID не того объекта или не того Link.

Что изменяет редактор

Задача	entityType или переопределение	Что нужно указать
Создать или изменить объект	entityType.object.metaTypeName	Метатип и поля
Создать Link	entityType.link	source, target и обычно linkName
Создать объект и связать его через Link	И object, и link	Один из концов Link обычно задаётся через getFromCreatedObject
Запустить метаметод	runMethod	parent, method, при необходимости объекты и параметры

runMethod перенаправляет отправку формы в /MetaMethods/Run; это не дополнительный обработчик после сохранения. Сценарий запуска метода объединяет объекты и параметры из конфигурации со значениями формы.

Режимы отображения

Режим	Поведение	Когда использовать
modal	Открывает диалог и ждёт ввода пользователя	Обычное создание и редактирование
panel	Использует область редактирования, которой управляет панель	Вариант панели, в который встроен редактор, явно поддерживает этот режим
direct-request	Отправляет запрос без формы. create сначала применяет значения по умолчанию из редактора; http без модального редактора не передаёт значения полей редактора. Редактор runMethod учитывает режим только при создании узла BPMN и тогда не передаёт значения по умолчанию	Все обязательные значения и источники объектов известны заранее

В текущих сценариях действий на практике используется modal, но контракт EditorType требует явно указать mode. Не используйте direct-request, если пользователь должен выбрать объект для источника или ввести значение.

Поля, вкладки и строки

Задайте либо fields на верхнем уровне, либо tabs. Каждой вкладке нужны постоянный id, локализованный title и собственные поля. Группа { "layout": "row", "fields": [...] } выводит компактные элементы управления рядом, в одну строку.

Каждое конечное поле, то есть поле, которое не является группой, должно содержать attribute. Основные свойства поля:

• editAttribute задаёт путь для отправки значения, если он отличается от отображаемого attribute;
• readonly показывает значение, но не даёт его изменить;
• hidden исключает поле из отображения и общей проверки;
• явно заданные type, label, listOfValue, comment, regEx и defaultValue имеют приоритет над метаданными с сервера;
• propertyAsId и selectPanel настраивают выбор объекта;
• control: "scratchFile" в редакторе действия с method: "runMethod" заменяет поле ввода выбором файла. Когда пользователь отправляет форму, панель загружает выбранный файл как временный файл и передаёт методу его токен; подробнее — в разделе Файл для метода. Полю нужен явный "type": "String", а defaultValue у него не задают. Всё остальное — ошибка конфигурации: scratchFile в другом редакторе, в том числе в editor.runMethod действия create, который тоже запускает метод; любое другое значение control, в том числе пустое; scratchFile без "type": "String" или с defaultValue. Тогда вместо поля ввода показана ошибка, и действие не выполняется, пока настройку не исправят. Скрытые поля и поля на других вкладках тоже проверяются: их ошибки появляются в уведомлении, когда пользователь отправляет форму. Действие, которое выполняется без формы, — create с editor.mode: "direct-request", http без своего модального редактора или runMethod, запущенный из attributes.panelActions либо при создании узла BPMN без формы или его удалении, — не может заполнить поле с control, поэтому такое поле останавливает действие с таким же уведомлением.

Подробнее о приоритете метаданных и типизированных элементах управления.

Откуда берутся объекты

LinkEndpoint описывает, откуда взять объект, например для source или target Link. В момент выполнения действия приложение определяет по каждому LinkEndpoint один селектор объекта.

Источник	Откуда берётся объект	Типичное применение
objectId	Фиксированный ObjectSelector	Заранее известный объект из конфигурации
getFromItem	Текущий элемент Table или Tree	Действие строки
getFromCreatedObject	Объект, созданный ранее в том же сценарии	Создать объект, затем связать его
getSelectedObjectForPanelId	Последний выбор в указанной панели	Действие с участием другой панели, если её ID не меняется
getSelectedObjectForEventId	Выбор, сохранённый в реестре событий	Зависимый запрос или редактор
getFromActionId	Контекст результата действия	Цепочка действий
selectPanel	Выбор пользователя во встроенной модальной панели	Объект нельзя определить заранее

Для селектора, полученного через Link, idSource определяет, какой GUID использовать:

• не указан или "linkedObject" — GUID целевого объекта;
• "link" — GUID самого Link.

Указывайте "link", чтобы удалить или изменить сам Link. Значение по умолчанию подходит для создания, чтения, изменения и удаления объекта и для методов, которые принимают связанный объект.

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

Минимальный редактор объекта

{
  "mode": "modal",
  "entityType": {
    "object": { "metaTypeName": "ProductionOrder" }
  },
  "fields": [
    { "attribute": "name", "label": "Name" }
  ]
}

Метатип ProductionOrder должен существовать. Форма использует метаданные этого типа, если их возвращает API метаданных.

Создание объекта и связь с выбранным элементом

Используйте этот редактор в действии строки родительского объекта. Новая операция становится источником Link, а заказ, в строке которого запущено действие, — его целью.

{
  "mode": "modal",
  "header": {
    "title": { "en": "Create operation", "ru": "Создать операцию" },
    "propertyAsId": "code"
  },
  "entityType": {
    "object": {
      "metaTypeName": "Operation"
    },
    "link": {
      "linkName": "OrderOperation",
      "source": { "getFromCreatedObject": true },
      "target": { "getFromItem": true }
    }
  },
  "fields": [
    {
      "attribute": "code",
      "type": "String",
      "label": { "en": "Code", "ru": "Код" },
      "regEx": "^OP-[0-9]+$"
    },
    {
      "attribute": "duration",
      "type": "Integer",
      "label": { "en": "Duration, min", "ru": "Длительность, мин" }
    },
    {
      "attribute": "link.sequence",
      "type": "Integer",
      "label": { "en": "Sequence", "ru": "Порядок" }
    }
  ]
}

link.sequence относится к метаданным и телу запроса Link, остальные поля — к новому объекту.

Выбор цели через панель

{
  "entityType": {
    "link": {
      "linkName": "OrderProduct",
      "source": { "getFromItem": true },
      "target": {
        "selectPanel": {
          "label": { "en": "Choose product", "ru": "Выберите изделие" },
          "width": "48rem",
          "height": "28rem",
          "panel": {
            "id": "product-picker",
            "type": "table",
            "request": { "metaTypeName": "Product" },
            "pagination": { "rowsPerPage": [10] },
            "columns": [
              { "attribute": "code", "label": "Code" },
              { "attribute": "name", "label": "Name" }
            ]
          }
        }
      }
    }
  }
}

Панели выбора нужны полный запрос и вариант, который поддерживает выбор. Её ID не должен совпадать с ID в приложении, внутри которого она открывается.

Редактор для запуска метода

{
  "mode": "modal",
  "runMethod": {
    "parent": "ProductionOrder",
    "method": "release",
    "objects": [
      { "getSelectedObjectForEventId": "order-selected" }
    ],
    "params": {
      "source": "configurator"
    }
  },
  "fields": [
    {
      "attribute": "comment",
      "type": "Text",
      "label": "Release comment"
    }
  ]
}

Фактический контракт объектов и параметров задаёт сам метаметод. JSON-конфигурация не проверяет ни имя метода, ни передаваемые ему данные.

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

Значения по умолчанию, приоритет и отправка

1. Действие или вариант панели передаёт текущий элемент, выбор и ID действия.
2. Редактор определяет объекты по источникам объекта и Link для этого потребителя.
3. Для существующего объекта приложение запрашивает его детальные данные по путям из attribute. Путь editAttribute тоже попадает в запрос, если это не та агрегация, через которую attribute читает значение: при attribute: "uom|designatorNational" и editAttribute: "uom" запрос перечисляет только uom|designatorNational.
4. Явно заданные в поле метаданные имеют приоритет над метаданными атрибута, полученными от API.
5. Значения, полученные от API, имеют приоритет над значениями по умолчанию: значения по умолчанию заполняют только поля, значение которых не определено.
6. Общая проверка применяет regEx и проверяет JSON, после чего потребитель отправляет запрос.
7. Последующие действия по ответу или действия перезагрузки обновляют зависимые области интерфейса.

Для обычных данных пустые значения Guid и Object при отправке заменяются на null. Это правило действует только на границе отправки; общего правила «все пустые строки становятся null» нет.

Ограничения и текущие расхождения

• Общая проверка не применяет required.
• Поддержка режимов редактора зависит от потребителя: объявление в типе не означает, что каждое действие отображает режим panel.
• withLinkedAttribute объявлен для entityType.object, но его фактическое поведение проверено недостаточно, чтобы рекомендовать сценарий с ним.
• Не каждый обработчик действия поддерживает все варианты источников объектов.
• Обработчики локальных тестовых данных для прямого создания и изменения Link и для операций с Link по GUID существуют, но встроенная интерактивная демонстрация Object API их не вызывает. Не считайте этот маршрут работающим подтверждением прямых изменений Link.
• Имена методов, схемы параметров и правила доступа определяет контракт сервера.

Справочник параметров

Страницы параметров пока представлены на английском языке.

Отображение и структура:

• editor.mode
• editor.header.title
• editor.header.propertyAsId
• editor.tabs[].id
• editor.tabs[].title

Поля редактора:

• editor.{fields|tabs[].fields}[].attribute
• editor.{fields|tabs[].fields}[].editAttribute
• editor.{fields|tabs[].fields}[].type
• editor.{fields|tabs[].fields}[].control
• editor.{fields|tabs[].fields}[].label
• editor.{fields|tabs[].fields}[].required
• editor.{fields|tabs[].fields}[].readonly
• editor.{fields|tabs[].fields}[].hidden
• editor.{fields|tabs[].fields}[].defaultValue
• editor.{fields|tabs[].fields}[].listOfValue
• editor.{fields|tabs[].fields}[].comment
• editor.{fields|tabs[].fields}[].regEx
• editor.{fields|tabs[].fields}[].propertyAsId
• editor.{fields|tabs[].fields}[].selectPanel
• editor.{fields|tabs[].fields}[].layout

Объект, Link и метод, с которыми работает редактор:

• editor.entityType.object.metaTypeName
• editor.entityType.object.withLinkedAttribute
• editor.entityType.link.linkName
• editor.runMethod.parent
• editor.runMethod.method
• editor.runMethod.objects[]
• editor.runMethod.params

Источники объектов в LinkEndpoint:

• LinkEndpoint.objectId
• LinkEndpoint.getFromActionId
• LinkEndpoint.idSource
• LinkEndpoint.getFromItem
• LinkEndpoint.getFromCreatedObject
• LinkEndpoint.getSelectedObjectForPanelId
• LinkEndpoint.getSelectedObjectForEventId
• LinkEndpoint.selectPanel.panel
• LinkEndpoint.selectPanel.label
• LinkEndpoint.selectPanel.height
• LinkEndpoint.selectPanel.width

Следующие шаги

• Подключение редактора к действию
• Публикация выбранного объекта через событие
• Типизированные значения и приоритет метаданных
• Сценарий создания, редактирования и обновления