form-dispatcher

Forms v0.1.0

Что делает:

Работа с формой: Валидация, Отправка и Обработка ответа сервера

1. Отправка формы только после валидации
2. Текст ошибок с переводом(при помощи функции перевода в шаблоне)
3. Вывод ошибок от сервера под соответствующими полями
4. Сообщение от сервера в отдельном div (красные и зеленые)
5. Показать сообщение об успехе (сверстанное заранее в шаблоне)
6. Редирект на url полученный с сервера
7. Вставка другого шаблона и повторный вызов на новой форме валидации-отправки-обработки
8. Скрыть внешнюю кнопку отправки формы

Главный, управляющий класс - form_dispatcher/index.js - FormDispatcher Он импортирует еще 3 класса и создает их экземпляры:

1. form_dispatcher/classes/validate.js - Validate Валидация формы перед отправкой
2. form_dispatcher/classes/send_form.js - SendForm Отправка формы
3. form_dispatcher/classes/handler_answer.js - HandlerAnswer Обработчик ответа от сервера, выполняет разные действие в зависимости от ответа.

Использование: (new FormDispatcher($('.js--validate_form'), { formSelector: '.js--validate_form' })).init();

Не забыть заменить ajaxTest на ajax в form_dispatcher/classes/send_form.js - сделал для тестирования. И удалить template_test.js - это имитация получения шаблона с сервера.

Каждый класс можно использовать отдельно: только валидация или только отправка. HandlerAnswer также можно использовать отдельно.

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

1. ('validate', 'send', { token, $form: this.$form })
2. ('sendForm', 'beforeSend')
3. ('sendForm', 'success', { rsp });
4. ('sendForm', 'complete')
5. ('sendForm', 'error', { rsp });
6. ('handlerAnswer', 'pastTemplate', { template: $template })

Валидация

Во время импорта файла form_dispatcher/classes/validate.js устанавливается дополнительные плагины в jquery: validateForm, destroyValidateForm, resetForm. Так что можно использовать валидацию прямо на jquery-элементе.

Инициализировать проверку: $(selector).validateForm(); или validate = new Validate(selector); validate.init();

Очистка формы: $(selector).resetForm();

Удаление валидации с формы (если больше не используется форма): $(selector).destroyValidateForm(); Чтобы нельзя было отправить неправильную форму до загрузки js, лучше все элементы формы обернуты в <fieldset> с аттрибутом disabled, после загрузки валидации разблокирует форму (нужно указать класс в data-lock-class)

Использует для настройки поведения следующие аттрибуты:

1. data-lock-class - разблокирование fieldset элемента, указать класс
2. $('body').data('recaptcha_key')
3. на input: data(valid-${type}) - тип, правило проверки поля
4. на input: data(error-${type}) - текст ошибки по данному правилу, можно использовать функцию перевода шаблонизатора
5. на form: validate - экземпляр валидации

Действия после валидации Если есть ошибки добавляет соответствующие классы и сообщения на элементы формы. Смотри образец какая структура элемента (обертка, input, место для сообщения, выделение поля если ошибка или верно), и стили свои писать можно. Обертка элемента - .forms_element > в нем div для ошибок .forms_element__message. Можно в экземпляре валидации переопределить эти классы-селекторы: this.wrapperElement this.messageElement.

Если успешная валидация вызовет отправку формы следующими способами: В конструктор можно передать функции dispatcher или sender. Или вызовет dispatcher с сообщением, что можно отправлять форму в виде dispatcher('validate', 'send', { token, $form: this.$form }) Или вызовет sender(token) Иначе просто отправит форму

Это поведение можно изменить, переопределив метод sendForm у экземпляра

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

1. 'required': 'Обязательное поле',
2. 'white-space-only': 'required',
3. 'minlength': 'Неверное количество символов',
4. 'email': 'email',
5. 'equal-to': 'equal_to',
6. 'only-ukraine': 'only_ukraine символы',
7. 'only-russian': 'only_russian символы',
8. 'only-english': 'only_english символы',

Удобно использовать совместно с jquery-mask-plugin. Вызывать маску отдельно.

Отправка формы

(new SendForm($(selector))).send();

Можно передать в send({ token }) и в запрос будет добавлен параметр gRecaptchaResponse=

Использует для настройки поведения следующие аттрибуты:

1. data-button-id - использует указанную кнопку вне формы для отправки формы
2. $form.attr('action'), $form.attr('method')

