mvtForms2   for MODX Revolution   Купить в modstore
Связаться с автором

Документация

1. Описание

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

При установке компонента можно установить и примеры всех форм на базе bootstarp4.


Возможности:

  • Создавайте любые формы и используйте их многократно для отправки разных сообщений
  • Простая установка форм в любое место на сайте в т.ч. прямо в контент страницы даже с правами контент-менеджера.
  • Поддерживается аттач файлов с контролем по типу, размеру и количеству.
  • Заказ в 1 клик со страницы товара, раздела и из корзины (для Minishop2)
  • Автоматическая поддржка компонентов msOptionsPrice / msOptionsPrice2*
  • Сервис по работе с отзывами клиентов
  • Отправка промокода за отзыв (необходим компонент msPromoCode / msPromoCode2*)
  • Сохранение данных всех отправляемых форм с включением данных о местоположении отправителя (город и регион).
  • Определение местоположения пользователя
* - в настоящее время поддержка этих компонентов декларируется, т.е. будет реализована при обращении покупателя компонента.

Геолокация:

Ваш населённый пункт: Ашберн, Вирджиния

Если настроены соответствующие параметры геолокации в системных настройках, то данные геотаргетинга помещаются в сессию при загрузке сайта и доступны везде с помощью Fenom:

{$.session.mvtForms2.geo.city}
{$.session.mvtForms2.geo.region}

2. Использование

2.1. Настройка формы

Все формы хранятся и настраиваются в приложении mvtForms2:

Каждая форма настраивается индифидуально:

Поле Описание
Код формы Уникальный идентификатор формы. Используйте только латиницу, числа, знаки «- , _»
Тип Тип формы. Указывает, как нужно работать форме. Обычная форма просто отправляет данные, формы заказа в 1 клик - создают заказ, отзыв - создаёт отзыв.
Адреса  Адрес или список адресов на которые нужно отправить форму, через запятую.
Чанк формы  Чанк, который используется для данной формы. Можно (и нужно!) создать несколько типовых чанков и использовать их затем для включения различных форм. Необходимо указать системную настройку «Разрешённые чанки форм» или «Разрешённые категории чанков форм», см. Системные настройки.
Название/Тема письма Заголовок формы.
Поля формы  Список полей формы (идентификатор:название), которые будут обработаны. Например: name:Имя,phone:Телефон,email:E-mail.
Обязательные поля  Список идентификаторов обязательных обязательных полей. Например: name,email,phone.
Уведомить отправителя  Если указано «Да», то при успешной отправке формы, отправитель получит уведомление. Чанк шаблона уведомления: tpl.mvtForms.message.user.
Отправка неполной формы  Разрешить отправку формы с незаполненными всеми обязательными полями. Требует значения «Да» для системной настройки «Разрешить отправку неполной формы». Требует заполнения email или phone для получения лида.
Редирект на ресурс  Укажите id ресурса, если хотите переадресовать пользователя на другую страницу после отправки формы. Например для формы типа «Заказ в 1 клик со страницы корзины».
Успешно  Сообщение при успешной отправке формы.
Ошибка  Сообщение при ошибке.
Описание  Описание формы.

Данные форм:

Отзывы:


2.2. Настройка чанков форм

Чанки форм, созданные на основе форм-примеров (устанавливаются вместе с компонентом) не нуждаются в дополнительных настройках. Примеры сделаны на разметке Bootstrap4.

Обязательные переменные, без которых ничего не заработает: {$formID}, {$token}
Класс .mvtFormPhone необходим для работы маски ввода номера телефона.


2.3. Включение форм

  • специальной строкой в контенте/чанке/шаблоне:
    ⁄form2:[идентификатор формы]⁄ , например: ⁄form2:callback⁄
  • шаблонизатор Fenom
    {'!mvtForms2' | snippet : ['form'=>'callback']} , где form - Идентификатор нужной формы
    чтобы лишний раз не дублировать формы, можно изменить «на лету» название и описание формы:
    {'!mvtForms2' | snippet : [
        'form'=>'feedback',
        'name' => 'Обратная связь',
        'description' => 'Можно отправить сообщение...'
    ]}
  • MODX parser
    [[!mvtForms2?&form=`callback`]]

2.4. Системные настройки

Поле Описание

Основные

Разрешить отправку неполной формы

Можно использовать для увеличения количества лидов.
Если заполнено верно поле Email или Телефон - форма будет отправлена, но пользователь всё равно получит ошибку валидации.
При этом вы получите письмо; в случае, если пользователь прекратит заполнение - лид всё равно будет получен.

Комментарий в письме для неполной формы

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

Разрешённые чанки форм

