Добавление полей формы
========================

На этом шаге мы наполняем форму полями ввода.
Поля добавляются в соответствии со структурой данных ордера.

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

.. important::

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


Общий принцип добавления полей
------------------------------

Добавление любого поля на форму выполняется по одному и тому же принципу:

1. Выделяется нужная ячейка таблицы.
2. В панели **«Компоненты»** кликом выбирается необходимый компонент.
3. Компонент добавляется в выбранную ячейку.
4. В свойствах компонента выполняется его настройка.

**Здесь мы рассмотрим создание полей на нескольких примерах прямо из ордера.**

Шаги добавления полей на форму
------------------------------
**Шаг 1.** В левую колонку таблицы добавляем компонент **«Неизменяемый текст»**. Для ускорения процесса можно добавить сначала сразу все наименования полей, затем перейти к компонентам. 

**Шаг 2.** В правую колонку добавляем компонент в зависимости от типа данных, указанного в ордере:

* Номер заявки — компонент **«Номер»**.
* Справочные значения — **«Выпадающий список»**.
* Выбор одного варианта — **«Переключатель вариантов»**.
* Текстовые данные — **«Однострочное поле»**.
* Комментарии — **«Многострочный текст»**.
* Файлы - компонент **«Файл»**

**Шаг 3.** Для каждого поля во вкладке **«Свойства»**:

* Задаем код поля (читаемый и содержащий смысловую нагрузку предназначения поля)
* При необходимости отмечаем обязательность 

Поле 1. Порядковый номер заявки
-------------------------------

**Шаг 1.** В левой ячейке таблицы добавляем компонент **«Неизменяемый текст»**,
который используется для отображения названия поля.

В поле **«Надпись»** указывается название 
**«Порядковый номер заявки»**. При необходимости добавляем перевод.

.. figure:: ../resources/img/field_label_static_text.png

   Название поля с использованием компонента «Неизменяемый текст»

**Шаг 2.** В правой ячейке добавляется компонент **«Номер»** из раздела
**«Специальные»**.

Данный компонент будет использовать шаблон номера,
к созданию которого мы перейдем позже.

.. figure:: ../resources/img/field_counter.png

   Компонент «Номер» для порядкового номера заявки

Не забываем поменять код поля на читаемый и содержащий смысл.


Добавление строк в таблицу
--------------------------

Для добавления следующего поля необходимо добавить новую строку в таблицу.

Добавление строки выполняется с помощью стрелки **«вниз»**,
расположенной внизу таблицы.

.. figure:: ../resources/img/add_table_row.png

   Добавление новой строки в таблицу


Поле 2. Статус заявки
--------------------

Поле «Статус заявки» имеет тип данных **«Справочник»**.

**Шаг 1.** В левую ячейку добавляем компонент **"Неизменяемый текст"** и указываем название поле "Статус заявки"

**Шаг 2.** В правую ячейку из раздела "Элементы выбора" добавляем компонент **"Выпадающий список"**


.. figure:: ../resources/img/field_dropdown.png

   Компонент «Выпадающий список»

Настройка возможных значений выполняется во вкладке **«Элементы»**.

Список значений может быть:

* создан вручную с помощью кнопки «Добавить ряд данных»;
* выбран из уже существующих справочников системы.

В режиме заполнения пользователю отображаются значения из столбца
«Наименование», а системным значением является значение из столбца
«Значение».


.. admonition:: Компонент «Выпадающий список» имеет следующие настройки:
    
    * **«Обязательное поле»** - пока не работает
    * **«Заблокировать от изменений пользователем»** - блокирует выбор значения из справочника пользователем во время редактирования заявки.
    * **«Шифровать данные»** используется для защиты конфиденциальной информации. Если опция включена, значения поля сохраняются в системе в зашифрованном виде и недоступны для чтения вне платформы. Шифрование включается галочкой в настройках компонента формы. Для пользователей работа с полем не меняется - данные автоматически шифруются при сохранении и расшифровываются при просмотре. Примечание: Для работы функционала необходимо попросить администратора платформы включить использование шифрования.
    * **«Позволять поиск»** позволяет найти нужное значение в справочнике
    * **«Связь с компонентом»** позволяет связывать справочники между собой, для фильтрации определенных значений в зависимости от другого справочника.
    
Объект приложения "Справочник"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Справочник — это отдельный объект приложения, представляющий собой таблицу со списком значений, которая используется в компонентах выбора (выпадающие списки, переключатели вариантов и т.д.).

