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

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

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

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

  • Любое количество форм с уникальными идентификаторами и включением метрик Яндекс.Метрика и Google Analitics.
  • Простая установка формы в любое место на сайте в т.ч. прямо в контент страницы
  • Аттач файлов с контролем по типу, размеру и количеству.
  • Заказ в 1 клик со страниц раздела каталога, товара и из корзины (для Minishop2)
  • Сохранение в БД данных всех отправляемых форм с включением данных о местоположении отправителя: город и регион.
  • Определение местоположения. При включении соответствующих настроек, данные о городе и регионе сохраняются в сессии и доступны как в ваших сниппетах, так и в элементах через Fenom.
  • Выгрузка данных отправленных форм в Excel - пока отменено ввиду отсутствия востребованности

Вставка формы

  • сниппетом в шаблоне/чанке:
    MODX parser: [[mvtForms?&form=`callback`]]
    fenom: {'mvtForms' | snippet : ['form'=>'callback']} , где form - Идентификатор нужной формы
  • специальной строкой в контенте:
    ⁄form:[идентификатор формы]⁄ , например: ⁄form:callback⁄

Примеры использования заказа в 1 клик смотрите в разделе Примеры.

Быстрый старт

Начиная с версия 1.1.3 значительно упрощено начало работы с дополнением:

  • Добавлены пять типовых форм: "Заказать звонок", "Задать вопрос", "Заказ в 1 клик со страницы товара",  "Заказ в 1 клик со страницы каталога",  "Заказ в 1 клик со страницы корзины"
  • В чанки добавлены соответствующие кнопки для запуска модальных окон
  • При первой установке автоматически задаётся настройка "mvtforms_allowed_chunks_category"

Это позволяет СРАЗУ после установки пакета начать с ним работать. Подробнее.

Кастомизация формы

Пример чанка формы


Принцип работы

 

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

 

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

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

 

Работа с чанками

Рекомендуется использовать чанки, идущие в комплекте (bootstrap,fenom). Они максимально просты и на их основе вы можете создавать любое количество своих чанков.

Обратите внимание:

Переменная {$formID} (Идентификатор формы): если вы не используете fenom, замените на [[+formID]]. 
Аналогично с остальными переменными.
Все элементы с идентификаторами и классами mvtForms* используются для нормальной работы компонента,
не удаляйте и не изменяйте их.
Исключения: поля, которые в данной форме не используются.

Обязательно указывайте поле «Описание» для чанков - оно используется при выборе чанка для формы.

 

 Геолокация 

Получения данных о городе и регионе посетителя сайта необходимо включить настройки геолокации (выше) и раскомментировать в плагине mvtForms строку:

$_SESSION['mvtForms']['geo'] = $mvtForms->getGeoData();

 Влюбом месте сайта данные сессии доступны с помощью Fenom: 

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

 

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

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

case 'MvtFormsOnFormSubmit':
        $modx->log(1,'MvtFormsOnFormSubmit');
    break;
case 'MvtFormsOnBeforeFormSend':
        $modx->log(1,'MvtFormsOnBeforeFormSend');
    break;

 Примеры применения смотрите в кейсах ниже.


Настройка

Для работы с компонентом не под админом, пользователю необходимо добавить стандартную политику доступа «mvtManagerPolicy».

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

 

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

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

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

Включить лог

Если разрешено, mvtForms будет писать лог всех отправленных форм с геоданными отправителя.

DADATA token

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

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

 Для того, чтобы при выборе форм не показывались не нужные чанки, вы можете ограничить список чанков.
Укажите здесь перечень id нужных чанков через запятую. Особенно актуально при использовании фронтенд-менеджером, чтобы он смог использовать только строго отведённые чанки.
Разрешённые категории чанков форм То же самое, но для категорий. Можно оставить параметр «Разрешённые чанки форм» путым, и указать здесь перечень нужных id категорий через запятую. Начиная с версии 1.1.3 при установке автоматически устанавливается = категории MvtForms.
Разрешённые к отправке типы файлов  Список разрешённых для обработки типов файлов.
Отправлять содержимое корзины Minishop  Если указано «Да», то вместе с данными формы будет отправлена информация о составе корзины отправителя.
Чанк письма  Чанк шаблона письма.
Чанк письма отправителю  Чанк шаблона письма уведомления. Если для формы указано "Уведомить отправителя", то отправителю формы будет отправлено уведомление с использованием данного чанка.
Идентификатор счётчика Yandex.Метрика  Для срабатывания события Яндекс.Метрика, укажите здесь номер счётчика. На сайте должен быть установлен скрипт Яндекс.Метрика.

 

JS

Компонент использует один js-файл: mvt.min.js. Он содержит функционал обработки форм + jquery mask для поля телефона + multifile для прикрепления файлов.
Исходные js-файлы доступны в assets/components/mvtforms/js/web/. При необходимости вы можете изменить логику обработчика, состав дополнительных скриптов и собрать свой файл mvt.min.js.

Настройка multifile

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


Примеры

1. Форма "Заказать звонок"

Переходим в нужный шаблон/чанк и вставляем вызов сниппета: 

[[mvtForms?&form=`callback`]]


Ниже примеры приведены в Fenom. Если вы ещё не используете pdoTools & Fenom — рекомендую.

 

2. Заказ товара в 1 клик со страницы товара в модальном окне

В шаблоне товара (или в чанке msProduct.content, в зависимости от того, как вы структурируете проект) получим массив $product, в котором будут лежать все данные товара:

{var $product = $_modx->resource}

 Содержимое массива можно просмотреть так:

{$product | print_r : 1}

Далее оформляем чанк (пример чанка), добавив вызов модальной формы и сниппета mvtForms с нужной нам формой:

<a type="button" href="#" data-modal="oneClickForm" data-price="{$product.price} {'ms2_frontend_currency' | lexicon}" class="btn btn-success mvtFormsOneClickForm">Заказать в 1 клик</a>
{'mvtForms' | snippet : ['form'=>'byOneClickProduct']}

Внимание! Класс mvtFormsOneClickForm должен присутствовать обязательно. Сниппет mvtForms нужно вызывать ЗА ПРЕДЕЛАМИ <form class="form-horizontal ms2_form" method="post">...</form>, чтобы submit формы не добавлял товар в корзину :-).

 

В варианте без fenom'а просто добавьте за пределами формы:

<a type="button" href="#" data-modal="oneClickForm" data-price="[[+price]] [[%ms2_frontend_currency]]" class="btn btn-success mvtFormsOneClickForm">Заказать в 1 клик</a>
[[mvtForms? &form=`byOneClickProduct`]]

 


3. Заказ товара в 1 клик со страницы раздела в модальном окне

В шаблоне раздела каталога добавляем сниппет mvtForms с нужной нам формой:

{'mvtForms' | snippet : ['form'=>'byOneClickProductList']}

Далее оформляем чанк списка товаров (пример чанка), добавив вызов модальной формы:

<a type="button" href="#" data-modal="oneClickFormProductList" data-price="{$price} {'ms2_frontend_currency' | lexicon}" data-name="{$pagetitle | replace : '"' : ''}" data-id="{$id}" class="btn btn-success mvtFormsOneClickForm">Заказать в 1 клик</a>

Внимание! Класс oneClickFormProductList должен присутствовать обязательно.
Обратите внимание на конструкцию : тут мы избавляемся от возможных кавычек в названии товара. Хотя я рекомендую убирать их раньше: на этапе импорта товара, плагином при сохранении товара в админке или prepareSnippet'ом при выводе товаров сниппетом msProducts. 


4. Заказ товара в 1 клик со страницы корзины в модальном окне

Тут совсем всё просто. В чанке tpl.msCart добавляем  сниппет mvtForms с нужной нам формой:

{'mvtForms' | snippet : ['form'=>'byOneClickCart']}

 

Для форм заказа в 1 клик не забываем выставить соответствующий тип в приложении.


Кейсы


Changelog

Changelog for mvtForms.

1.1.6-beta
==============
- Security update
- Added support for arrays of forms (checkbox, radiobutton), eg field[]

1.1.5-beta
==============
- Update js
- Many forms to one page
- Making order by phone only
- Added data post filter
- Added function getGeoData()

1.1.4-beta
==============
- Added logging with geo-data
- Fixed error var yaCounter in files default.js/mvt.min.js

1.1.3-beta
==============
- Add minishop2 event: msOnCreateOrder
- Add minishop2 create OrderAddress
- Add demo forms records
- Automatic setting of the "mvtforms_allowed_chunks_category" setting when the package is first installed

1.1.2-beta
==============
- Correcting сhunks

1.1.1-beta
==============
- Added field validation

1.1.0-beta
==============
- First relis