Примеры компонент. 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();

При открытии формы на создание поле будет автоматически заполнено текущей датой.

Select Journal Component

Select Journal Component - компонент для выбора значения из журнала.

На вкладке «Базовые» заполняется:

  • Название поля - имя компонента, как оно будет отражаться на форме (1).

  • Имя свойства - имя свойства в типе данных (2).

Обязательность поля выставляется отдельным чекбоксом. (3)

На вкладке «Данные» заполняется ID журнала - идентификатор журнала, который будет использовать в компоненте. (4)

Select Orgstruct Component

Select Orgstruct Component - компонент для выбора из оргструктуры.

На вкладке «Базовые» заполняется:

  • Название поля - имя компонента, как оно будет отражаться на форме (1).

  • Имя свойства - имя свойства в типе данных (2).

На вкладке «Кастомные» - можно указать:

  • допустимый «Разрешенный тип полномочий» (3)

  • Текущий пользователь по умолчанию - настройка, позволяющая подставить в компонент пользователя, который открыл форму на создание (4).

Текущий пользователь по умолчанию

Для автоматической подстановки текущего пользователя при создании записи используйте свойство currentUserByDefault. Настройка работает только в режиме создания формы (formMode = CREATE).

Пример JSON-конфигурации:

{
  "key": "responsible",
  "type": "selectOrgstruct",
  "input": true,
  "allowedAuthorityType": "USER",
  "currentUserByDefault": true,
  "defaultValue": ""
}

Примечание

Свойство currentUserByDefault — встроенная настройка компонента selectOrgstruct. Для других типов компонентов используйте customDefaultValue (см. Custom Default Value).

../../../_images/form_5.png

Для выбора подразделения:

Button Component

Button Component - компонент для добавления кнопок для выполнения различных действий в форме.

На вкладке «Базовые» заполняются:

  • Название поля - наименование кнопки, как оно будет отражаться на форме (1).

  • Имя свойства - имя свойства кнопки (2).

  • Действия - указать действие кнопки (3)

Для отображения кнопки на всю ширину ячейки необходимо на вкладке «Вид» выставить чекбокс «Блокировать»:

Panel

Panel - компонент - заголовок, в который помещаются близкие по смыслу компоненты.

Заполняется «Имя свойства» - имя компонента.

И на вкладке «Вид» заполнить «Название свойства» (2):

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).

Чтобы компонент формы реагировал на асинхронный компонент, необходимо сделать следующие настройки во вкладке «Данные» в компоненте Грейд:

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

В Вычисляемые значения:

Теперь при выборе Должности в компонент формы «Грейд» в зависимости от значения компонента «Должность», будет автоматически выставлено значение.

Подробнее об Async Data

Select Hierarchical Component

Компонент Select Hierarchical позволяет выбирать элементы из иерархически организованного справочника. Для его настройки необходимо предварительно подготовить тип данных с самореферентной ассоциацией.

Шаг 1. Подготовить тип данных

В типе данных добавить атрибут — ассоциацию, ссылающуюся на саму себя. При необходимости выставить множественность.

Шаг 2. Добавить компонент на форму

Добавить на форму компонент Select Hierarchical, указав в поле Имя свойства название атрибута из типа данных:

Результат:

Подробно см.

Тип данных через ассоциацию может быть использован в другом типе данных.

Для этого необходимо добавить в другом типе данных атрибут-ассоциацию на тип данных с иерархией

На форме использовать компонент Select Hierarchical, указав в поле Имя свойства название атрибута-ассоциации. На вкладке Кастомные указать иерархический тип данных, который был подготовлен на шаге 1.

Результат:

../../../_images/Hierarchical_05.png

How to

Сделать компонент нередактируемым

  • вкладка «Вид» - Скрыть поле - делает компонент нередактируемым.

Скрыть поле на форме, если оно пустое

Полезно, например, на канбан-доске:

Текст скрипта:

show = !_.isEmpty(value)

Статус

На форме документа статус может быть отражен следующим образом:

В компоненте Text field:

  • название поля может быть любым,

  • имя свойства - _status,

  • скрыть и заблокировать на ввод, если необходимо не отображать на форме.

Показывать поле через «логику»

На вкладке «Отображение» перейдите в Расширенные условия отображения:

../../../_images/form_mode_1.png 
show = _.get(data, 'asyncDataField.boolAttribute', false);

Вместо asyncDataField и boolAttribute ваши данные. Если нужно, то логику в скрипте можно расширить.

Если необходима логика на несколько атрибутов, то можно использовать компонент Панель. И внутри нее уже разместить нужные атрибуты. Визуально панель можно настроить, чтобы её присустствие никак не отображалось.

Показывать поле только в определенном режиме формы

На вкладке «Отображение» перейдите в Расширенные условия отображения:

../../../_images/form_mode.png 
const {options} = instance || {};
const {formMode} = options || {};
var isCreateMode = formMode === 'CREATE';

show = !isCreateMode;

где formMode может быть:

  • CREATE - форма создания;

  • VIEW - форма просмотра;

  • EDIT - форма редактирования

Обработка результатов формы по элементам чекбокс, выпадающим спискам / submit для выпадающих списков checkbox

Для того чтобы при выборе элемента в выпадающем списке или при клике на чекбокс происходил сабмит формы можно на submit кнопке во вкладке «Данные»:

  1. В поле «Обновлять при» добавить зависимость от компонентов на форме, изменение которых нам интересно.

  2. В поле «Вычисляемые значения» добавить логику для срабатывания авто-сабмита:

if (data.selectWithSubmit || data.submitOnCheckBox) {
instance.root.submit();
}

где

  • data - данные формы;

  • selectWithSubmit и submitOnCheckbox - ключи компонентов на форме;

  • instance - текущий компонент (кнопка);

  • instance.root - текущая форма, в которой добавлена кнопка.

Пример конфигурации:

../../../_images/submit-on-select.png

json с данными формы

Как загрузить на форму изображение с внешнего файлового хранилища?

Для автозаполнения полей на форме можно добавить кнопку и настроить «Действия» = 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);

где

В результате этого запроса получим RecordRef временного файла.

Затем нужно из временного файла получить json описание, которое нужно для компонента на форме:

Records.get(tempFile).load('_as.content-data[]?json').then(it => it.map(element => {
element.data = { 'entityRef': element.recordRef };
}));

Полученные данные можно проставить на форму, как показано в первом скрипте.

Пример конфигурации:

../../../_images/download-and-fill.png

Пример типа и формы:

yaml с данными типа

json с данными формы

Можно загрузить эти артефакты, открыть журнал http://localhost/v2/journals?journalId=type$example-with-download-and-fill-form-data-type , создать новую сущность и нажать на форме кнопку Download.

Как обеспечить подсветку/выделение текста по флагу?

  1. Для настройки произвольных стилей внутри формы можно

    а) Добавить на форму панель (Макет → Panel), в которую добавить все элементы формы и настроить «Пользовательский CSS класс» на вкладке «Вид», который будет однозначно идентифицировать нашу форму. Это нужно чтобы избежать влияния стилей на другие части системы (назовем этот класс в нашем примере ROOT_PANEL_CLASS).

    б) Добавить на форму компонент html (Расширенные → HTML Element), который настраиваем следующим образом:

    1. В вкладке «Базовые» ставим галку на «Скрыть поле»

    2. В вкладке «Вид» в поле «Контент» пишем вначале произвольный текст (это нужно чтобы компонент было видно в редакторе и была возможность его отредактировать) и затем размещаем открывающий и закрывающий тэги <style></style>, внутри которых настраиваем произвольные стили. Чтобы стили работали только в пределах нашей формы нужно их описывать в формате .ROOT_PANEL_CLASS .inner_class { __стили__ }, где ROOT_PANEL_CLASS - класс, который мы настроили в п.1, а inner_class - класс элемента внутри формы.

  2. Для того чтобы по значению флага выделялся некоторый текст можно сделать следующее:

    а) Добавить на форму HTML компонент

    1. В поле «Вид» → «Пользовательский CSS класс» вводим класс, который будет однозначно идентифицировать наш html компонент (допустим HTML_TO_HIGHLIGHT)

    2. В поле «Вид» → «Контент» пишем произвольный текст, который будет отображаться пользователю и размечаем части этого текста, которые нужно будет подсветить в зависимости от условий используя классы.

    Например:

    Текст до <span class="text-to-select">текст для выделения</span> текст после

    б) Добавить на форму «Основные компоненты» → Checkbox и делаем его скрытым в «Базовые» → «Скрыть поле» если пользователю его значение знать и менять не нужно.

    в) Добавить еще один html компонент:

    1. Выставить «Базовые» → «Скрыть поле» → «Да»

    2. В поле «Вид» → «Контент» написать произвольный текст, чтобы поле было видно в редакторе

    3. Данные → Обновлять при → Checkbox (из пункта б)

    4. Во вкладке «Логика» добавляем новую логику:

    Триггер: Простая логика - когда компонент формы Checkbox (из пункта б) равен true.

    Действия: Тип - Свойство, Свойство компонента: Content, В появившемся поле Content вводим наши стили внутри тэгов <style></style> не забывая про указание класса из пункта (а), чтобы случайно не поменять вид других частей системы. Например:

    <style>
.HTML_TO_HIGHLIGHT .text-to-select {
color: red;
font-weight: bold;
}
</style>

Во вложении форма с примером настройки:

json с данными формы