AjaxFrontend

Оптимизация и централизация кастомных AJAX запросов на сайте
Бесплатно
Загрузите дополнение из админки вашего сайта.
Как загрузить?
Автор дополнения
crow
Пакетов
7
Закачек
60
Автор дополнения
Пакетов
7
Закачек
60
Версия 1.0.3-pl
Дата выпуска 15.10.2018
Загрузки 17
Просмотры 844
Внимание, этот компонент требует версию PHP 5.3 или выше! Если ваш сайт использует PHP ниже требуемого, установка этого дополнения может его сломать.
Внимание, этот компонент требует версию MODX не ниже 2.5 !
Компонент позволяет создавать и обрабатывать кастомные AJAX запросы без создания дополнительных action файлов, плагинов и подобного для обработки AJAX запроса.

Возможности
  • централизованно принимать и обрабатывать кастомные AJAX запросы через единый файл
  • защита от несанкционированных внешних запросов от ботов
  • встроенная защита принимаемых данных от клиента или стандартная модексовская (на выбор, по умолчанию — встроенная защита компонента)
  • список исключаемых полей или наоборот список только разрешенных полей
  • встроенная валидация компонента (полей, файлов)
  • легкая и мощная настройка существующих кастомных форм (через классы и data атрибуты)
  • легкое использование на стороне клиента в любых своих JS скриптах
  • поддержка отправки файлов по AJAX
  • автоматический возврат и отображение ошибок клиенту
  • адаптирован под ответы процессоров модекса и процессоров от компонентов

Внимание!
  • Компонент не имеет интерфейса, он полностью настраивается на существующих обычных формах через классы и data атрибуты
  • Должен быть подключен jQuery (в данный момент рекомендуемая версия 3+, на версиях ниже может не работать)
  • Ориентирован на разработчика сайта, для облегчения ему жизни
  • Вложенные массивы $this->data['key'][] — не обрабатываются, обрабатываются только значения первого уровня
  • Для передачи HTML кода без его обработки используется специальное название поля, указанное в настройках ($this->data['html'] — по умолчанию)
  • Для передачи JSON данных используется специальное название поля, указанное в настройках ($this->data['json'] — по умолчанию), на выходе получается массив преобразованный через json_decode
Настройка компонента (необходимо перед началом использования)
  1. Необходимо зайти в папку "core/components/ajaxfrontend/custom/", там находится файл "example_actions.class.php". Данный файл изменять не имеет смысла, так как, при обновлении он будет перезаписан и все ваши изменения исчезнут. В этом файле показаны примеры обработки запросов
  2. Скопировать файл "example_actions.class.php" в эту же папку и переименовать его в "actions.class.php" (по умолчанию), краткий код файла будет показан ниже. Название файла можно поменять на другое или вообще переместить в любую другую папку проекта (хоть в корень сайта). Если файл перемещен в другую папку, переименован в другое название или одно и другое, тогда необходимо в системных настройках указать где находится данный файл (системная настройка "ajaxfrontend_file_ajax"). При указании пути, можно использовать плейсхолдеры модекса — [[++core_path]], [[++assets_path]], [[++base_path]]
  3. В шаблоне сайта вызвать сниппет компонента ( [[!ajaxFrontend]] или для fenom {'!ajaxFrontend'|snippet} ) глобально (для всех страниц). Сниппет необходимо вызывать НЕ КЭШИРОВАННЫМ!
  4. Базовая настройка самого компонента завершена
Минимальный код для файла «actions.class.php»
<?php

class ajaxCustomActions extends ajaxActions
{
    public function actionTestaction()
    {
        return ['success'=>true];
    }
}

return 'ajaxCustomActions';

Использование компонента (на стороне клиента)
Подключение форм
  1. В тег form обязательно добавить класс "js_ajax_form" и data-action=""
  2. В data-action="" добавить параметр основываясь на том, какой метод необходимо запустить в нашем созданном файле "actions.class.php" (правила генерации имен методов будут ниже), в нашем случае это метод "actionTestaction". Добавляем в атрибут правильное название метода, он будет выглядеть следующим образом: data-action=«testAction» (регистр букв не имеет значения, пробелы и любые символы кроме англ. букв и цифр запрещены, слово action исключается)
  3. Добавляем необходимые поля в форму если их еще нет
  4. Теперь наша форма готова, при попытке отправить ее — произойдет ajax запрос на указанный нами action в файле "actions.class.php" c отправкой полей в форме