В кнопке отправить можно использовать прелоадер - '.js--preloader' - показывать статус отправки формы. Выполняет на нем addClass('d-block'). Нужно чтобы не было повторной отправки.

Обрабатывает ответ { status }:

1. rsp.status === 401 - редирект на главную /
2. rsp.status === 500 - можно выводить сообщение например в toast (сейчас отключено)

Обработка ответа от сервера

handlerAnswer.success({rsp, template}) Основной метод класса - followDirective. Здесь выполняются действия в зависимости от атрибутов формы и полученного ответа - { rsp } Сейчас обрабатывается только случай отправки ajax - success. Также можно отдельно вызвать например: const handlerAnswer = new HandlerAnswer($('.js--validate_form')); handlerAnswer.success({ rsp: { status: 'ok', template: templateForm } });

Логику поведения можно переопределять в методе handlerAnswer Сейчас есть такие действия:

1. Вывод, очистка сообщения с сервера, в определенный селектор
2. Вывод ошибок под нужными полями, так же как валидации показывает ошибки (в ответе должен быть объект {name, message} - имя поля и сообщение)
3. Скрыть внешнюю кнопку отправки формы (если определена в data аттрибуте)
4. Редирект по { url }
5. Вставка шаблона из ответа в определенном блоке и попытка вызвать другой экземпляр (проверка-отправка-обработка). Но это в сочетании FormDispatcher. Также удаление datepicker после вставки нового шаблона
6. Показать блок с сообщением об успехе(заложенном в шаблоне)

Использует дата атрибуты buttonId - скрыть внешнюю кнопку submit datepicker - удаление его id_message_success - сообщение после отправки успешной id_target - куда вставлять шаблон с ответа place_server_message - место для вывода сообщений от сервера

FormDispatcher

Главный класс. Использует и координирует работу валидации, отправки и обработки. Связывает эти 3 части. Использование: (new FormDispatcher($('.js--validate_form'), { formSelector: '.js--validate_form' })).init(); Главный метод notify. Здесь настроена логика, связь между другими кассами. Именно здесь нужно будет настраивать желаемое поведение формы. Сейчас такие обрабатываются такие события:

1. ('validate', 'send', { token, $form: this.$form })
2. ('handlerAnswer', 'pastTemplate', { template: $template })
3. ('sendForm', 'success', { rsp });

Зависит от пакетов

1. jquery
2. jquery-validation
3. Bootstrap: util, index

Зависит от компонентов

1. components/preloader
2. components/toast

Настройки через data атрибуты

1. valid-${type} - Правила валидации (required, white-space-only, minlength ...)
2. error-${type} - Текст сообщения для правила валидации
3. recaptcha_key
4. buttonId - кнопка для отправки формы, если вне формы (чтобы блокировать во время отправки и активировать прелоадер)
5. id_message_success - контейнер для сообщения после успешной отправки (Не динамический - заложенный в верстке, но скрытый).
6. id_datepicker - если на форме был datepicker, то перед вставкой шаблона уничтожить datepicker
7. id_target - контейнер для вставки нового шаблона из ответа от сервера
8. place_server_message - селектор контейнера для вставки сообщения от сервера. default '.js--server_message'
9. lock-class - класс (без точки) например "js--validate_form_fieldset". Если все элементы формы обернуты в fieldset disabled, после загрузки валидации разблокирует форму (иначе можно отправить неправильную форму до загрузки js)

Настройки через параметры функции

FormDispatcher($form, parameters = { formSelector }) formSelector используется для поиска элемента, на котором нужно сделать инициализацию на вновь вставленном шаблоне. Это нужно если вставляется также форма.

Пользовательские события

нет

Желательно использовать с маской ввода телефона типа $('.js--phone').mask('[phone]'); Также удобно использовать form_element, чтобы выводить ошибку от сервера под соответствующем полем

Задачи на доработку, улучшение

1. Привести к единому стилю data атрибуты
2. Сделать те же настройки, что в data атрибутах, и через параметры вызова
3. Доделать toasts, чтобы можно было получать несколько сообщений и разного типа, склонения в таймере (минут, минута, минуты) - Сейчас не используется
4. Придумать гибкую систему переопределения поведения в ответ сервера. Возможно объект с параметрами и соответствующими функциями. Что бы можно было их добавлять во время создания экземпляра.
5. Придумать метод добавления правил валидации
6. Возможно добавить пользовательские события на форму, чтобы извне добавлять функциональность.