Skip to content
This repository was archived by the owner on Dec 1, 2023. It is now read-only.

ReadMeRU

Jump to bottom
LightFuri edited this page Apr 15, 2020 · 2 revisions

Оглавление

LeadVertex плагин формы

\Leadvertex\Plugin\Components\Form - компонент, который предназначен для простого создания собственной формы для LeadVertex. Каждая форма разделена на группы полей, которые могут иметь свое имя и описание, и все группы полей имеют свои набор полей со своими именами, описаниями и валидаторами.

Установка

composer require leadvertex/plugin-component-form

Форма

Form это объект, который содержит массив FieldGroups, который, в свою очередь, содержит массив Fields.
Конструктор Form принимает эти значения:

  • title - string название формы.
  • description - string описание формы.
  • fieldGroups - массив FieldGroups.

FieldGroups и Fields

Каждая форма имеет в своем составе массив FieldGroup.
FieldGroup - группа полей, которая имеет свой собственный заголовок, описание и массив с полями.
Каждое поле - один из возможных FieldDefinition. Список всех доступных FieldDefinition:

  • BooleanDefinition - чекбокс.
  • FloatDefinition - число с плавающей запятой.
  • IntegerDefinition - целое число.
  • ListOfEnumDefinition - может иметь пул статических значений и пул динамических значений. Для статических значений вам необходимо настроить пул StaticValues. Для динамических значений вам необходимо настроить пул DynamicValues.
  • StringDefinition - текст.
  • PasswordDefinition - текстовое поле, которое принимает значение string, которое будет проверено в соответствии с правилами пароля.
  • MarkdownDefinition - текстовое поле, которое поддерживает Markdown.
  • FileDefinition - URI, по которому можно получить необходимый файл.

Каждое из этих определений имеет название и описание. Также все Fields имеют свой валидатор и значение по умолчанию. Validator - функция, которая принимает значение для проверки, текущий объект Field и объект FormData.
Например, валидатор для ListOfEnum может выглядеть так:

$validator = function ($values, ListOfEnumDefinition $definition, FormData $data) {
    $limit = $definition->getLimit();                                                                   // Получение текущего Limit для этого поля
    $errors = [];

    if (!is_null($values) && !is_array($values)) {                                                      // Проверка, является ли входной аргумент $values массивом или null
        $errors[] = "Invalid argument";
        return $errors;
    }

    if ($limit) {                                                                                       // Проверка, установлен ли Limit
        if ($limit->getMin() && count($values) < $limit->getMin()) {                                    // Проверка на минимальное количество выбранных значений
            $errors[] = "Number of values is too low. Expected at least {$limit->getMin()} value(s)";
        }
        if ($limit->getMax() && count($values) > $limit->getMax()) {                                    // Проверка на максимальное количество выбранных значений
            $errors[] = "Too many values. Expected maximum of {$limit->getMax()} value(s)";
        }
    }

    if (!is_null($data->get('group_1')['isNew'])) {                                                     // Проверка с зависимостью от другого поля. Если поле isNew в первой группе полей заполнено
         if(!isset($values['static_3']) || is_null($values['static_3'])) {                              // то в выбранных значениях обязательно должно присутствовать значение static_3
             $errors[] = 'static_3 should be picked with static_2';
         }
     }

    return $errors;
};

Для примера, вы можете создать новую FieldGroup с одним String полем следующим образом:

$fieldGroup = new FieldGroup(
    'GroupTitle',                                                           // Заголовок группы
    'GroupDescription',                                                     // Описание группы
    [new StringDefinition('FieldTitle', 'FieldDescription', $validator)]    // Массив полей
);

Markdown

Поле Markdown поддерживает TUI markdown со всеми плагинами.

ListOfEnum

StaticValues/DynamicValues

Поле StaticListOfEnum

Поле StaticListOfEnum имеет предопределенный набор значений, которые можно выбрать.
Набор всех возможных значений необходимо передать в виде объекта StaticValues. Объект StaticValues содержит в себе массив полей, каждое из которых имеет название и группу.
Также в настройки поля можно передать ограничение на количество полей для отправки - задать можно как минимум так и мксимум значений. Для этого необходимо передать объект Limit с указанным минимумом и максимумом выбранных значений. Пример создания Limit, StaticValues и StaticListOfEnum:

$limit = new Limit(1, 2);                       // Поле должно иметь от 1 до 2 выбранных значений

$staticValues = new StaticValues([
    "static_1" => [ 
        'title' => 'Value1',
        'group' => 'Group1'
    ],
    "static_2" => [ 
        'title' => 'Value2',
        'group' => 'Group1'
    ],
    "static_3" => [ 
        'title' => 'Value3',
        'group' => 'Group2'
    ],
]);

$staticListOfEnum = new ListOfEnumDefinition(
    'Field title',                              // Заголовок поля
    'Field description',                        // Описание поля
    $validator,                                 // Валидатор поля
    $staticValues,                              // Список значений для поля
    $limit,                                     // Лимит для выбранных значений в поле
    'static_1'                                  // Поле, выбираемое по умолчанию. Опциональный параметр
);

Поле DynamicListOfEnum

Поле DynamicListOfEnum работает схоже со StaticListOfEnum. Различие заключается в получении списка значений для поля - в DynamicListOfEnum передается объект DynamicValues, который в свою очередь принимает uri, с которого он может получить массив значений в таком же формате, что и для StaticValues. Пример создания DynamicValues и DynamicListOfEnum:

$limit = new Limit(1, 2);                       // Поле должно иметь от 1 до 2 выбранных значений

$dynamicValues = new DynamicValues('http://example.com');

$staticListOfEnum = new ListOfEnumDefinition(
    'Field title',                              // Заголовок поля
    'Field description',                        // Описание поля
    $validator,                                 // Валидатор поля
    $dynamicValues,                             // Список значений для поля
    $limit,                                     // Лимит для выбранных значений в поле
    'dynamic_1'                                 // Поле, выбираемое по умолчанию. Опциональный параметр
);

Создание формы

С помощью FormGroup, которая содержит все необходимые Fields, вы можете создать Form:

$form = new Form(
    'FormTitle',        // Заголовок формы
    'FormDescription',  // Описание формы
    $fieldGroups        // Массив групп полей
);

Теперь вы можете получить доступ ко всем методам формы Form:

  • getTitle() метод для получения заголовка формы.
  • getDescription() метод для получения описания формы.
  • getGroups() метод для получения массива FeldGroups формы.
  • getData() метод для получения значений всех полей заполненной формы. Этот метод возвращает объект FormData.
  • setData() метод для установки значений полей в форме. Этот метож принимает объект FormData.
  • validateData() method to validate all of your fields. This method returns bool value.
  • getErrors() метод для получения всех ошибок, которые возникли в процессе заполнения формы. Этот метод возвращает массив всех ошибок.

Пример простой формы

С помощью кода ниже вы можете создать простую форму, которая будет содержать обязательные для заполнения поля Name и Phone:

// Для начала сделаем необходимый набор полей
$fields = [
    'Name' => new StringDefinition(
        'ФИО',                                                              // Заголовок поля    
        null,                                                               // Описание поля
        function ($value, FieldDefinition $definition, FormData $form) {    // Проверка на наличие значения. Поле становится обязательным для заполнения
            $errors = [];
            if (!is_scalar($value)) {
                $errors[] = 'Поле ФИО обязательно для заполнения';
            }
            return $errors;
        }
    ),
    'Phone' => new StringDefinition(
        'Телефон',                                                          // Заголовок поля    
        null,                                                               // Описание поля
        function ($value, FieldDefinition $definition, FormData $form) {    // Проверка на наличие значения. Поле становится обязательным для заполнения
            $errors = [];
            if (!is_scalar($value)) {
                $errors[] = 'Поле Телефон обязательно для заполнения';
            }
            return $errors;
        }
    ),
];

// Далее создадим группу для этих полей
$fieldGroup = new FieldGroup(
    'Заказ',                                    // Заголовок группы
    'Оставьте данные для оформления заказа',    // Описание группы
    $fields                                     // Массив полей
);

// После этого можно создать форму
$form = new Form(
    'Форма заказа',                             // Заголовок формы
    'Пук',                                      // Описание формы
    [$fieldGroup],                              // Массив из групп полей
    'Отправить'                                 // Текст, который будет написан на кнопке отправки формы
);

Clone this wiki locally