Для того, чтобы при выборе форм не показывались не нужные чанки, вы можете ограничить список чанков.
Укажите здесь перечень id нужных чанков через запятую. Особенно актуально при использовании фронтенд-менеджером, чтобы он смог использовать только строго отведённые чанки.
Разрешённые категории чанков форм То же самое, но для категорий. Можно оставить параметр «Разрешённые чанки форм» путым, и указать здесь перечень нужных id категорий через запятую. При установке автоматически устанавливается = категории mvtForms2.
Разрешённые к отправке типы файлов Список разрешённых для обработки типов файлов.
Скрипты js Путь к файлу со скриптами. Вы можете указать здесь свой js-файл с вашей логикой.
Стили фронтенда Путь к файлу со стилями. Вы можете указать здесь свой файл стилей или офистить эту настройку.
Сохранять данные форм Если разрешено, данные отправленных форм будут записаны и доступны для редактирования.
Сохранять файлы форм Если разрешено, файлы отправленных форм будут сохранены согласно указанному источнику файлов.
Источник файлов Работа с файлами идёт через указанный источник файлов, поэтому вы можете хранить файлы не на сервере, а в облаке (используйте Swift)
Отправлять содержимое корзины Minishop Если указано «Да», то вместе с данными формы будет отправлена информация о составе корзины отправителя.
Чанк письма Чанк шаблона письма.
Чанк письма отправителю Чанк шаблона письма уведомления. Если для формы указано "Уведомить отправителя", то отправителю формы будет отправлено уведомление с использованием данного чанка.
Использовать защитный токен Если «Да», форма будет обработана, только если с ней пришёл валидный токен

Геолокация

Включить геолокацию Если разрешено, компонент будет пытаться определить гео-данные, сохранит их в сессии и добавит к сохранённым данным форм.

DADATA token

Токен сервиса dadata.ru. Определение города по IP бесплатно в рамках лимита см. ссылку.
Путь до файла SxGeoCity.dat Указывать от корневой директории. По-умолчанию = assets/components/mvtforms/SxGeoCity.dat.
Необходим для определения местоположения отправителя, если не подключён сервис dadata.ru. В состав компонента не включён, т.к. не обязателен и создаёт лишний вес. Dadata надёжнее, sxGeo нужно иногда обновлять, зато безлимитно. Скачать можно отсюда: https://sypexgeo.net/files/SxGeoCity_utf8.zip

Заказы

Префикс номера заказа, корзина

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

Купоны (требуется msPromoCode и Minishop2)

Разрешить отправку купонов Если «Да», то становится доступна опция отправки промо-кода автору отзыва.
Чанк письма с купоном По умолчанию: tpl.mvtForms2.message.coupon
Сколько раз можно использовать купон По умолчанию: 1
Скидка Если число с «%», скидка для каждой позиции в корзине в %, иначе - в единицах.
Срок использования Целое число дней с момента отправки.
Маска для генерации купонов Например: «prefix-/([a-zA-Z0-9]-6)-([a-zA-Z0-9]4)/» или «U-/([A-Z0-9]6)/»
Заголовок письма

Отзывы

Обрабатывать изображения для отзыва Если «Да», изображеня будут обработаны в соответствии с установленными настройками
Транслитировать названия файлов изображений Если «Да», названия файлов будут обработаны в соответствии с системными настройками тринслитирования
Настройка превью изображения для отзыва Если «Да», изображение будет обрабатываться phpThumb, согласно указанному правилу.
Например: {"w":100,"h":100,"bg":"ffffff","q":100,"zc":0}
Настройка изображения для отзыва Если «Да», изображение будет обрабатываться phpThumb, согласно указанному правилу.
Например: {"w":600,"h":400,"bg":"ffffff","q":100,"zc":0}
Источник файлов для изображений отзывов Работа с файлами идёт через указанный источник файлов, поэтому вы можете хранить файлы не на сервере, а в облаке (используйте Swift)

2.5. Системные события

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


2.6. JS

Компонент использует один сжатый js-файл: mvt.min.js.
Он содержит функционал обработки форм + jquery mask для поля телефона + multifile для прикрепления файлов.

Исходные js-файлы доступны в assets/components/mvtforms2/js/web/. При необходимости вы можете изменить логику обработчика, состав дополнительных скриптов и собрать свой файл mvt.min.js.

Настройка multifile - в соответствии с документацией.

Для различных целей (например, метрики Яндекса), можно использовать callbacks:

$(document).ready(function ($) {
    mvtForms2.callbacks.success = function(response) {
        console.log(response);
    };
    mvtForms2.callbacks.error = function(response) {
        console.log(response);
    }
    mvtForms2.callbacks.fail = function(response) {
        console.log(response);
    }
});
            

Пример использование callbacks для кастомизации работы формы


3. Примеры

Формы в контенте страницы
Модальная форма
Отзывы
Заказ в 1 клик со страницы товара
Заказ в 1 клик со страницы списка товаров
Заказ в 1 клик из корзины

4. Кейсы

Добавление данных при отправке формы
Регистрация пользователя
Отправка лида в RetailCRM

5. Changelog

Последнее обновление: 22.06.2020г.
1.0.10-beta
==============
- добавлена возможность передачи названия и описания формы при запуске сниппета

1.0.9-beta
==============
- обновлен интерфейс настройки формы в админке

1.0.8-beta
==============
- добавлена возможность отправки неполных форм

1.0.7-beta
==============
- добавлен плэйсхолдер formDescription

1.0.6-beta
==============
- исправлены системные события

1.0.5-beta
==============
- обновлён default.js & mvtforms2.min.js

1.0.4-beta
==============
- в response добавлен идентификатор формы

1.0.3-beta
==============
- Исправлена ошибка обращения к minishop2, если он не установлен

1.0.2-beta
==============
- Исправлены ошибки установщика

1.0.1-beta
==============
- Первый релиз