Справочник нужен, чтобы:

* не вводить одни и те же значения каждый раз;
* избежать ошибок и опечаток;
* использовать единые значения во всех формах и процессах;
* управлять логикой процесса (условия, переходы, фильтрация).

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

Создание справочника:
^^^^^^^^^^^^^^^^^^^^^^
**Шаг 1.** В дереве приложения кликаем правой кнопкой мыши по нужной папке.

**Шаг 2.** Выбираем: Добавить → Базовые сущности → Справочник

.. figure:: ../resources/img/create_dict.jpeg

**Шаг 3.** В открывшемся окне указываем:

* **Наименование справочника** (например, «Статус заявки»);
* **Код справочника** — интуитивно понятный (можно оставить автоматически сгенерированный транслит).

**Шаг 4.** Ниже отображается таблица колонок справочника. Эта таблица определяет, какие колонки будет иметь справочник.
Добавляем минимум одну строку таблицы, указав:

* Наименование колонки;
* Код колонки.

Пример:

* Наименование → status_name
* Код → status_code

.. figure:: ../resources/img/dict_table.jpeg

При необходимости, отмечаем галочкой столбец «Перевод» если нужно добавить переводы значений.

**Шаг 5.** Сохраняем справочник

Справочник создан. После сохранения рядом с кнопкой "Сохранить" появляется вкладка "Элементы".

.. image:: ../resources/img/dict_elements.jpeg

Переходим к добавлению значений в справочник

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

**Шаг 1.** Переходим во вкладку **"Элементы"**

**Шаг 2.** Нажимаем кнопку «+» на верхней панели – добавляются пустые строки

**Шаг 3.** Заполняем значения в созданных колонках

.. figure:: ../resources/img/dict_final.jpeg

Привязка справочника к полю на форме:
^^^^^^^^^^^^^^^^^^^^^^

**Шаг 1.** Возвращаемся в форму заявки

**Шаг 2.** Кликаем по компоненту «Выпадающий список» в соответствующем поле (например "Статус заявки")

**Шаг 3.** Переходим во вкладку «Элементы» в свойствах компонента

**Шаг 4.** В выпадающем списке выбираем созданный справочник. 

* В столбце "Наименование" выбираем колонку "Наименование статуса".  
* В столбце "Значение" выбираем колонку "Код статуса"

.. figure:: ../resources/img/dropdown_settings.jpeg

**Шаг 5.** Нажимаем "ОК"

Поле 3. Тип заявителя
--------------------
Для поля «Тип заявителя» мы используем компонент **«Переключатель вариантов»**. Т.к в данном случае предполагается использование компонента, позволяющее выбрать только один возможный вариант.

Переключатель вариантов по своим настройкам похож на компонент «Выпадающий список», внутри него так же используется вложенный справочник, либо возможные значения заполняются вручную по нажатию на вкладку **«Элементы»**

**Шаг 1.** На форме в нужной строке добавляем компонент **«Переключатель вариантов»**.

**Шаг 2.** Кликаем по компоненту и переходим в его настройки.

**Шаг 3.** Открываем вкладку **«Элементы»**.

**Шаг 4.** В таблице ниже добавляем возможные варианты:

* указываем наименование значения («ЮЛ», «ИП»);

* задаём соответствующее значение (код, может быть как числовым так и буквенным).

.. figure:: ../resources/img/type_of_applicant_example.jpeg

**Шаг 5.** После указания всех необходимых значений нажимаем «ОК».

Поля 4,5,6,7,8,9: «БИН организации», «ИИН индивидуального предпринимателя», «Наименование организации или индивидуального предпринимателя», «ФИО Руководителя организации», «Номер телефона», «Адрес электронной почты»
--------------------

Поля 4–9 предназначены для ввода идентификационных и контактных данных заявителя.
Все эти значения представляют собой короткий текст, вводимый в одну строку, поэтому для них используется компонент **«Однострочное поле**.

Компонент **«Однострочное поле»** позволяет вводить и отображать произвольное текстовое значение в одну строку (без абзацев) и подходит для таких данных, как:

* идентификаторы (БИН, ИИН);

* наименования и ФИО;

* номер телефона;

* адрес электронной почты.

.. figure:: ../resources/img/field_text_input.png

   Компонент «Однострочное поле»

