Перейти к основному содержимому
Версия: 7.0

How-to: Пользовательские компоненты (объекты)

Эта статья описывает классические JavaScript-представления для существующего кода. Для нового представления используйте React-компонент в контейнере custom или зарегистрированный как reactView для CUSTOM (How-to: Пользовательские React-представления).

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

В качестве наглядного примера рассмотрим задачу по отображению в виде "плитки" списка товаров с изображениями.

Доменная логика​

Для начала создадим классы и свойства товаров, а также форму редактирования:

CLASS Item 'Item';

name 'Name' = DATA STRING (Item) NONULL;
price 'Price' = DATA NUMERIC[12,2] (Item) NONULL;
picture '' = DATA IMAGEFILE (Item);

FORM item 'Item'
OBJECTS i = Item PANEL
PROPERTIES(i) name, price, picture

EDIT Item OBJECT i
;

DESIGN item {
OBJECTS {
MOVE PROPERTY(picture(i)) {
fill = 1;
}
}
}

Для каждого товара должны быть заданы наименование, цена и изображение.

Интерфейс​

Создадим форму со списком товаров. Для этого добавим на форму объект Товар, его свойства, а также действия по добавлению, редактированию и удалению:

FORM items 'Items'
OBJECTS i = Item CUSTOM 'itemCards'
PROPERTIES(i) READONLY picture, price, name
PROPERTIES(i) NEWSESSION new = NEW, edit = EDIT GRID, DELETE GRID
;

NAVIGATOR {
NEW items;
}

При помощи ключевого слова CUSTOM указывается, что для отрисовки списка товаров должен использоваться не стандартный табличный интерфейс, а компоненты, создаваемые функцией itemCards. Эту функцию объявим в файле itemcards.js, который поместим в папку resources/web. Это путь без сборки — обычный файл .js, без JSX и упаковки. Где размещается пользовательский JS и о варианте со сборкой см. How-to: Пользовательские клиентские JS-модули. Она будет возвращать объект, состоящий из двух функций: render и update. Регистрируется именно функция: платформа сама вызывает itemCards() и берет render и update из результата, поэтому нельзя регистрировать сам объект с этими функциями без обертки-функции.

Функция render принимает на вход контроллер и элемент, внутри которого должны создаваться новые элементы, необходимые для отображения данных:

render: (element, controller) => {
let cards = document.createElement("div")
cards.classList.add("item-cards");

element.cards = cards;
element.appendChild(cards);
},

В данном примере мы создаем новый div cards, запоминаем его и добавляем внутрь element.

Для обновления отображаемых значений платформа будет каждый раз вызывать функцию update, в которую будет передан тот же element, что и в функции render, а также список значений list:

update: (element, controller, list) => {
while (element.cards.lastElementChild) {
element.cards.removeChild(element.cards.lastElementChild);
}

for (let item of list) {
let card = document.createElement("div")
card.classList.add("item-card");

if (controller.isCurrent(item))
card.classList.add("item-card-current");

let cardImage = document.createElement("img")
cardImage.classList.add("item-card-image");
cardImage.src = item.picture;
card.appendChild(cardImage);

let cardPrice = document.createElement("div")
cardPrice.classList.add("item-card-price");
cardPrice.innerHTML = item.price;
card.appendChild(cardPrice);

let cardName = document.createElement("div")
cardName.classList.add("item-card-name");
cardName.innerHTML = item.name;
card.appendChild(cardName);

element.cards.appendChild(card);

card.onclick = function(event) {
if (!controller.isCurrent(item)) controller.changeObject(item);
}
card.ondblclick = function(event) {
controller.changeProperty('edit', item);
}
}
}

Так как функция update вызывается каждый раз, когда изменяются данные, то первым делом происходит удаление всех ранее созданных элементов (а именно карточек товаров).

В list передается не весь набор объектов, а только считанная страница: для группы объектов с видом представления CUSTOM ее размер по умолчанию — 1000 объектов. Чтобы представление получало все объекты группы, задайте в блоке OBJECTS опцию PAGESIZE 0 (читать все объекты).

В данном примере используется самая простая схема обновления, но при необходимости ее можно оптимизировать путем обновления DOM только для изменившихся значений. Для этой цели у controller есть метод diff, в который передаются новый список объектов list и функция-обработчик. Метод сравнивает переданный список со списком из предыдущего вызова (при первом вызове — с пустым) и выдает изменения как последовательный сценарий преобразования старого списка в новый: обработчик вызывается для каждого изменения и получает его тип ('add', 'update' или 'remove'), позицию изменения в преобразуемом списке (для 'add' и 'update' она совпадает с позицией объекта в новом списке) и сам объект (для 'remove' — удаленный, для остальных типов — новый). После этого переданный список запоминается. Два необязательных флага уточняют сравнение: при noDiffObjects строка одного объекта не превращается в строку другого — вместо 'update' такая пара дает 'remove' и 'add', а при removeFirst обработчик получает сначала все удаления — с позициями в предыдущем списке — и только затем добавления и изменения. Пример:

controller.diff(list, (type, index, object) => {
switch (type) {
case 'add': ...; break;
case 'update': ...; break;
case 'remove': ...; break;
}
}, true, true);

Метод clearDiff сбрасывает запомненный список — его вызывают в необязательной функции clear компонента, которая вызывается при очистке представления с теми же element и controller, чтобы следующая отрисовка началась с пустого состояния.

После удаления старых элементов для каждого объекта из массива list создается свой div card, в который помещаются нужные элементы отображения каждого свойства. Названия полей объектов соответствуют названию свойств на форме. Значения свойств преобразуются в значения JS так же, как в строках React-представления: например, значения классов даты и времени передаются как Date, а JSON — как разобранный объект. Свойство, значением которого является объект, приходит числовым id этого объекта — тем же, которым объект передаётся в запись FK и вызовы сервера. При помощи метода isCurrent определяется, какой объект из списка является текущим.

В самом конце функции добавляются обработчики нажатия кнопки мыши на карточку товара.

По одиночному нажатию у контроллера вызывается метод changeObject, который изменяет текущий объект. Второй параметр (rendered) не указывается (то есть считается равным false), что означает, что сервер должен в итоге вызвать функцию update с новым списком объектов (возможно тем же). Так как значение метода isCurrent изменится, то повторное создание карточек товаров изменит текущий выделенный объект в интерфейсе.

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

Чтобы объединить функции render и update в одну, создается функция itemCards, которая возвращает их внутри одного объекта:

function itemCards() {
return {
render: function (element, controller) => {
...
},
update: function (element, controller, list) {
...
}
}
}

Для завершения настройки дизайна создадим файл itemcards.css, которую также поместим в папку resources/web:

.item-cards {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
grid-auto-rows: 200px;
grid-gap: 10px;
}

.item-card {
cursor: pointer;
display: flex;
flex-direction: column;
overflow: hidden;
align-items: center;
padding: 8px;
}
.item-card-current {
background-color: lightblue;
}

.item-card-image {
flex: 1;
min-height: 100px;
}

.item-card-price {
font-weight: bold;
}

.item-card-name {
color: gray;
}

Для того, чтобы при открытии страницы в браузере, загрузились созданные js и css файлы, нужно добавить их инициализацию в действии onWebClientInit путем добавления имени файла в свойство onWebClientInit(STRING). Числовое значение необходимо для задания порядка загрузки:

onWebClientInit() + {
onWebClientInit('itemcards.js') <- 1;
onWebClientInit('itemcards.css') <- 2;
}

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

Методы контроллера​

Методы локального контроллера, передаваемого в render и update, не считая служебных (необязательные аргументы — в скобках). Здесь property — интеграционное имя свойства, добавленного на форму в этой группе объектов, object — объект из списка list:

методчто делает
isCurrent(object)является ли объект текущим в группе
changeObject(object[, rendered[, element]])задает текущий объект группы (см. выше); с element показывает рядом с ним запись таблицы; Promise его запроса
changeProperty(property[, object][, value])изменяет значение свойства или выполняет действие — на текущем объекте или на переданном (см. выше); Promise его запроса
batch(fn)выполнить fn; вызовы changeProperty и фильтров представления в ней уходят вместе, одним запросом; Promise этого запроса
getValue(property, object)текущее значение свойства для объекта
getCaption(property)заголовок свойства
isPropertyReadOnly(property, object)доступность свойства для правки: null — редактируемое, false — только чтение
getBackground(property, object) / getForeground(property, object)цвет фона / текста ячейки
getFont(property, object)шрифт ячейки
getPlaceholder(property, object), getPattern(property, object), getRegexp(property, object), getRegexpMessage(property, object), getTooltip(property, object), getValueTooltip(property, object)значения одноименных атрибутов дизайна свойства
getCaptionClass(property), getGridClass(property, object), getValueClass(property, object)CSS-классы, заданные одноименными атрибутами дизайна
getChangeKey(property, object) / getChangeMouse(property, object)заданное на форме сочетание клавиш / событие мыши, изменяющее свойство
getPropertyCustomOptions(property, object)значение опции OPTIONS свойства (разобранный JSON)
getPropertyValues(property, value[, mode], ok[, fail][, count])список подсказок значений свойства с сервера
diff(list, fnc[, noDiffObjects][, removeFirst]) / clearDiff()вычисляет изменения списка (см. выше)
setBooleanViewFilter(property, pageSize)фильтрует представление условием «значение свойства истинно»; Promise его запроса
setDateIntervalViewFilter(startProperty, endProperty, pageSize, start, end)фильтрует представление по интервалу дат; Promise его запроса
getColorThemeName()имя текущей цветовой темы: 'LIGHT' или 'DARK'
formконтроллер формы

