универсальный плагин отправки HTML-форм
средствами PHP, jQuery, AJAX.

Скачать GitHub

## Особенности

Универсальный плагин отправки HTML-форм средствами PHP, jQuery, AJAX. Плагин автоматически собирает значения всех полей формы и в виде HTML-таблицы отправляет на указанный почтовый ящик. Для удобной и надежной отправки писем через SMTP-сервер используется библиотека PHPMailer.

- Отправка форм без перезагрузки страницы - AJAX
- Поддержка всех типов полей HTML5
- Поддержка отправки вложений (single, multiple)
- Возможность задавать массив получателей, отправителя, тему, редактировать HTML-содержимое письма
- Сохраняется работоспособность форм при отключенном JS (можно создавать/задвать отдельные страницы и переправлять на них при событиях: "Форма успешная отправлена" и "Ошибка при отправке формы")
  Рекомендации по оформления подобных форм

## Пакетные менеджеры

## Подключение

##### 1. Подключить последнюю версию jQuery и jquery.sendmail.js

            <!-- jQuery -->
            <script src="libs/jquery/dist/jquery.min.js"></script>

            <!-- jquery.sendmail.js -->
            <script src="dist/jquery.sendmail.js"></script>

##### 2. В корневую директорию сайта скопировать папку mail/ со всем ее содержимым. В файле mail/sendmail.php отредактировать значения следующих обязательных параметров:

    $recipients    // Получатели писем
    $smtp_host     // SMPT-адрес сервера
    $smtp_port     // TCP-порт
    $smtp_secure   // SMTP TLS/SSL
    $smtp_auth     // SMPT-аутентификация
    $smtp_username // Почтовый ящик, с которого будут отправляться письма
    $smtp_password // Пароль почтового ящика, с которого будут отправляться письма

    // Остальные параметры по необходимости...

Значения параметров: `SMPT-адрес сервера`, `TCP-порт`, `SMTP TLS/SSL`, `SMPT-аутентификация` будут зависить от почтового ящика, который будет выбран в качестве отправителя. По умолчанию все настройки заданы для `gmail.com`.
Настройки SMTP для наиболее популярных почтовых сервисов
Если возникли ошибки при отправке через SMTP Google

##### 3. Создать HTML-форму:

##### 4. Инициализировать плагин на форме/ах:

            $('form.example').sendMail();

## Параметры

Опция | Тип | Поум. | Описание
--- | --- | --- | ---
url | String | 'mail/sendmail.php' | Путь к PHP-обработчику
reset | Boolean | true | Очистка полей формы после успешной отправки
freeze | Boolean | 0 | Предотвращает повторные попытки отправки формы на указанный промежуток времени, мс По умолчанию, при значении 0, повторная отправка формы становится доступна по завершению предыдущего запроса

### Примеры использования параметров

            $('form.example').sendMail({
              url: false,
              reset: 'sendmail.php'
            });

## Параметры: sendmail.php

Опция | Тип | Описание
--- | --- | ---
$recipients | Array | Получатели писем
$subject | String | Тема письма
$before_table | String | HTML-содержимое до таблицы
$after_table | String | HTML-содержимое после таблицы
$sep | String | Разделитель между значениями (использ. при форм. HTML-содержимого письма). Например, при отображении нескольких выбранных занчений в select multiple
$smtp_host | String | SMPT-адрес сервера
$smtp_port | Number | TCP-порт
$smtp_secure | String | SMTP TLS/SSL
$smtp_auth | Boolean | SMPT-аутентификация
$smtp_username | String | Почтовый ящик, с которого будут отправляться письма
$smtp_password | String | Пароль почтового ящика, с которого будут отправляться письма
$success_page | String | Ссылка на страницу (если JS отключен): Успешная отправка формы
$error_page | String | Ссылка на страницу (если JS отключен): Ошибка при отправке формы

## Методы

Метод | Аргументы | Описание
--- | --- | ---
init | options | Инициализация
destroy | - | Деинициализация
reinit | newOpts | Реинициализация
send | - | Отправка формы

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

            var options = { /* Параметры... */ },
              newOpts = { /* Новые параметры... */ };

            $('form.example').sendMail('init', options); // Инициализация с польз. пар-ми
            $('form.example').sendMail(options); // Инициализация с польз. пар-ми
            $('form.example').sendMail(); // Инициализация с пар-ми поум.
            $('form.example').sendMail('destroy'); // Деинициализация
            $('form.example').sendMail('reinit', newOpts); // Реинициализация с новыми пар-ми
            $('form.example').sendMail('reinit'); // Реинициализация с текущими пар-ми
            $('form.example').sendMail('send'); // Отправка формы