Дополнительные опции для формы
  • В теге формы data-clear=«1» — указывает очистить поля формы или нет после успешного запроса (1 — очистить, 0 — не очищать, по умолчанию). Если указано «1», в необходимые поля для очистки добавить класс «js_ajax_clear». Поля в которые не добавлен этот класс — не будут очищаться
  • В теге формы data-success=«FunctionName» — кастомная JS функция, которая будет вызвана по завершению AJAX запроса с этой формы. Функция принимает 2 параметра FunctionName(response, options){}
  • В теге формы data-nomessage=«1» — показывать или нет alert сообщения (1 — не показывать, 0 — показывать, по умолчанию)
  • В теге формы data-text=".ajax_text_block" — класс или ID блока, в который необходимо вернуть контент с сервера по завершению AJAX запроса
Показ ошибок клиенту (для каждого поля)
Обычный ответ с сервера выглядит так: {success:false, errors: {}}
Для показа ошибок необходимо использовать следующие классы внутри формы
  • Класс "js_ajax_wrapper" — используется на родительском блоке нужного поля, может быть по иерархии и выше, главное чтобы не оборачивались 2 поля сразу
  • Класс "js_ajax_error" — указывается на блоке где необходимо вывести ошибку для конкретного поля, должен быть дочерним элементом блока с классом "js_ajax_wrapper"
Простой пример с 2 полями и минимальным набором для них:
<form class="js_ajax_form" data-action="testAction">
<div class="js_ajax_wrapper">
	<input type="text" name="name">
	<div class="js_ajax_error"></div>
</div>
<div class="js_ajax_wrapper">
	<input type="text" name="phone">
	<div class="js_ajax_error"></div>
</div>
<button type="submit">Отправить</button>
</form>

Показ клиенту ошибки или успешного сообщения (общее)
Обычный ответ с сервера выглядит так: {success:false, message: 'Произошла ошибка'}
или так: {success:true, message: 'Сообщение успешно отправлено'}
Здесь есть 2 варианта показа сообщения, показывать сообщение как в ajaxForm и miniShop2 компонентах (alert сообщения через jGrowl) или в самой форме.
Для показа в форме, необходимо в форму добавить блоки со специальными классами для ошибки и\или успешной отправки формы.
Минимальная разметка для сообщения ошибки:
<div class="js_ajax_alert_error">
	<div class="js_text"></div>
</div>
Минимальная разметка для сообщения об успехе:
<div class="js_ajax_alert_success">
	<div class="js_text"></div>
</div>
При использовании разметки общих ошибок, alert сообщения вызываться не будут.

Использование в своих JS скриптах:
Для использования в своих скриптах необходимо использовать функцию ajax(action, data, options);
  • action — аналогично data атрибуту в форме "data-action"
  • data — данные, принимается в 2 форматах
    • form.serializeArray() или обьект [{name:«name»,value:«name»},{name:«phone»,value:«12345»}]
    • {name: «name»,phone: «12345»}
  • options (не обязательно) — многофункциональная опция, которая принимает только JSON формат, о ней ниже
    • text — аналогично data атрибуту в форме "data-text", класс или ID блока в который необходимо вернуть текст. Если возвращается ассоциативный массив, тогда отельные его части буду вставлены в разные блоки указанные классами. Для вставки данных из массива используется префикс классов "js_ajax_response_", то есть если вернулся такой массив {success: true, text: {name: 'Имя', phone: 'Телефон'}} — тогда классы генерируются такие: js_ajax_response_name и js_ajax_response_phone. Классы можно использовать в любых нужных блоках HTML разметки
    • reload — перезагрузить страницу по окончанию запроса и если он будет успешный
    • nomessage — аналогично data атрибуту в форме "data-nomessage", показывать или нет alert сообщения
    • success — функция которая будет вызвана при успешном ответе с сервера, данные, принимается в 3 форматах
      • анонимная функция function(response,options){}

      • название функции 'FunctionName'
      • название объекта и его метод через запятую 'Object,Method'
    • error — функция которая будет вызвана, если сервер вдруг не сможет дать ответ, 500 ошибка на сервере к примеру, форматы функции такие же как и у success
    • completed — функция которая будет вызвана по завершению запроса, независимо от ответа с сервера
    • data — параметр который принимает любые данные, в любом формате и в любом уровне вложенности объекта, данный параметр передается «как есть» во все 3 callback функции success, error, completed в качестве второго параметра