changeProperty понимает свои аргументы по их количеству, а единственный аргумент — по нему самому: без аргументов он выполняет событие изменения свойства (для действия — само действие) на текущем объекте; с одним аргумент считается строкой, и событие изменения выполняется на ней, если это строка данных или дескриптор objects либо если свойство — действие, нарисованное в группе объектов; всё остальное — значение, которое устанавливается для текущего объекта; с двумя — первый аргумент строка, второй значение. Формат значений — тот же, что у <group>.<property>.change контроллера формы. Свойство, не являющееся колонкой этой группы, changeProperty передает форме, которая разрешает его только по имени — так, как представление называет свойство везде: <group>.<property> — свойство этой группы, имя без группы — свойство уровня формы (пустой группы); свойство группы объектов называется с группой, передана строка или нет, а строка, переданная с именем без группы, — ошибка. batch(fn) делает несколько изменений вместе: каждый вызов changeProperty в fn делается сразу, а уходят они одним запросом, когда fn вернётся, — например, представление диаграммы Ганта при перетаскивании полосы задачи изменяет обе даты сразу:

controller.batch(() => {
controller.changeProperty('start', task, newStart);
controller.changeProperty('end', task, newEnd);
});

Пакет несёт только изменения: внутри fn getPropertyValues отклоняется — вызывается его failure-callback, причина пишется в консоль, — а серверный вызов контроллера формы (controller.form.exec, eval, evalAction, change) — тоже, его Promise отвергается; делайте их до пакета или после; а изменения — только через changeProperty и фильтры представления (setBooleanViewFilter, setDateIntervalViewFilter), которые входят в пакет: перевод фокуса или изменение DOM внутри fn заставляют платформу отправлять свои запросы, а на них пакет не рассчитан. Функция, возвращающая Promise, отклоняется — но не собственный Promise пакета, который возвращает changeProperty, сделанный в fn, — как и в batch контроллера формы.

getPropertyValues использует те же режимы mode, что и <group>.<property>.getValues контроллера формы, но свойство разрешается среди колонок этой группы, а запрос выполняется для ее текущего объекта. Результат передаётся в обработчик ok в виде { data: [ { displayString, rawString, objects }, ... ], more }. more равно true, пока будут ещё ответы — окончательный список ответа, который сервер дал, ещё не убедившись, что несохранённые изменения формы на него не влияют, или ответ более позднего запроса. Ответ более раннего запроса, пришедший после ответа более позднего, отбрасывается:

controller.getPropertyValues('name', query, result => { ... });

setBooleanViewFilter и setDateIntervalViewFilter задают серверный фильтр представления и размер страницы pageSize: в следующий вызов update список приходит уже отфильтрованным. setBooleanViewFilter оставляет объекты, у которых значение свойства property истинно. setDateIntervalViewFilter оставляет объекты, у которых период от значения startProperty до значения endProperty пересекается с интервалом от start до end (значения — JS Date, а если endProperty равен null, оба конца периода берутся из startProperty). Так, встроенное представление календаря читает только события видимого диапазона дат.

Геттеры отображения позволяют компоненту использовать атрибуты дизайна, задаваемые на форме: например, представление диаграмм строит наборы данных, беря заголовок и цвета колонок из getCaption, getBackground и getForeground.

Вызов сервера​

Пользовательское представление объекта обращается к серверу через контроллер формы: он доступен как controller.form из локального контроллера представления, как props.controller.form в React-представлении либо как контроллер, передаваемый в функцию INTERNAL CLIENT (последним аргументом, после преобразованных параметров вызова). Его методы exec / eval / evalAction / change выполняются на сервере и возвращают Promise. Их сигнатуры — в разделе Вызов сервера. Далее в этом разделе — как ведут себя эти серверные вызовы: преобразование результата, сессии и авторизационная проверка.

Результат преобразуется в значение JS:

Результат на сервереЗначение в JS
скалярное число, строка, логическое значение или датачисло, строка, логическое значение или Date
JSONразобранный объект или массив
JSONTEXT, XMLисходная строка
файл — изображение или свойство файлового типастрока со ссылкой для скачивания
результат с дополнительными параметрами — RETURN, выражение которого объявляет новые параметрымассив объектов {name, value}, по одному на каждый набор значений параметров — массив и при одном значении, пустой, когда значений нет: name — эти значения через запятую, value — результат, преобразованный как выше
отсутствующий результат или NULLundefined

Вызов, выполненный так, как его выполняет инструмент eval MCP-сервера, — controller.mcp.eval(script, ...params), так же exec и evalAction — принимает параметры и отдаёт результат как инструмент. Параметры привязываются так, как инструмент привязывает свои params, по правилам HTTP-запроса: значение берётся своей строкой и разбирается классом параметра — поэтому строка с числом принимается как число, — а объект, в котором есть text или base64 либо указано type: 'file', — это файл при любом классе параметра. Вызов завершается тем, чем отвечает инструмент, а не результатом, преобразованным по таблице: объектом {results, status}, где status — HTTP-статус, который установило действие, 200, если оно его не устанавливало, а в results по записи на каждое значение, которое вернуло действие, — {value} со значением в виде строки, и ещё name в каждой записи результата с дополнительными параметрами.

Файл — это запись {type: 'file', fileName, extension, mimeType, size} — fileName это имя файла с расширением, а именем файла без своего имени служит file, — и в ней text — текст текстового файла, base64 — содержимое любого другого файла меньше 64 КиБ в base64, или url — ссылка для скачивания файла большего размера. Содержимое названо так же, как в файле-параметре, поэтому запись с ним можно передать в следующий вызов как есть. Текстовый файл больше 10 МиБ передаётся без текста, с truncated: true; один вызов несёт не больше 30 МиБ содержимого — сверх этого текст передаётся так же, а любой другой файл — ссылкой url.

Параметры передаются как обычные значения JS (число, строка, логическое значение, Date или объект/массив для параметра типа JSON) и привязываются позиционно. Файл передаётся строкой его текста или объектом: {base64, fileName, extension} для файла с нетекстовым содержимым, {text, fileName, extension} — чтобы задать текстовому файлу имя или расширение; имя и расширение необязательны. Объект lsFusion передать нельзя — передаётся его числовой id. Если параметр типизирован классом, платформа сама находит объект этого класса по id. Дескриптор строки (row.objects) объектом не является: для типизированного классом параметра вызов завершается ошибкой. Ошибка — отсутствующее действие или свойство, ошибка в скрипте или исключение во время выполнения — отклоняет Promise с её сообщением.

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

По умолчанию эти вызовы ограничены так же, как внешний HTTP-API: при enableAPI = 0 вызов разрешён, только если действие или свойство помечено @@api (что заодно открывает его по HTTP), либо у пользователя есть права администратора. Чтобы контроллер конкретной формы мог вызывать выбранные действия и свойства в обход этого ограничения, их перечисляют в блоке CUSTOMS формы — тогда для доступа достаточно того, что пользователь может открыть эту форму, и явного перечисления:

FORM order 'Order'
OBJECTS o = Order
PROPERTIES(o) number, note
CUSTOMS round, format = formatSum, taxRate
;

Теперь controller.form.exec("round", 3.14159), controller.form.exec("format", 1990, "USD") и controller.form.change("taxRate", 0.2) работают на этой форме без @@api и enableAPI (React-представление вызывает то же на props.controller.form). Каждую запись можно переименовать псевдонимом (format = formatSum), снабдить префиксом ACTION, чтобы выбрать действие, и указать полностью с сигнатурой (round[NUMERIC]) для выбора перегрузки. exec требует действие, change — свойство. Параметры передаются вызывающей стороной позиционно как обычные значения — в фазе 1 записи это в основном такие примитивные вызовы. Блок меняет то, какие вызовы разрешены, а не то, как связываются параметры, и не ограничивает значения аргументов, которые передаёт вызывающая сторона, поэтому перечислять стоит только записи, безопасные при любых аргументах (привязка параметра к собственному объекту формы — фаза 2). eval/evalAction выполняют произвольный скрипт и остаются под ограничением. Сквозной работающий пример — один компонент CUSTOM, вызывающий действия с параметрами-объектами, примитивами и JSON, читающий результат RETURN и изменяющий свойства через CUSTOMS, — в статье How-to: Пользовательские компоненты (вызовы сервера).

Для вызова, нужного пользовательскому представлению, предпочитайте CUSTOMS, а не @@api: CUSTOMS ограничивает доступ этой формой, тогда как @@api ещё и открывает действие или свойство для внешнего HTTP-API. Помечайте @@api только то, что действительно входит в этот API.