Примеры компонент. How to

В данном разделе собраны практические примеры настройки компонент форм платформы Citeck, а также типовые сценарии («How to») — скрипты и конфигурации для решения часто встречающихся задач: управление видимостью полей, автозаполнение, обработка событий и другие.

Columns

Компонент Columns позволяет удобно расположить компоненты формы.

../../../_images/columns_1.png

Свойства столбца - основной параметр настройки, позволяет определить как по колонкам будет разбиваться компонент. Компонент основан на использовании Bootstrap Grid.

../../../_images/columns_2.png

На вкладке «Вид» в разделе Свойства столбца указать количество столбцов и их размер.

../../../_images/columns_3.png

Далее нажать «Сохранить». Результат:

../../../_images/columns_4.png

Text field

Text field - текстовый компонент.

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

Поле

Описание

Название поля (1)

Имя компонента, как оно будет отражаться на форме.

Имя свойства (2)

Имя свойства в типе данных.

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

../../../_images/Text_field_1.png

Автофокус - автоматическая устанавка курсора ввода, без необходимости кликать на него мышью:

../../../_images/Text_field_2.png

ECOS Select Component

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

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

Поле

Описание

Название поля (1)

Имя компонента, как оно будет отражаться на форме.

Имя свойства (2)

Имя свойства в типе данных.

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

../../../_images/ECOS_Select_1.png

На вкладке «Данные» в «Типе источника данных» выбрать Values (1).

Data Source Values заполняется значениями, которые должны быть для выбора в списке (2):

Поле

Описание

Название поле

Отображаемое имя.

Значение

Значение, которое содержится.

../../../_images/ECOS_Select_2.png

Date / Time Component

Date / Time Component - компонент даты / времени.

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

Поле

Описание

Название поля (1)

Имя компонента, как оно будет отражаться на форме.

Имя свойства (2)

Имя свойства в типе данных.

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

../../../_images/Date_Time_1.png

На вкладке «Вид» указать формат даты (5) и возможность ручного ввода (4).

../../../_images/Date_Time_2.png

Для изменения формата даты/времени перейдите во вкладку - вкладка «Вид» - Формат:

../../../_images/Date_Time_3.png

Значение по умолчанию — текущая дата

Для установки текущей даты в качестве значения по умолчанию используйте свойство 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)

../../../_images/Select_Journal_1.png

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

../../../_images/Select_Journal_2.png

Select Orgstruct Component

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

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

Поле

Описание

Название поля (1)

Имя компонента, как оно будет отражаться на форме.

Имя свойства (2)

Имя свойства в типе данных.

../../../_images/form_4.png

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

  • допустимый «Разрешенный тип полномочий» (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).

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

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

../../../_images/form_5_1.png

Button Component

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

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

Поле

Описание

Название поля (1)

Наименование кнопки, как оно будет отражаться на форме.

Имя свойства (2)

Имя свойства кнопки.

Действия (3)

Указать действие кнопки.

../../../_images/button.png

Для отображения кнопки на всю ширину ячейки на вкладке «Вид» включите настройку block. Она задаёт ширину кнопки; запрет нажатия настраивается отдельно через disabled («Заблокирован ввод»).

../../../_images/button_1.png

Panel

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

../../../_images/form_210.png

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

../../../_images/form_3.png

На вкладке «Вид» заполните заголовок панели (title) (2). Ключ компонента (key) и отображаемый заголовок задаются отдельно:

../../../_images/form_141.png

Async Data Component

Async Data Component - асинхронный компонент.

../../../_images/form_12_1.png

Справочник Грейд (тип данных hr-grades-type) содержит в себе информацию о должности (offerposition), вилке оклада (gradesSalary) и премии (gradesPrize).

При выборе Должности автоматически заполнятся соответствующие ей поля Грейд и Зарплатная вилка и премия:

../../../_images/form_6.png

На вкладке «Асинхронные данные» заполняется:

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

  • Тип данных - тип данных (2).

../../../_images/form_7.png

Пояснения к скрипту (3):

../../../_images/form_8.png
  • emodel/type@hr-grades-type - тип, из которого необходимо получить данные.

  • gradesSimpleRoleTypeAssoc - сравниваемое свойство типа, из которого получаем данные.

  • offerPosition - свойство, которое используем для сравнения со свойством типа, из которого получаем данные.

В «Атрибуты» указываются атрибуты, который необходимо получить (4).

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

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

../../../_images/form_9.png

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

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

../../../_images/form_10.png

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

../../../_images/form_11.png

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

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

../../../_images/form_12.png

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

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

Select Hierarchical Component

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

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

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

../../../_images/Hierarchical_011.png

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

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

Результат:

../../../_images/Hierarchical_04.png

Подробно см.

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

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

../../../_images/Hierarchical_08.png

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

Результат:

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

How to

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

На вкладке «Базовые» включите «Заблокирован ввод» (disabled). Компонент останется видимым, но ввод будет запрещён. Настройка «Скрыть поле» (hidden) скрывает компонент и задаётся отдельно.

../../../_images/form_13.png

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

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

../../../_images/form_15.png

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

show = !_.isEmpty(value)

Для числовых и логических полей используйте проверку, соответствующую типу данных: _.isEmpty считает пустыми также числа и логические значения. Например, чтобы скрывать поле только при null или undefined:

show = value !== null && value !== undefined;

Статус

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

../../../_images/form_status1.png

В компоненте 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 - форма редактирования;

  • CLONE - форма клонирования.

Условие выше скрывает поле только в CREATE и оставляет видимым в CLONE. Если поле нужно скрывать и при клонировании, учитывайте оба режима.

Автосабмит формы при выборе в списке или чекбоксе

Как настроить автосабмит

Подпишитесь на событие изменения компонента. Не вызывайте отправку из Вычисляемого значения: такое выражение может выполняться при инициализации и нескольких проходах расчёта.

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

  1. Добавьте список с ключом selectWithSubmit и Checkbox с ключом submitOnCheckBox.

  2. Добавьте кнопку «Включить автосабмит», выберите Действия: Custom. Поля Вычисляемое значение и Обновлять при у этой кнопки оставьте пустыми.

  3. В 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; обычная программная установка значений без этих флагов не запускает отправку.

Кнопка включения блокируется после регистрации; повторная регистрация на той же форме не создаёт вторую подписку. Параллельные отправки исключены, а изменения во время отправки обрабатываются после её завершения. Ошибки отправки записываются в консоль; после исправления данных следующее изменение поля запускает новую попытку.

Этот пример подходит для самостоятельной формы сохранения записи. Для формы задачи учитывайте, что отправка может завершать задачу, и настраивайте её только как явное действие пользователя.

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(items =>
  items.map(element => ({
    ...element,
    data: { ...(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 с данными формы