.. admonition:: Для компонента «Однострочное поле» доступны следующие настройки:

 * **Обязательное поле** — делает поле обязательным для заполнения;
 * **Заблокировать от изменений** — запрещает пользователю изменять значение;
 * **Шифровать данные** — шифрует введенные значения;
 * **Маска ввода** — ограничивает формат вводимых данных;
 * **Плейсхолдер** — отображает подсказку внутри пустого поля.

**Шаг 1.** Для каждого из полей 4-9 добавляем в правую ячейку компонент **"Однострочное поле"**

**Шаг 2.** В настройках каждого компонента присваем читаемый и логичный код поля.

**Шаг 3.** Отмечаем галочку «Обязательное поле» — согласно звёздочке в ордере рядом с названием поля.

**Шаг 4.** Отмечаем галочку "Заблокировать от изменений" тем полям, у которых в примечании ордера указано что поля заполняются автоматически.

Настройки формата (маска ввода и регулярные выражения)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
⚠️ Маска ввода настраивается отдельно для каждого компонента.

1. Формат полей **"ИИН индивидуального предпринимателя" и "БИН организации"**

**Шаг 1.** В настройках компонента включаем галочку **«Маска ввода»**

.. figure:: ../resources/img/input_mask.jpeg

**Шаг 2.** В октрывшемся поле открываем настройки маски ввода кликнув по иконке настроек 

.. image:: ../resources/img/input_mask_icon.jpeg

**Шаг 3.** В таблице с настройками для задания формата 12-значного числового значения используем маску ############. 

Маску можно:

 * Ввести вручную
 * Кликом по строке в предложенной таблице

.. figure:: ../resources/img/input_mask_settings.jpeg

2. Формат поля **"Номер телефона"**

**Шаг 1.** Для поля «Номер телефона» также включаем настройку «Маска ввода».

