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

Особенности

Универсальный плагин отправки 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.3 - 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

www.000webhost.com