## События

Событие | Аргументы | Описание
--- | --- | ---
beforeInit.sml | e, instance, form | Перед началом инициализации
afterInit.sml | e, instance, form | После инициализации
beforeSend.sml | e, instance, form | Перед отправкой формы
afterSend.sml | e, instance, form, response | После попытки отправки формы, независимо от результата
success.sml | e, instance, form, response | Успешная отправка AJAX-запроса. Форма отправлена
serverError.sml | e, instance, form, response | Ошибка при отправке AJAX-запроса
ajaxError.sml | e, instance, form, response | Ошибка на сервере при отправке формы

### Примеры использования событий

              var example = $('form.example');

              example.on('success.sml', function(e, instance, form, response) {
                console.log( 'success: ', e, instance, form, response );
                /* Аргументы:
                  e - объект события
                  instance - экз. класса SendMail для элемента, на котором вызвано событие
                  form - форма, HTML-элемент
                  response - ответ
                */
              });

              example.sendMail(); // Инициализация

## Data-атрибуты

Параметры в data-атрибуте имеют наивысший приоритет. Они переопределят параметры по умолчанию, а так же пользовательские параметры заданные при инициализации. Значение атрибута - валидный JSON.

## Переопределение параметров по умолчанию

              /* Изменение параметров по умолчанию (свойство): */
              $.fn.sendMail.defaults.reset = false;

              /* Изменение параметров по умолчанию (объект): */
              $.fn.sendMail.defaults = $.extend(true, {},$.fn.sendMail.defaults, {
                reset: false,
                url: 'sendmail.php'
              });

              /* Далее инициализация... */
              $('form.example').sendMail();

## Рекомендации

- Для поддержки работоспособности формы в случае отключенного в браузере JS, всегда указывать в теге `<form>` атрибуты `action=""` и `method=""` с актуальными значениями.

- Для отправки вложений, обязательно наличие аттрибута `enctype="multipart/form-data"` в теге `<form>`

- Для отправки нескольких вложений из одного поля `<input type="file">`, обязательно наличие конструкции `[]` в атрибуте `name="upload[]"`, а также наличие атрибута `multiple`.

- При использовании `<select multiple>`, обязательно наличие конструкции `[]` в атрибуте `name="choose-colors[]"`

- Прикрепление файла к письму из sendmail.php (ссылка на файл, относ. путь):

- Файлы `error.html` и `success.html` не обязательны. Если у пользователя в браузере отключен JS или по каким-либо причинам не удалось отправить форму AJAX-ом, перенаправление будет происходить именно на эти страницы. Отключить перенаправление можно в файле `sendmail.php`, установив переменным `$success_page` и `$error_page` пустые значения или false.

- SMPT-адреса серверов наиболее популярных почтовых сервисов (`sendmail.php`, `$smtp_host`):

  Почтовый сервис | SMTP-адрес
  --- | ---
  Gmail.com | smtp.gmail.com
  Mail.ru | smtp.mail.ru
  Yandex.ru | smtp.yandex.ru
  Rambler.ru | mail.rambler.ru

  Следующие параметры зачастую у всех сервисов одни и те же.

- Если при отправке форм через SMTP Google, возникают ошибки, в первую очередь рекомендуется произвести следющие действия:

  - Зайти на https://myaccount.google.com под используемым в скрипте аккаунтом Google
  - В меню слева перейти по "Безопасность"
  - Ниже "Ненадежные приложения, у которых есть доступ к аккаунту" -> "Открыть доступ" или перейти по ссылке https://myaccount.google.com/lesssecureapps и выставить переключатель в положение "Небезопасные приложения разрешены"
  - Перейти по ссылке https://accounts.google.com/DisplayUnlockCaptcha и нажать "Продолжить"

## Примеры использования

### Пример: Всплывающие окна после отправки

SendMail в связке с FancyBox. Всплывающие окна на 3 основных события.

              var example = $('form.example');

              // Успешная отправка формы
              example.on('success.sml', function() {

                // Открыть динамический popup
                $.fancybox.open('<p>Спасибо! Ваша заявка успешно отправлена!</p>');

                // Закрыть окно через 5 сек.
                setTimeout(function() { $.fancybox.close() }, 5000);

              });

              // Ошибка при отправке AJAX-запроса
              example.on('serverError.sml', function(e, instance, form, response) {

                $.fancybox.open('<p>Ошибка при отправке AJAX-запроса!</p>' + '<br>' + response);
                setTimeout(function() { $.fancybox.close() }, 5000);

              });

              // Ошибка на сервере при отправке формы
              example.on('ajaxError.sml', function(e, instance, form, response) {

                $.fancybox.open('<p>Ошибка на сервере при отправке формы!</p>' + '<br>' + response);
                setTimeout(function() { $.fancybox.close() }, 5000);

              });

              // Инициализация...
              example.sendMail();