**Шаг 2.** В маске указываем формат с фиксированными символами, например: +7 (###) ###-##-##

Фиксированные символы (например, +7) будут:

* автоматически подставляться;

* недоступны для удаления или изменения пользователем.

Это позволяет обеспечить корректный формат ввода номера телефона.

3. Настройки формата поля **"Электронная почта"**

Для поля «Адрес электронной почты» требуется строгая проверка формата.

**Шаг 1.** Включаем настройку «Маска ввода».

**Шаг 2.** После этого становится доступна дополнительная галочка **Регулярное выражение** - отмечаем её

.. figure:: ../resources/img/regular_expression.jpeg

**Шаг 3.** Нажимаем на иконку настроек в поле **Маска ввода** 

.. image:: ../resources/img/input_mask_icon.jpeg

**Шаг 4.** В открывшемся окне выбираем готовый шаблон формата e-mail из списка доступных регулярных выражений.

.. figure:: ../resources/img/regex_settings.jpeg

**Шаг 5.** Нажимаем "Ок"

.. note::

 При ручном редактировании регулярного выражения для применения изменений необходимо нажать Enter.
 
Поле 10, 11. Регион и Вид услуги
--------------------
Для полей «Регион» и "Вид услуги" нам необходим компонент **«Выпадающий список»**, добавляем его и настраиваем уже известным нам способом - аналогично полю «Статус заявки».

Поле 12. Тип подписки
--------------------
Справочником, помимо выпадающего списка, может также являться список отдельных записей реестра. Для этого:

**Шаг 1.** Добавить компонент **"Ссылка на реестр"** из раздела "Специальные"

**Шаг 2.** Создать в системе реестр, который будет использоваться как справочный (к этому мы перейдем чуть позже)

Поле 13. Комментарий клиента
--------------------

Поле **«Комментарий клиента»** предназначено для ввода развернутого текстового описания со стороны заявителя.
В отличие от других текстовых полей, здесь предполагается возможность ввода нескольких строк текста с абзацами.

Для этого используется компонент «Многострочный текст», который позволяет вводить неограниченное количество текста и сохранять структуру комментария.

**Шаг 1.** В ячейку добавляем компонент "Многострочный текст"

**Шаг 2.** При необходимости включаем настройку:

**«Не удалять пробелы в начале строки»**, если важно сохранить форматирование и структуру текста, вводимого пользователем.

.. admonition:: Компонент **«Многострочный текст»** предназначен для работы с большим объёмом текста и содержит следующие настройки:

 * **Обязательное поле** — делает поле обязательным для заполнения.
 * **Заблокировать от изменений пользователем** — запрещает редактирование поля пользователем в режиме изменения заявки.
 * **Шифровать данные** — шифрует введенные значения.
 * **Не удалять пробелы в начале строки** — позволяет сохранить форматирование текста и структуру абзацев, не объединяя текст в одну сплошную строку.

Поле 14. Способ связи
--------------------

Поле **«Способ связи»** предназначено для указания предпочтительных каналов связи с заявителем (например, телефон, электронная почта и т.д.).

По логике процесса данное поле должно позволять выбор нескольких значений одновременно, поэтому тип данных поля — чекбокс.

Для реализации такого поведения используется компонент **«Выбор вариантов»**.

**Шаг 1.** Рядом с названием поля «Способ связи» добавляем компонент **"Выбор вариантов"**

**Шаг 2.** Кликаем по компоненту и переходим в его свойства

**Шаг 3.** Открываем вкладку «Элементы»

**Шаг 4.** В выпадающем списке «Справочник»:

* выбираем существующий справочник со способами связи,
или

* оставляем значение «Нет» и добавляем варианты вручную.

**Шаг 5.** При ручном добавлении:

* указываем наименование каждого варианта;

* задаём значение (код, буквенный или числовой).

.. figure:: ../resources/img/checkbox_settings.jpeg

**Шаг 6.** После указания всех необходимых вариантов нажимаем «ОК».

.. note::
 Для понимания логики выбора компонента важно различать элементы выбора:
 **Выпадающий список:**
 Представляет собой раскрывающийся список и позволяет выбрать только одно значение из предложенных вариантов.

 **Переключатель вариантов:**
 Представляет собой видимый список вариантов и также позволяет выбрать только одно значение, переключаясь между ними.

 **Выбор вариантов:**
 Представляет собой видимый список вариантов и позволяет выбрать несколько значений одновременно, отмечая их галочками.
 
Поле 15. Прикрепить документы (доументы компании/ТЗ/отчеты и т.д) 
--------------------
Поле **«Прикрепить документы»** предназначено для загрузки одного или нескольких файлов, относящихся к заявке (документы компании, техническое задание, отчёты и другие вложения).

Согласно ордеру, данное поле должно позволять динамически добавлять несколько файлов, поэтому оно реализуется в виде динамической таблицы.

Для этого поле выносится в отдельный компонент «Таблица», внутри которого будет размещён компонент «Файл».

**Шаг 1.** Добавляем на форму компонент "Таблица"

**Шаг 2.** В данном случае ячейки таблицы можно не делить на колонки — достаточно одной колонки.

**Шаг 3.** В настройках таблицы включаем параметры:
* **«Добавлять строки в режиме заполнения»;**

* **«Добавить заголовок динамической таблицы».**

**Шаг 4.** В появившейся строке заголовка:

* вводим название поля «Прикрепить документы»;

* выравниваем текст по центру.

**Шаг 5.** Во вторую строку таблицы добавляем компонент **«Файл»** и также выравниваем его по центру.

**Шаг 6.** В настройках компонента «Файл» включаем:

* **«Открывать выбор файла с устройства»**,
так как у пользователей будет остуствовать доступ к хранилищу.

.. figure:: ../resources/img/dynamic_table.jpeg

**Шаг 7.** В настройке **«Расширенные форматы файлов»** указываем допустимые форматы:

* DOCX
* PDF
* XLSX

.. admonition:: Настройки компонента **«Файл»**

    Компонент содержит следующие настройки:

    * **Обязательное поле** — делает загрузку файла обязательной.

    * **Заблокировать от изменений пользователем** — запрещает изменение файла при редактировании заявки.

    * **Отображать полный путь к файлу при загрузке из хранилища** — отображает полный путь к файлу из хранилища проекта.

    * **Отображать содержимое загруженного файла** — вместо ссылки отображает содержимое файла (актуально для изображений).

    * **Открывать выбор файла с устройства** — ограничивает выбор источника только файлами с устройства.

    * **Открывать выбор файла с хранилища** — ограничивает выбор источника только файлами из хранилища.

    * **Позволять создание нового документа** — открывает модальное окно для создания нового файла.

    * **Расширенные форматы файлов** — позволяет ограничить список допустимых форматов файлов.
    
    

.. seealso::

   Дополнительную информацию касательно всех полей и их особенностей можно найти в официальной документации:
   http://rtd.lan.arta.kz/docs/docs-po-platforme-arta-synergy/ru/latest/form/components.html


Результат этапа
---------------

По завершении данного этапа:

* все поля заявки добавлены на форму;
* каждому полю соответствует правильный тип компонента;
* форма готова к настройке форматных ограничений и логики отображения.


