Функции отображения
Функция отображения — функция JavaScript, рисующая пользовательское представление: вместо платформы она рисует строки группы объектов или значение свойства формы в интерактивном представлении. Её называет опция CUSTOM группы в блоке OBJECTS или свойства — в блоке PROPERTIES либо среди опций свойств в его объявлении. Называет её и атрибут custom таблицы группы GRID(o) или компонента свойства в дизайне формы (DESIGN). Функция возвращает объект из функций, которые вызывает платформа: render, update и необязательной clear. Вместо такой функции в тех же местах можно назвать компонент React (Компонент React в CUSTOM). Функции отображения вызывает только веб-клиент.
Функция отображения
Например, функция отображения группы объектов itemCards возвращает объект из двух функций, render и update:
function itemCards() {
return {
render: (element, controller) => {
...
},
update: (element, controller, list) => {
...
}
}
}
Регистрируется именно функция: платформа сама вызывает itemCards() и берет render и update из результата, поэтому нельзя регистрировать сам объект с этими функциями без обертки-функции. Её имя ищется сначала в реестре window.lsfusion.custom, где регистрируют свои экспорты загруженные клиентские модули JavaScript, затем среди имён глобального объекта window. Имя, зарегистрированное с видом reactView, — это компонент React.
Функция render принимает на вход контроллер и элемент, внутри которого должны создаваться новые элементы, необходимые для отображения данных.
Для группы объектов сигнатура функции — render(element, controller, event). При создании представления она получает событие браузера, открывшее форму, если оно ещё доступно, или null. Для ячейки свойства вызывается render(element, controller).
Для обновления отображаемых значений платформа будет каждый раз вызывать функцию update, в которую будет передан тот же element, что и в функции render, а также список значений list. Для свойства в update вместо списка передаётся его значение.
Объект может содержать и необязательную функцию clear, которую платформа вызывает при очистке представления группы объектов или ячейки свойства. Если clear группы выбросит исключение, клиент сообщит об ошибке и завершит очистку представления.
Прежнее объявление функции отображения группы с параметрами, function itemCards(element, list, controller), устарело с версии 5.0 и будет удалено в 8.0. Платформа вызывает такую функцию напрямую при каждом обновлении. Её заменяет показанная выше функция без параметров с инициализацией в render, передачей нового списка в update и очисткой в clear.
Строки группы объектов
В list передается не весь набор объектов, а только считанная страница: для группы объектов с видом представления CUSTOM ее размер по умолчанию — 1000 объектов. Чтобы представление получало все объекты группы, задайте в блоке OBJECTS опцию PAGESIZE 0 (читать все объекты).
Названия полей объектов соответствуют названию свойств на форме. Значения свойств преобразуются в значения JS так же, как в строках React-представления: например, значения классов даты и времени передаются как Date, а JSON — как разобранный объект. Свойство, значением которого является объект, приходит числовым id этого объекта — тем же, которым объект передаётся в запись FK и вызовы сервера. Каждый объект несёт также те же key и objects, что и строка представления React (Идентификация строки).
Если свойство группируется по колонкам, поле колонки с непустым ключом называется <property>_<index>, где index — позиция среди ключей колонок этого свойства, начиная с нуля. Поле колонки, скрытой по условию SHOWIF, в строке отсутствует. Имена key и objects зарезервированы для идентификации строки.
Четвёртым аргументом, options, функция update получает значение опции OPTIONS группы (разобранный JSON).
Контроллер группы объектов
Методы локального контроллера, передаваемого в render и update, не считая служебных (необязательные аргументы — в скобках). Здесь property — интеграционное имя свойства, добавленного на форму в этой группе объектов, object — объект из списка list:
| метод | что делает |
|---|---|
isCurrent(object) | является ли объект текущим в группе |
changeObject(object[, rendered[, element]]) | задает текущий объект группы (см. ниже); с element показывает рядом с ним запись таблицы; Promise его запроса |
changeProperty(property[, object][, value]) | изменяет значение свойства или выполняет действие — на текущем объекте или на переданном (см. ниже); Promise его запроса |
batch(fn) | выполнить fn; вызовы changeProperty и фильтров представления в ней уходят вместе, одним запросом; Promise этого запроса |
changeDateProperty(property, object, year, month, day) | устарел с версии 6.0, будет удалён в 8.0. Замена — controller.changeProperty(property, object, new Date(year, month - 1, day)). Старый метод вызывает changeProperty без указания контроллера и выбрасывает ReferenceError, если такое имя не определено |
changeProperties(properties, objects, newValues) | устарел с версии 7.0. Изменяет по одной ячейке на каждый индекс в параллельных массивах имён колонок, строк и значений, и возвращает Promise пакета. Замена — batch(fn) с вызовом changeProperty для каждой ячейки. Старый метод пропускает неизвестные колонки |
getValue(property, object) | текущее значение свойства для объекта |
getCaption(property) | заголовок свойства |
isPropertyReadOnly(property, object) | доступность свойства для правки: null — редактируемое, false — только чтение |
getBackground(property, object) / getForeground(property, object) | цвет фона / текста ячейки |
getGroupObjectBackgroundColor(object) | цвет фона строки или null, если он не задан. Если object.color истинно, берётся строковое представление этого значения. Без аргумента или при передаче null выбрасывается TypeError |
getGroupObjectForegroundColor([object]) | цвет текста строки или null, если он не задан. Без аргумента или при передаче null возвращается цвет текущей строки |
getDisplayBackgroundColor(color[, isCurrent]) / getDisplayForegroundColor(color) | переданный цвет ('#rrggbb') с поправкой на текущую цветовую тему или null для null. Метод для фона игнорирует isCurrent |
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]]) | список подсказок значений свойства с сервера |
getValues(property, value, ok[, fail]) | сокращённая запись getPropertyValues(property, value, ok, fail) в режиме по умолчанию 'objects' |
getObjects(object) | дескриптор objects строки. Если передан сам дескриптор, возвращается он же. Для ключа или объекта без дескриптора платформы возвращается null |
createObject(object, objects) | поверхностная копия object с полями key и objects переданной строки или дескриптора. Если objects не идентифицирует строку, оба поля в копии отсутствуют |
getObjectsString(object) | строка, по которой diff сопоставляет объекты. Для строки данных или её дескриптора равна String(row.key). Для объекта без дескриптора возвращается String(object.key), для примитивного значения или null — String(object) |
isList() | true для представления группы объектов |
isTabFocusable() | должно ли поле ввода представления получать фокус при переходе по Tab. Для группы всегда true |
diff(list, fnc[, noDiffObjects][, removeFirst]) / clearDiff() | вычисляет изменения списка (см. ниже) |
setBooleanViewFilter(property, pageSize) | фильтрует представление условием «значение свойства истинно»; Promise его запроса |
setDateIntervalViewFilter(startProperty, endProperty, pageSize, start, end) | фильтрует представление по интервалу дат; Promise его запроса |
getColorThemeName() | имя текущей цветовой темы: 'LIGHT' или 'DARK' |
form | контроллер формы |
Если второй параметр changeObject (rendered) не указан, он считается равным false, что означает, что сервер должен в итоге вызвать функцию update с новым списком объектов (возможно тем же). Если представление уже отобразило новый текущий объект, передают rendered = true. Если явно переданный объект, отличный от null, не удалось определить, текущий объект сохраняется. В этом случае, как и при передаче уже текущего объекта, вызов завершается без запроса. Если есть текущая строка, при передаче null в качестве object отправляется запрос, который завершается ошибкой, поскольку серверу нужен ключ строки.
changeProperty понимает свои аргументы по их количеству, а единственный аргумент — по нему самому: без аргументов он выполняет событие изменения свойства (для действия — само действие) на текущем объекте; с одним аргумент считается строкой, и событие изменения выполняется на ней, если это строка данных или дескриптор objects либо если свойство — действие, нарисованное в группе объектов; всё остальное — значение, которое устанавливается для текущего объекта; с двумя — первый аргумент строка, второй значение. Формат значений — тот же, что у <group>.<property>.change контроллера формы. Свойство, не являющееся колонкой этой группы, changeProperty передает форме, которая разрешает его только по имени — так, как представление называет свойство везде: <group>.<property> — свойство этой группы, имя без группы — свойство уровня формы (пустой группы); свойство группы объектов называется с группой, передана строка или нет, а строка, переданная с именем без группы, — ошибка.
Для колонки этой группы changeProperty(property, object, value[, type[, index]]) обновляет также список, запомненный методом diff, если такой список есть. По умолчанию метод заменяет указанное поле в совпадающих строках. С 'add' он вставляет копию объекта с заданным значением поля в позицию index (начиная с нуля, по умолчанию в конец). С 'remove' удаляет совпадающую строку, которая должна быть в списке. Эти аргументы влияют только на запомненный список. Если явно переданная строка не содержит дескриптора и сама им не является, метод возвращает null и выводит причину в консоль. При передаче изменения форме неизвестное или неоднозначное имя, свойство с группировкой по колонкам либо строка, недопустимая для указанного имени, вызывают исключение в момент вызова.
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 => { ... });
Оба метода поиска не возвращают значения. В ответе displayString — отображаемый текст подсказки, rawString — исходный текст, а objects зависит от режима поиска. При неизвестной колонке, неизвестном режиме или ошибке поиска вызывается fail(), если он передан. При неизвестном режиме причина также выводится в консоль. В getPropertyValues положительный count увеличивает число запрашиваемых подсказок. По умолчанию count равен 0. Сокращённый метод группы getValues всегда использует это значение.
Чтобы обновлять 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, чтобы следующая отрисовка началась с пустого состояния.
setBooleanViewFilter и setDateIntervalViewFilter задают серверный фильтр представления и размер страницы pageSize: в следующий вызов update список приходит уже отфильтрованным. setBooleanViewFilter оставляет объекты, у которых значение свойства property истинно. setDateIntervalViewFilter оставляет объекты, у которых период от значения startProperty до значения endProperty пересекается с интервалом от start до end (значения — JS Date, а если endProperty равен null, оба конца периода берутся из startProperty). Так, встроенное представление календаря читает только события видимого диапазона дат.
Геттеры отображения позволяют компоненту использовать атрибуты дизайна, задаваемые на форме: например, представление диаграмм строит наборы данных, беря заголовок и цвета колонок из getCaption, getBackground и getForeground.
Геттеры колонки, принимающие объект, используют текущую строку, если объект не указан или равен null. Для неизвестной колонки геттеры значения и атрибутов дизайна, а также isPropertyReadOnly возвращают null. Если в фильтре представления указана неизвестная колонка, фильтр и размер страницы сохраняются.
При изменении в группе, установке фильтра представления или выполнении пакета Promise запроса разрешается после обработки клиентом ответа сервера. Если запрос отправлять не требуется, Promise разрешается сразу. При ошибке запроса или на закрытой форме (Form is closed) он отклоняется.
Правка формы — changeObject, changeProperty, batch и фильтры представления — идёт обычным каналом правки и не требует проверки доступа. Вызовы сервера контроллера формы, controller.form, её проходят (Проверка доступа).
Значение свойства
Функция отображения свойства рисует одно значение — значение своего свойства, в ячейке таблицы или на панели. Функция update получает его третьим аргументом, value:
update: function (element, controller, value) {
element.text.innerText = value || '';
}
Значение любого класса приходит преобразованным в значение JS так же, как в строках React-представления, и, кроме файлов, в том же виде передаётся в change.
У обычной функции отображения ячейки, заданной в CUSTOM, четвёртый аргумент update равен null.
Вместе с SELECT функция отображения рисует выбор. В value функции update передаются варианты свойства, как и собственному элементу выбора платформы. Обёртка-функция вызывается с объектом {multi, notNull, html, changeValue}: multi означает выбор нескольких значений, notNull — обязательность выбранного значения, html — представления вариантов в виде HTML, а changeValue — передачу представления выбранного варианта явному изменению свойства.
Контроллер свойства
Методы контроллера, передаваемого в функцию update, не считая служебных (необязательные аргументы — в скобках):
| метод | что делает |
|---|---|
change([value]) | передает изменение значения (см. ниже); без аргумента действие изменения вызывается без значения |
change(value, renderValueSupplier) | в ячейке свойства передаёт value действию изменения и показывает renderValueSupplier(oldValue), пока выполняется запрос |
changeValue([value]) | устарел с версии 5.0, будет удалён в 8.0. Замена — change([value]) |
changeProperty(property, object, newValue[, type[, index[, changeValue]]]) | изменяет поле элемента массива в ячейке. Передаёт в change объект {property, objects: object.objects, value: newValue} либо явно заданное значение changeValue. Отображаемый массив обновляется, как описано ниже |
getValues(value, ok[, fail[, count]]) | список подсказок с сервера для вводимого значения value — тех же, что при штатном редактировании свойства |
getPropertyValues(property, value, ok[, fail[, count]]) | вызывает getValues ячейки со строкой поиска property + ':' + value. Для стандартного действия изменения свойства, построенного оператором JSON, property — интеграционное имя поля, значения которого запрашиваются |
isReadOnly() | доступность свойства для правки: null — редактируемое, false — только чтение, true — отключено |
isList() | false для свойства, в том числе в ячейке таблицы |
isTabFocusable() | должно ли поле ввода представления получать фокус при переходе по Tab. На панели определяется доступностью фокуса для свойства, в ячейке таблицы равно false |
getObjects(object) | поле objects элемента массива или undefined, если поле отсутствует. Без аргумента или при передаче null выбрасывается TypeError |
createObject(object, objects) | поверхностная копия элемента. При передаче строки платформы или её дескриптора копии задаются key и objects. Любое другое значение objects заменяет только одноимённое поле |
getObjectsString(object) | значение, по которому diff и changeProperty сопоставляют элементы. Для строки платформы или её дескриптора оно учитывает идентификаторы объектов группы и ключ строки. Если передать null или не передать элемент, возникает TypeError. Для другого объекта с заданным key метод возвращает String(object.key). В остальных случаях он возвращает null, если поле object.objects отсутствует, равно undefined или null. При любом другом значении поля метод возвращает результат JSON.stringify(object.objects) (например, JSON.stringify(() => 1) возвращает undefined) или '{}', если при сериализации выброшено исключение |
diff(list, fnc[, noDiffObjects][, removeFirst]) | вычисляет изменения массива значений — как метод diff группы объектов; элементы сопоставляются по полю objects |
getColorThemeName() | имя текущей цветовой темы: 'LIGHT' или 'DARK' |
form | контроллер формы |
Значение, переданное методом change, попадает в обработку изменения свойства так же, как значение, введенное штатным редактором, — для первичного свойства это запись значения в него. Когда переданный объект попадает в стандартное действие изменения свойства со значением пользовательского класса, указанного в блоке CHECKED BY ограничения, он должен быть среди значений, которые оставляет фильтр: иначе изменение отклоняется. Если после свойства указано действие с ключевым словом ON CHANGE, вместо стандартной обработки изменения выполняется оно, а значение, переданное методом change, подставляется вместо ввода пользователя в его запрос значения.
Запросы метода change и вызовов сервера через controller.form выполняются на сервере в порядке вызова.
Методы ячейки change, changeValue и changeProperty не возвращают значения. Для changeProperty исходный отображаемый массив пуст, если старое значение равно null. По умолчанию у совпадающих элементов заменяется указанное поле. Операции 'add' и 'remove' и позиция вставки index действуют так же, как у changeProperty группы объектов. Явно заданный changeValue влияет только на значение, переданное действию.
Обработчик ok метода getValues получает результат в том же формате, что и getPropertyValues пользовательской группы объектов. Оба метода поиска ячейки не возвращают значения и принимают такие же count и обработчик ошибки. Чтобы указать count без обработчика ошибки, используйте controller.getPropertyValues('name', query, ok, undefined, 20). При поиске внутри пакета вызывается fail(), если он передан, и причина выводится в консоль.
Если функция отображения свойства рисует подвал колонки или ячейку сводной таблицы, изменение и поиск не выполняются и ни один обработчик поиска не вызывается. Если функция отображения рисует значение пользовательского фильтра, change(value, renderValueSupplier) записывает в фильтр результат renderValueSupplier(oldValue), где oldValue — текущее значение фильтра. В пользовательском фильтре ни getValues, ни getPropertyValues не вызывают ok или fail.
Функция render и необязательная функция clear, вызываемая при очистке ячейки, получают вторым аргументом сокращенный контроллер. Он предоставляет isList(), isTabFocusable() и clearDiff(), сбрасывающий запомненный методом diff список. Метод isReadOnly() полного контроллера возвращает состояние на момент вызова update.