Примеры вызова:
ajax('testAction', {name: "name",phone: "12345"});
ajax('testAction', {name: "name",phone: "12345"}, {success: 'FunctionName');
ajax('testAction', {name: "name",phone: "12345"}, {success: function(response, options){});
ajax('testAction', {name: "name",phone: "12345"}, {success: function(response, options){},error: 'FunctionErrorName');
ajax('testAction', {name: "name",phone: "12345"}, {success:'Object,MethodName',data:{param1:'1',param2:'2',currentObj: this});
Обработка результата:
function FunctionName(response, options){
	if(response.success){
	}
	if(!response.success){
	}
response.message;
	options.param1;
	options.param2;
	options.currentObj;
}

Управление данными на сервере через файл "actions.class.php":
Все методы, автоматически обрабатываемые компонентом, должны начинаться с "public function action" и добавляться с большой буквы action отправляемый с клиентской стороны (все буквы параметра action, необходимо писать с маленькой, кроме первой).
Примеры:
public function actionTestaction(){}
public function actionLoadfiledata(){}
public function actionSetnewdate(){}
Это основные методы обработчики, в них необходимо возвращать результат работы AJAX.
Есть еще методы обработчики, которые вызываются перед методами с префиксов 'action', это такие же методы только с префиксом 'before' (не являются обязательными, просто предлагают некоторые комфортные фишки и на каждый метод 'action' можно делать отдельные 'before'), примеры для методов выше:
public function beforeTestaction(){}
public function beforeLoadfiledata(){}
public function beforeSetnewdate(){}
Эти методы не предназначены для возврата чего либо через 'return', но у них есть такая возможность. При возврате чего либо через 'return', основной метод 'action' не будет запущен.

Форматы возвращаемых данных, которые можно использовать.
Может быть массив или строка.

  • return 'Текст' — вернет клиенту {success:false, message: 'Текст'} // ошибка
  • return ['message'=>'Текст'] — {success:false, message: 'Текст'} // ошибка
  • return ['success'=>true, 'message'=>'Текст'] — {success:true, message: 'Текст'} // успех
  • return ['message'=>'Текст', 'errors'=>['name'=>'Empty name','phone'=>'Phone is not valid']] — {success:false, message: 'Текст', errors: {name:'Empty name',phone:'Phone is not valid'}} // ошибка и возврат ошибок для каждого поля отдельно
  • return ['success'=>true, 'text': 'Какой-то текст'] — {success:true, text: 'Какой-то текст'} // успех и возврат контента для блока указанного в AJAX запросе на стороне клиента
  • return ['success'=>true, 'text': ['text1'=>'Какой-то текст','text2'=>'Какой-то текст 2']] — {success:true, [{text1: 'Какой-то текст',text2: 'Какой-то текст 2'}]} // успех и возврат контента для блока указанного в AJAX запросе на стороне клиента, только будут использоваться правила для массива данных
  • return ['success'=>true, 'text': ['text1'=>'Какой-то текст','text2'=>'Какой-то текст 2']] — {success:true, [{text1: 'Какой-то текст',text2: 'Какой-то текст 2'}]} // успех и возврат контента для блока указанного в AJAX запросе на стороне клиента, только будут использоваться правила для массива данных
  • return ['success'=>true,'customParam1' => 'Какой-то текст или параметр','customParam2' => 'Какой-то текст или параметр 2'] — {success:true, customParam1: 'Какой-то текст или параметр',customParam2: 'Какой-то текст или параметр 2'} // успех и возврат кастомных параметров с данными, любое кол-во в любом объеме в котором позволяет сервер
  • return $this->modx->runProcessor('processor/name',$this->data)->response; // запуск любого процессора и возврат данных клиенту
Во всех методах доступ к данным от клиента, можно получить через $this->data[]
$this->data['name'];
$this->data['phone'];
Также доступен объект модекса через
$this->modx;
Список запрещенных полей или запрещенных, можно использовать как в методах 'action' так и в 'before'. Обычно нет смысла использовать обе функции вместе. Обе функции изменяют массив $this->data и указывать список полей необходимо через запятую. Примеры вызова:
$this->allow('name,phone'); // убирает из массива все поля кроме указанных
$this->exclude('name,phone'); // убирает из массива указанные поля
Валидация полей (поля указываются через запятую), фильтры для одного и того же поля можно группировать или разбивать (необходимо делать в методах 'before'):
$this->validate('name:required,phone:required,email:required:email');
$this->validate('name:required,phone:required,email:required,email:email');
Формат "ИмяПоля: Фильтр: Фильтр: Фильтр:...".
Формат «Фильтр» — "НазваниеФильтра=ДопОпции=ПользовательскийТекстСообщения"
ДопОпции — доступны не всем фильтрам, если нет доп опций или не указываются, формат может выглядеть так: "НазваниеФильтра==ПользовательскийТекстСообщения"
ПользовательскийТекстСообщения — необязательный, может быть ключом загруженного лексикона, если не указывается, тогда используется стандартный текст
НазваниеФильтра:
  • required — поле обязательно для заполнения
  • email — значение должно быть в формате email (русские символы в адресе не поддерживаются)
  • minlength — минимальное кол-во символов, ДопОпция — кол-во символов
  • maxlength — максимальное кол-во символов, ДопОпция — кол-во символов
  • numeric — значение должно быть числом
  • minvalue — минимальное числовое значение, ДопОпция — кол-во символов
  • maxvalue — максимальное числовое значение, ДопОпция — кол-во символов
  • mincount — минимальное кол-во элементов в массиве, ДопОпция — кол-во элементов
  • maxcount — максимальное кол-во элементов в массиве, ДопОпция — кол-во элементов
  • match — проверяет на обязательное совпадение значений в полях, ДопОпция — второе поле для сравнения, является главным при проверке
  • filerequired — файл должен быть добавлен и загружен
  • filesize — максимальный размер файла, ДопОпция — размер файла в 4 форматах: 123 или 123B (байты), 123KB, 123MB, 123GB
  • fileextension — расширение файла, ДопОпция — список расширений файла через запятую: jpg,png,...
  • filemime — mime type файла, ДопОпция — список типов через запятую: application/pdf,image/jpeg,…
  • fileimage — проверка файла на изображение
Есть возможность переопределить стандартный alert компонента, для этого необходимо в своем JS файле прописать
$(document).ready(function () {
// сообщение об успешном завершении запроса
// сервер прислал параметр success:true
ajaxMessage.success = function (msg) {
       alert(msg);
};
// сообщение об ошибке
// сервер прислал параметр success:false
ajaxMessage.error = function (msg) {
        alert(msg);
};
});

Форма для примера
Файл "actions.class.php":
<?php

class ajaxCustomActions extends ajaxActions
{
    public function beforeSendfirstform()
    {
        $this->allow('name,phone,email');
        $this->validate('name:required:minlength=3:maxlength=10,phone:required:numeric,email:required:email');
    }

    public function actionSendfirstform()
    {
        return [
            'success' => true,
            'message' => 'Сообщение отправлено',
            'text'=>'Понадобилось вывести этот текст при успешном завершении запроса'
        ];
    }
}

return 'ajaxCustomActions';
HTML разметка
<form class="js_ajax_form" data-action="sendFirstForm" data-clear="1" data-text=".response_block">
    <div class="js_ajax_alert_error">
    	<div class="js_text"></div>
    </div>
    <div class="js_ajax_alert_success">
    	<div class="js_text"></div>
    </div>
    <hr>
    <div class="js_ajax_wrapper">
    	<input type="text" name="name">
    	<div class="js_ajax_error"></div>
    </div>
    <div class="js_ajax_wrapper">
    	<input class="js_ajax_clear" type="text" name="phone">
    	<div class="js_ajax_error"></div>
    </div>
    <div class="js_ajax_wrapper">
    	<input class="js_ajax_clear" type="text" name="email">
    	<div class="js_ajax_error"></div>
    </div>
    <button type="submit">Отправить</button>
</form>
<hr>
<div class="response_block"></div>

Последние обсуждения в сообществе MODX.pro