Скрипт асинхронной обработки любых html-форм с поддержкой работы на старых хостингах.
Основные характеристики:
- Встроенная защита от спама, поддержка капчи.
- Работа через SMTP.
- Поддержка всплывающей формы.
- Поддержка валидации, тултипы, настройка масок ввода.
Системные требования
- Работает с PHP 5.2.17+.
- Jquery >= 1.9+
- Браузеры: ie11+
В репозиторие лежат только исходники скрипта, все зависимости надо доустановить.
php composer.phar install
npm run install
Для установки нужно подключить скрипты в указанной последовательности:
<!-- Rockform -->
<script src=https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js></script>
<link href="/rockform/core/themes/default/main.css" type="text/css" rel="stylesheet"/>
<script src="/rockform/dist/rockform.min.js"></script>
<!-- // Rockform -->Для подключения существующей формы на странице достаточно тегу form добавить
атрибут с названием конфигурации data-bf-config="Название_конфигурации".
Можно оставить пустым, тогда конфигурация возьмётся из настроек по умолчанию: /core/config/config.php.
Для начала нужно настроить шаблон, который можно найти в папке /configs/example/templates/popup.html. В него можно передать любой html-код с формой, он подхватится автоматически. Работает с поддержкой шаблонизатора Twig.
Для вызова всплывающего окна нужно добавить атрибут data-bf-config="" на любой тег,
кроме формы.
В всплывающую форму можно передать параметры через data-атрибуты,
например: data-bf-field_title="Параметр"
Где title можно заменить на своё название.
Стоит учесть, что здесь обязательно нужно использовать нижнее подчёркивание.
Переданная переменная будет доступна в шаблонах как: {{field_title}}.
Шаблон лежит в папке выбранного конфига /templates/report.html.
В качестве шаблона для полей используется конструкция {{название_поля_ввода}}. Поддерживает работу с шаблонизатором Twig.
Также доступны системные переменные:
| Переменная | Описание |
|---|---|
| {{field_page_link}} | Адрес страницы оформления формы |
| {{field_page_h1}} | Тег h1 страницы оформления формы |
Шаблон лежит в папке выбранного конфига /templates/popup.html.
Шаблон лежит в папке выбранного конфига /templates/success.html.
Стоит учесть, что здесь обязательно нужно добавить атрибут
data-bf-successв тег обёртки шаблона.
Настройки хранятся в формате .ini. По умолчанию, при пустом вызове, настройки берутся из /config/config.php.
rockform/
└── config
├── templates
│ ├── popup.html
│ ├── success.html
│ └── report.html
└─── config.php
Дополнительные конфигурации можно создавать в папке /configs/.
Можно создать сколько угодно конфигураций, просто копируя /configs/example/ с другим названием и меняя параметры на свои.
Стоит отметить, что конфигурации наследуются от
/config/config.ini.php, поэтому можно опускать почту и другие повторяющиеся параметры. Не наследуется только секция валидации.
Для настроек можно использовать названия полей из формы и суперглобальный массив $_SERVER.
Например: subject = 'Письмо от {{username}}'. Где username,
- это значение атрибута поля ввода name="username".
| Параметр | Значение по умолчанию | Пример | Описание |
|---|---|---|---|
| mail_to | [email protected](Первый получатель) | Поле обязательно. Почта получателей. Можно несколько через запятую. Имя в скобочках опционально. | |
| mail_subject | Письмо с сайта | Заголовок письма. | |
| mail_from | from@{{SERVER_NAME}} | [email protected] | Почта, которая будет указана в качестве адреса отправителя. Совпадает с пользователем SMTP. |
| mail_from_name | Из {{SERVER_NAME}} | Имя или название источника отправителя. | |
| mail_disable_send | 0 | Не отправлять на почту (0 или 1) | |
| mail_add_cc | [email protected](Первый получатель) | Добавить получателей точной копии (CC). Можно несколько через запятую. Имя в скобочках опционально. | |
| mail_add_bcc | [email protected](Первый получатель) | Добавить получателей скрытой копии (BCC). Можно несколько через запятую. Имя в скобочках опционально. | |
| mail_reply_to | [email protected](Первый получатель) | Добавление адреса для ответа (Reply-To). Можно несколько через запятую. Имя в скобочках опционально. | |
| mail_confirm_reading_to | [email protected] | Требование подтверждения прочтения. | |
| mail_smtp_host | smtp.yandex.ru | Адрес SMTP сервера | |
| mail_smtp_auth | true | Включение SMTP авторизации | |
| mail_smtp_username | [email protected] | SMTP пользователь | |
| mail_smtp_password | SMTP пароль | ||
| mail_smtp_secure | ssl | ssl | Включение шифрования TLS, также доступен ssl |
| mail_smtp_port | 465 | 465 | TCP порт |
| lexicon | default | Название файла локализации в папке /core/lexicon/. | |
| charset | utf-8 | Кодировка |
Для включения валидации полей, надо в конфигурационом файле добавить
секцию [validation].
Затем перечислить названия полей и атрибуты валидации к ним.
Пример: name_user = 'required,minlength[3],words'.
Это будет означать, что атрибут name со значением - name_user будет обязателен для заполнения, минимальное допустимое число символов будет 3 и на вход должны быть переданы только слова.
Атрибуты валидации:
| Выражение | Описание |
|---|---|
| required | Поле становится обязательным для заполнения. |
| minlength[1] | Минимальное число символов. В скобочках указывается значение. |
| maxlength[10] | Максимально число символов. В скобочках указывается значение. |
| rangelength[1,10] | Диапозон числа символов. В скобочках указывается значение. |
| Электронная почта. | |
| url | Ссылка. |
| ip | ip-адрес. |
| number | Дробные числа. |
| digits | Только цифры. |
| letter | Только буквы. |
| words | Ввод слов. |
| filesize[1048576] | Допустимый размер файлов. В скобочках размер в байтах (1048576 = 1 мегабайт). |
| file[.jpg,.png] | Допустимые расширения файлов. В скобочках расширения через запятую. |
Существует поддержка настройки позиции всплывающих подсказок. Атрибут data-bf-tooltip="" можно задать,
как глобально для тега form, так и индивидуально для каждого элемента полей ввода.
Доступны следующие атрибуты:
| Выражение | Описание |
|---|---|
| top-right | Сверху справа |
| top-center | Сверху по центру |
| top | Сверху |
| top-left | Сверху слева |
| bottom | Снизу |
| bottom-left | Снизу слева |
| bottom-right | Снизу справа |
| bottom-center | Снизу по центру |
| left | Слева |
| right | Справа |
В форме доступны два атрибута для настроек масок:
data-bf-maskпринимает на вход выражения из таблицы ниже.
Доступны атрибуты маски:
| Выражение | Описание |
|---|---|
| A | Только буквы |
| 0 | Только цифры |
| S | Только буквы и цифры |
Пример
data-bf-mask="+7 (000) 000-00-00"
placeholder- плейсхолдер, формируется автоматически, но если в плейсхолдере есть цифры или буквы, тогда нужно задать явно через этот атрибут.
Пример
placeholder="+7 (___) ___-__-__"
Для работы используется плагин jQuery-Mask-Plugin.
-
Для добавления капчи нужно картинке присвоить атрибут -
data-bf-capcha. -
В конфигурационном файле указать в секции
[validation]параметрbf_capcha = capcha;. Гдеbf_capcha- значение атрибутаnameдля поля, в который будет вводиться информация с картинки.
Пример
<div class="bf-row">
<div class="bf-info-img">
<img width="100" height="50" title="Обновить картинку" data-bf-capcha src="" alt="" />
</div>
<input class="capcha bf-form-control" name="bf_capcha" placeholder="Код с картинки" type="text" value="" />
</div>
Для создания всплывающего окна с политикой конфиденциальности достаточно создать отдельный конфиг,
где в шаблоне popup.html указать нужный текст. Вызывать его аналогично, как и другие всплывающие формы,
т.е через data-bf-config="НАЗВАНИЕ_КОНФИГА", но также требуется добавить атрибут дополнительного поля,
например: data-bf-field_form="НАЗВАНИЕ_КОНФИГА"
Для возврата в конфиг, с которого был переход на политику, надо создать ссылку
с атрибутом data-bf-config="{{field_form}}". Если требуется закрыть окно с политикой,
то ссылке надо добавить атрибут data-bf-popup="close".
Файл для локализаций лежит в /core/lexicon/default.ini. Значения в этом файле можно переопределить на своё усмотрение или скопировать в файл с другим названием. Нaпример в /core/lexicon/en.ini.
Установить новый файл локализаций можно через опцию lexicon в конфигурации, передав название нового файла.
Для примера выше, это будет выглядеть так: lexicon = en.
Для расширения фунциональности, например для записи данных из формы в базу данных, существует класс расширения.
Класс примера можно найти в /configs/example/events.php (файл можно скопировать в любой другой конфиг).
Методы класса срабатывают только при вызове данного конфига.
Доступны следующие события
| Событие | Описание |
|---|---|
| before_show_modal | Срабатывает до показа всплывающей формы. |
| before_success_modal | Срабатывает до показа формы об успешной отправке. |
| before_success_send_form | Срабатывает перед успешной отправкой формы. |
| after_success_send_form | Срабатывает после успешной отправки формы. |