### Пример: Валидация формы

Валидация формы на примере jQuery Validation Plugin

              var example = $('formform.example');

              // Убрать обработчик для "Submit" с формы
              example.on("afterInit.sml", function(e, instance, form) {
                $(form).off( 'submit.sml-' + instance.nsid );
              });

              // Инициализация SendMail
              example.sendMail({
                // Параметры SendMail...
              });

              // Инициализация Validator
              example.validate({

                // Параметры валидатора...

                submitHandler: function(form) {

                  // Валидация пройдена - Отправка формы
                  $(form).sendMail('send');

                }
              });

### Пример: Внесение доп. данных в таблицу письма

Свойства объекта `instance.addData` (ключ-значение) будут добавлены к общим данным формы
и выведены в таблице Email-письма.

              var example = $('form.example');

              // Перед отправкой формы
              example.on('beforeSend.sml', function(e, instance) {

                // Наполнить объект произвольными данными
                instance.addData = {
                  "Время": "15:30:45",
                  "Температура": "+25С"
                };

              });

              // Инициализация...
              example.sendMail();

## История изменений

### 2.0.5 - 23.02.2019

- Изменены наименования некоторых событий

### 2.0.2 - 15.01.2019

- Полностью переработана структура плагина
- Функции обратного вызова заменены соотв. событиями
- Исправлено содержимое ответов от сервера, получ. в событиях "afterSend.sml", "success.sml", "serverError.sml", "ajaxError.sml". Ошибки от PHPMailer по умолчанию переведены на русский язык.
- Изменена логика перенаправлений на страницы "success.html" и "error.html"
- Добавлена возможность расширить передваемые из формы в таблицу данные, собственными, при помощи события "beforeSend.sml"
- Добавлен параметр "freeze", запрещающий повторную отправку формы на указанное время
- Другие мелкие исправления

### 1.0.8 - 07.10.2018

- Исправлены проблемы с путями в файле sendmail.php
- Незначительные правки в коде

### 1.0.7 - 22.09.2018

- Обновление библиотеки PHPMailer до версии 6.0.5

### 1.0.6 - 21.08.2018

- Колбэк "beforeSend" прерывает отправку письма при "return false"
- Некоторые правки для комфортной работы с jQuery Validation Plugin (пример в demo/index.html)

### 1.0.3 - 20.08.2018

- Незначительные правки в коде (не повливают на работу плагина)

### 1.0.2 - 18.08.2018

- Добавлена поддержка цепочек вызовов
- Незначительные изменения в именах некоторых переменных
- Правки в readme.md

## Лицензия (MIT)

Copyright (c) 2018-2019 Sergey Kravchenko

Данная лицензия разрешает лицам, получившим копию данного программного обеспечения и сопутствующей документации (в дальнейшем именуемыми «Программное Обеспечение»), безвозмездно использовать Программное Обеспечение без ограничений, включая неограниченное право на использование, копирование, изменение, слияние, публикацию, распространение, сублицензирование и/или продажу копий Программного Обеспечения, а также лицам, которым предоставляется данное Программное Обеспечение, при соблюдении следующих условий:

Указанное выше уведомление об авторском праве и данные условия должны быть включены во все копии или значимые части данного Программного Обеспечения.

ДАННОЕ ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНО ВЫРАЖЕННЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ ГАРАНТИИ ТОВАРНОЙ ПРИГОДНОСТИ, СООТВЕТСТВИЯ ПО ЕГО КОНКРЕТНОМУ НАЗНАЧЕНИЮ И ОТСУТСТВИЯ НАРУШЕНИЙ, НО НЕ ОГРАНИЧИВАЯСЬ ИМИ. НИ В КАКОМ СЛУЧАЕ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО ИСКАМ, ЗА УЩЕРБ ИЛИ ПО ИНЫМ ТРЕБОВАНИЯМ, В ТОМ ЧИСЛЕ, ПРИ ДЕЙСТВИИ КОНТРАКТА, ДЕЛИКТЕ ИЛИ ИНОЙ СИТУАЦИИ, ВОЗНИКШИМ ИЗ-ЗА ИСПОЛЬЗОВАНИЯ ПРОГРАММНОГО ОБЕСПЕЧЕНИЯ ИЛИ ИНЫХ ДЕЙСТВИЙ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ.

## Поддержка

Решение проблем/багов плагина, а также замечания и пожелания в соответствующей теме

По всем другим вопросам: wahawaher@gmail.com