Примеры компонент. How to
В данном разделе собраны практические примеры настройки компонент форм платформы Citeck, а также типовые сценарии («How to») — скрипты и конфигурации для решения часто встречающихся задач: управление видимостью полей, автозаполнение, обработка событий и другие.
Columns
Компонент Columns позволяет удобно расположить компоненты формы.
Свойства столбца - основной параметр настройки, позволяет определить как по колонкам будет разбиваться компонент. Компонент основан на использовании Bootstrap Grid.
На вкладке «Вид» в разделе Свойства столбца указать количество столбцов и их размер.
Далее нажать «Сохранить». Результат:
Text field
Text field - текстовый компонент.
На вкладке «Базовые» заполняется:
Поле |
Описание |
|---|---|
Название поля (1) |
Имя компонента, как оно будет отражаться на форме. |
Имя свойства (2) |
Имя свойства в типе данных. |
Обязательность поля выставляется отдельным чекбоксом. (3)
Автофокус - автоматическая устанавка курсора ввода, без необходимости кликать на него мышью:
ECOS Select Component
ECOS Select Component - компонент формы для выбора значения из списка.
На вкладке «Базовые» заполняется:
Поле |
Описание |
|---|---|
Название поля (1) |
Имя компонента, как оно будет отражаться на форме. |
Имя свойства (2) |
Имя свойства в типе данных. |
Обязательность поля выставляется отдельным чекбоксом. (3)
На вкладке «Данные» в «Типе источника данных» выбрать Values (1).
Data Source Values заполняется значениями, которые должны быть для выбора в списке (2):
Поле |
Описание |
|---|---|
Название поле |
Отображаемое имя. |
Значение |
Значение, которое содержится. |
Date / Time Component
Date / Time Component - компонент даты / времени.
На вкладке «Базовые» заполняется:
Поле |
Описание |
|---|---|
Название поля (1) |
Имя компонента, как оно будет отражаться на форме. |
Имя свойства (2) |
Имя свойства в типе данных. |
Обязательность поля выставляется отдельным чекбоксом. (3)
На вкладке «Вид» указать формат даты (5) и возможность ручного ввода (4).
Для изменения формата даты/времени перейдите во вкладку - вкладка «Вид» - Формат:
Значение по умолчанию — текущая дата
Для установки текущей даты в качестве значения по умолчанию используйте свойство customDefaultValue на вкладке «Данные». Свойство принимает JavaScript-выражение, результат которого присваивается переменной value.
Примечание
Статическое свойство defaultValue не поддерживает динамические значения (например, "now" не работает). Для динамических значений всегда используйте customDefaultValue.
Пример JSON-конфигурации компонента:
{
"key": "startDate",
"type": "datetime",
"input": true,
"format": "yyyy-MM-dd",
"enableTime": false,
"customDefaultValue": "value = new Date();",
"defaultValue": ""
}
В поле Custom Default Value в билдере форм введите:
value = new Date();
Пустое поле при создании записи может быть заполнено текущей датой. Применение значения по умолчанию зависит от компонента и начальных данных; оно не предназначено для безусловной перезаписи уже заполненного поля. Подробнее см. customDefaultValue.
Select Journal Component
Select Journal Component - компонент для выбора значения из журнала.
На вкладке «Базовые» заполняется:
Поле |
Описание |
|---|---|
Название поля (1) |
Имя компонента, как оно будет отражаться на форме. |
Имя свойства (2) |
Имя свойства в типе данных. |
Обязательность поля выставляется отдельным чекбоксом. (3)
На вкладке «Данные» заполняется ID журнала - идентификатор журнала, который будет использовать в компоненте. (4)
Select Orgstruct Component
Select Orgstruct Component - компонент для выбора из оргструктуры.
На вкладке «Базовые» заполняется:
Поле |
Описание |
|---|---|
Название поля (1) |
Имя компонента, как оно будет отражаться на форме. |
Имя свойства (2) |
Имя свойства в типе данных. |
На вкладке «Кастомные» - можно указать:
допустимый «Разрешенный тип полномочий» (3)
Текущий пользователь по умолчанию - настройка, позволяющая подставить в компонент пользователя, который открыл форму на создание (4).
Текущий пользователь по умолчанию
Для автоматической подстановки текущего пользователя используйте currentUserByDefault. Подстановка выполняется для пустого поля, ещё не изменённого пользователем, при options.formMode = 'CREATE' и вне режима чтения. Режим задаётся в options формы; JSON компонента его не устанавливает. Подробные условия см. в настройке текущего пользователя по умолчанию.
Пример JSON-конфигурации:
{
"key": "responsible",
"type": "selectOrgstruct",
"input": true,
"allowedAuthorityType": "USER",
"currentUserByDefault": true,
"defaultValue": ""
}
Примечание
Свойство currentUserByDefault — встроенная настройка компонента selectOrgstruct. Для других типов компонентов используйте customDefaultValue (см. Custom Default Value).
Для выбора подразделения:
Panel
Panel - компонент - заголовок, в который помещаются близкие по смыслу компоненты.
Заполняется «Имя свойства» - имя компонента.
На вкладке «Вид» заполните заголовок панели (title) (2). Ключ компонента (key) и отображаемый заголовок задаются отдельно:
Async Data Component
Async Data Component - асинхронный компонент.
Справочник Грейд (тип данных hr-grades-type) содержит в себе информацию о должности (offerposition), вилке оклада (gradesSalary) и премии (gradesPrize).
При выборе Должности автоматически заполнятся соответствующие ей поля Грейд и Зарплатная вилка и премия:
На вкладке «Асинхронные данные» заполняется:
Название поля - имя компонента, как оно будет отражаться на форме (1).
Тип данных - тип данных (2).
Пояснения к скрипту (3):
emodel/type@hr-grades-type - тип, из которого необходимо получить данные.
gradesSimpleRoleTypeAssoc - сравниваемое свойство типа, из которого получаем данные.
offerPosition - свойство, которое используем для сравнения со свойством типа, из которого получаем данные.
В «Атрибуты» указываются атрибуты, который необходимо получить (4).
На вкладке «Расширенные настройки» заполняется:
Обновлять при -параметр, в котором указывается элемент формы, которые следует отслеживать (5).
На вкладке «API» заполняется:
Имя свойства - имя свойства компонента (6).
Чтобы компонент формы реагировал на асинхронный компонент, необходимо сделать следующие настройки во вкладке «Данные» в компоненте Грейд:
В Обновлять при указать компонент, при изменении которого будет реагировать компонент, для которого необходимо получить данные из асинхронного компонента.
В Вычисляемые значения:
Теперь при выборе Должности в компонент формы «Грейд» в зависимости от значения компонента «Должность», будет автоматически выставлено значение.
Select Hierarchical Component
Компонент Select Hierarchical позволяет выбирать элементы из иерархически организованного справочника. Для его настройки необходимо предварительно подготовить тип данных с самореферентной ассоциацией.
Шаг 1. Подготовить тип данных
В типе данных добавить атрибут — ассоциацию, ссылающуюся на саму себя. При необходимости выставить множественность.
Шаг 2. Добавить компонент на форму
Добавить на форму компонент Select Hierarchical, указав в поле Имя свойства название атрибута из типа данных:
Результат:
Подробно см.
Тип данных через ассоциацию может быть использован в другом типе данных.
Для этого необходимо добавить в другом типе данных атрибут-ассоциацию на тип данных с иерархией
На форме использовать компонент Select Hierarchical, указав в поле Имя свойства название атрибута-ассоциации. На вкладке Кастомные указать иерархический тип данных, который был подготовлен на шаге 1.
Результат:
How to
Сделать компонент нередактируемым
На вкладке «Базовые» включите «Заблокирован ввод» (disabled). Компонент останется видимым, но ввод будет запрещён. Настройка «Скрыть поле» (hidden) скрывает компонент и задаётся отдельно.
Скрыть поле на форме, если оно пустое
Полезно, например, на канбан-доске:
Для текстового поля можно использовать следующий скрипт:
show = !_.isEmpty(value)
Для числовых и логических полей используйте проверку, соответствующую типу данных: _.isEmpty считает пустыми также числа и логические значения. Например, чтобы скрывать поле только при null или undefined:
show = value !== null && value !== undefined;
Статус
На форме документа статус может быть отражен следующим образом:
В компоненте Text field:
название поля может быть любым,
имя свойства - _status,
скрыть и заблокировать на ввод, если необходимо не отображать на форме.
Показывать поле через «логику»
На вкладке «Отображение» перейдите в Расширенные условия отображения:
show = _.get(data, 'asyncDataField.boolAttribute', false);
Вместо asyncDataField и boolAttribute ваши данные. Если нужно, то логику в скрипте можно расширить.
Если необходима логика на несколько атрибутов, то можно использовать компонент Панель. И внутри нее уже разместить нужные атрибуты. Визуально панель можно настроить, чтобы её присустствие никак не отображалось.
Показывать поле только в определенном режиме формы
На вкладке «Отображение» перейдите в Расширенные условия отображения:
const {options} = instance || {};
const {formMode} = options || {};
var isCreateMode = formMode === 'CREATE';
show = !isCreateMode;
где formMode может быть:
CREATE - форма создания;
VIEW - форма просмотра;
EDIT - форма редактирования;
CLONE - форма клонирования.
Условие выше скрывает поле только в CREATE и оставляет видимым в CLONE. Если поле нужно скрывать и при клонировании, учитывайте оба режима.
Автосабмит формы при выборе в списке или чекбоксе
Как настроить автосабмит
Подпишитесь на событие изменения компонента. Не вызывайте отправку из Вычисляемого значения: такое выражение может выполняться при инициализации и нескольких проходах расчёта.
В этом примере автосабмит включается пользователем после загрузки формы:
Добавьте список с ключом
selectWithSubmitи Checkbox с ключомsubmitOnCheckBox.Добавьте кнопку «Включить автосабмит», выберите Действия: Custom. Поля Вычисляемое значение и Обновлять при у этой кнопки оставьте пустыми.
В Button Custom Logic поместите обработчик:
const form = instance.root;
if (!form._autoSubmitOnSelection) {
const keys = new Set(['selectWithSubmit', 'submitOnCheckBox']);
let timer;
let pending = false;
let busy = false;
const flush = () => {
timer = null;
if (!form.element || !form.element.isConnected) {
pending = false;
return;
}
if (!pending || busy) {
return;
}
if (form.submitting) {
timer = setTimeout(flush, 200);
return;
}
pending = false;
busy = true;
Promise.resolve()
.then(() => form.submit())
.catch(error => console.error('Auto-submit failed', error))
.finally(() => {
busy = false;
if (pending) {
timer = setTimeout(flush, 200);
}
});
};
const onChange = event => {
const flags = event && event.flags || {};
if (!event || !keys.has(event.component && event.component.key) ||
!(flags.modified || flags.changeByUser)) {
return;
}
pending = true;
clearTimeout(timer);
timer = setTimeout(flush, 200);
};
form._autoSubmitOnSelection = onChange;
form.on('componentChange', onChange);
}
instance.disabled = true;
Откройте форму и нажмите «Включить автосабмит». Затем пользовательское изменение одного из указанных полей запускает отправку после паузы 200 мс, включая снятие флажка или очистку списка. Обработчик учитывает флаги события modified / changeByUser; обычная программная установка значений без этих флагов не запускает отправку.
Кнопка включения блокируется после регистрации; повторная регистрация на той же форме не создаёт вторую подписку. Параллельные отправки исключены, а изменения во время отправки обрабатываются после её завершения. Ошибки отправки записываются в консоль; после исправления данных следующее изменение поля запускает новую попытку.
Этот пример подходит для самостоятельной формы сохранения записи. Для формы задачи учитывайте, что отправка может завершать задачу, и настраивайте её только как явное действие пользователя.
Как загрузить на форму изображение с внешнего файлового хранилища?
Загрузка изображения с внешнего хранилища
Для автозаполнения полей на форме можно добавить кнопку и настроить «Действия» = Custom. При этом выборе внизу появляется поле для ввода произвольного javascript кода. В это поле можно загрузить нужные данные и проставить их на форму следующим образом:
const submission = instance.root.submission;
instance.root.submission = {
...submission,
data: {
...(submission.data),
// Заполняем поле с файлом
uploadField: contentData,
// Заполняем текстовое поле
textField: 'Размер файла: ' + contentData[0].size
}
};
где
instance - текущий компонент (кнопка);
instance.root - форма, в которой находится наша кнопка;
instance.root.submission - данные формы.
С простыми текстовыми/числовыми/булевыми полями в data можно просто положить требуемое значение. Для полей с контентом нужно предварительно загрузить контент на сервер как временный файл.
const formData = new FormData();
formData.append('file', file);
formData.append('ecosType', 'temp-file');
formData.append('mimeType', file.type);
formData.append('name', file.name);
return ecosFetch('/gateway/emodel/api/ecos/webapp/content', {
method: 'POST',
body: formData
}).then(r => r.json()).then(data => data.entityRef);
где
file - инстанс File - https://developer.mozilla.org/en-US/docs/Web/API/File
В результате этого запроса получим RecordRef временного файла.
Затем нужно из временного файла получить json описание, которое нужно для компонента на форме:
Records.get(tempFile).load('_as.content-data[]?json').then(items =>
items.map(element => ({
...element,
data: { ...(element.data || {}), entityRef: element.recordRef }
}))
);
Полученные данные можно проставить на форму, как показано в первом скрипте.
Пример конфигурации:
Пример типа и формы:
Можно загрузить эти артефакты, открыть журнал http://localhost/v2/journals?journalId=type$example-with-download-and-fill-form-data-type , создать новую сущность и нажать на форме кнопку Download.
Как обеспечить подсветку/выделение текста по флагу?
Подсветка / выделение текста по флагу
Для настройки произвольных стилей внутри формы можно
а) Добавить на форму панель (Макет → Panel), в которую добавить все элементы формы и настроить «Пользовательский CSS класс» на вкладке «Вид», который будет однозначно идентифицировать нашу форму. Это нужно чтобы избежать влияния стилей на другие части системы (назовем этот класс в нашем примере ROOT_PANEL_CLASS).
б) Добавить на форму компонент html (Расширенные → HTML Element), который настраиваем следующим образом:
В вкладке «Базовые» ставим галку на «Скрыть поле»
В вкладке «Вид» в поле «Контент» пишем вначале произвольный текст (это нужно чтобы компонент было видно в редакторе и была возможность его отредактировать) и затем размещаем открывающий и закрывающий тэги <style></style>, внутри которых настраиваем произвольные стили. Чтобы стили работали только в пределах нашей формы нужно их описывать в формате .ROOT_PANEL_CLASS .inner_class { __стили__ }, где ROOT_PANEL_CLASS - класс, который мы настроили в п.1, а inner_class - класс элемента внутри формы.
Для того чтобы по значению флага выделялся некоторый текст можно сделать следующее:
а) Добавить на форму HTML компонент
В поле «Вид» → «Пользовательский CSS класс» вводим класс, который будет однозначно идентифицировать наш html компонент (допустим HTML_TO_HIGHLIGHT)
В поле «Вид» → «Контент» пишем произвольный текст, который будет отображаться пользователю и размечаем части этого текста, которые нужно будет подсветить в зависимости от условий используя классы.
Например:
Текст до <span class="text-to-select">текст для выделения</span> текст после
б) Добавить на форму «Основные компоненты» → Checkbox и делаем его скрытым в «Базовые» → «Скрыть поле» если пользователю его значение знать и менять не нужно.
в) Добавить еще один html компонент:
Выставить «Базовые» → «Скрыть поле» → «Да»
В поле «Вид» → «Контент» написать произвольный текст, чтобы поле было видно в редакторе
Данные → Обновлять при → Checkbox (из пункта б)
Во вкладке «Логика» добавляем новую логику:
Триггер: Простая логика - когда компонент формы Checkbox (из пункта б) равен true.
Действия: Тип - Свойство, Свойство компонента: Content, В появившемся поле Content вводим наши стили внутри тэгов <style></style> не забывая про указание класса из пункта (а), чтобы случайно не поменять вид других частей системы. Например:
<style> .HTML_TO_HIGHLIGHT .text-to-select { color: red; font-weight: bold; } </style>
Во вложении форма с примером настройки: