Сайт справки

108 AJAX

October включает инфраструктуру AJAX, которая позволяет вам выполнять обработчики AJAX, определенные в ваших страницах, макетах or компонентах и обновлять блоки страниц с помощью чанков. AJAX фреймворк поставляется в двух вариантах - в виде API JavaScript и API атрибутов данных. API атрибутов данных не требует знания JavaScript для использования AJAX с October.

Введение

Чтобы использовать фреймворк AJAX, он должен быть включен, помещением тега {% framework %} где-нибудь внутри страницы или макета. Это добавляет ссылку на библиотеку JavaScript для интерфейсов October. Библиотека требует jQuery, поэтому она должна быть загружена первой, например:

<script src="/{{ [
    'assets/javascript/jquery.js',
]|theme }}"></script> 

{% framework %}

Тег {% framework %} поддерживает необязательный параметр extras. Если этот параметр указан, тег добавляет файлы CSS и JavaScript, которые содержат плагин индикатора загрузки и классы CSS для стилизации индикатора загрузки. При запуске запроса AJAX индикатор отображается в верхней части страницы.

{% framework extras %}

Как AJAX обрабатывает запрос

Страница может выдавать запрос AJAX с атрибутами данных или с помощью JavaScript. Каждый запрос вызывает обработчик событий на сервере и может обновлять элементы страницы с помощью чанков. Запросы AJAX работают лучше всего с формами, поскольку данные формы автоматически отправляются на сервер. Последовательность запросов AJAX:

  1. Клиент выдает запрос AJAX, предоставляя имя обработчика AJAX и необязательно другие параметры.
  2. Сервер находит обработчик AJAX и выполняет его.
  3. Обработчик выполняет требуемую бизнес-логику и обновляет среду Twig, вставляя переменные страницы.
  4. Сервер отображает частичные данные, запрошенные клиентом с помощью опции update.
  5. Сервер отправляет ответ, содержащий разметку с отрендеренными чанками.
  6. Фреймворк клиентской стороны обновляет элементы страницы с блоками данных, полученными с сервера.

Ниже приведен простой пример использования API атрибутов данных для формы калькулятора AJAX. Форма ссылается на пример обработчика onTest, продемонстрированный в разделе Обработчики Ajax ниже. Пример можно легко преобразовать для использования [JavaScript API] (#javascript-api).

<form data-request="onTest" data-request-update="calcresult: '#result'">
    <input type="text" name="value1"/>
    <input type="text" name="value2"/>
    <input type="submit" value="Calculate">
</form>
<div id="#result"></div>

Конфигурация формы из предыдущего примера может быть прочитана следующим образом: «Когда форма отправлена, отправить запрос AJAX обработчику onTest . Когда обработчик закончит, отрендерить calcresult и добавить его содержимое в элемент #result.". Ниже приведен пример чанка calracesult. Он в основном выводит переменную result, подготовленную обработчиком AJAX.

The result is {{ result }}

Обработчики Ajax

Обработчики AJAX - это функции PHP, которые могут быть определены на странице или в блоках PHP кода макета или внутри компонентов. Имена обработчиков должны соответствовать следующему шаблону: onName. Обработчики могут вводить переменные среды Twig, где они могут использоваться во время рендеринга чанка. В следующем примере показан Ajax обработчик, определенный в разделе PHP страницы. Обработчик загружает два значения POST и вводит переменную страницы result.

url = "js"
layout = "default"
==
function onTest()
{
    $value1 = post('value1');
    $value2 = post('value2');
    $this['result'] = $value1 + $value2;
}
==

Обратите внимание: Если два обработчика с одинаковым именем, определенным вместе на странице и макете, будут выполняться обработчик страниц. У обработчиков, определенных в компонентах, самый низкий приоритет.

API атрибутов данных

API атрибутов данных позволяет отправлять запросы AJAX без JavaScript. Во многих случаях API атрибутов данных менее подробный, чем JavaScript API - вы пишете меньше кода, чтобы получить тот же результат. Поддерживаемые атрибуты данных AJAX:

  • data-request - указывает имя обработчика AJAX.
  • data-request-confirm - указывает подтверждающее сообщение. Подтверждение отображается до отправки запроса. Если пользователь нажимает кнопку «Отмена», запрос не отправляется.
  • data-request-redirect - указывает URL-адрес для перенаправления браузера после успешного запроса AJAX.
  • data-request-update - задает список фрагментов и элементов страницы (селекторов CSS) для обновления. Формат следующий: чанк: селектор, чанк: селектор. В некоторых случаях требуется использование кавычек, например: 'my-partial': '# myelement'. Если перед селекторной строкой стоит символ @, содержимое, полученное с сервера, будет добавлено к элементу вместо замены существующего содержимого.
  • data-request-data - указывает дополнительные параметры POST, отправляемые на сервер. Формат следующий: var: value, var: value. При необходимости используйте амперсанды: var: 'some string'. Атрибут может использоваться в элементе триггера, например, на кнопке, которая также имеет атрибут data-request, в ближайшем элементе триггерного элемента и в элементе родительской формы. Структура объединяет значения атрибутов data-request-data. Если атрибут в разных элементах определяет параметры с одним и тем же именем, структура использует следующий приоритет: триггерный элемент data-request-data, более близкие родительские элементыdata-request-data, входные данные формы.
  • data-request-before-update - указывает код JavaScript для выполнения непосредственно перед обновлением содержимого страницы. Внутри кода JavaScript вы можете получить доступ к следующим переменным: $el (элемент страницы вызвавший запрос), объект context, объект data, полученные с сервера, текстовую строкуtextStatus и строку JqXHR.
  • data-request-success - указывает код JavaScript, который будет выполняться после успешного завершения запроса. Внутри кода JavaScript вы можете получить доступ к следующим переменным: $el (элемент страницы вызвавший запрос), объект context, объект data, полученные с сервера, текстовую строкуtextStatus и строку JqXHR.
  • data-request-error - указывает код JavaScript для выполнения, если запрос встречает ошибку. Внутри кода JavaScript вы можете получить доступ к следующим переменным: $el (элемент страницы вызвавший запрос), объект context, объект data, полученные с сервера, текстовую строкуtextStatus и строку JqXHR.
  • data-request-loading - определяет селектор CSS для элемента, отображаемого во время выполнения запроса. Вы можете использовать эту опцию для отображения индикатора загрузки AJAX. Функция использует функции jQuery show () и hide () для управления видимостью элемента.
  • data-track-input - может быть применено к полю ввода текста или пароля, которое также имеет атрибут data-request. Когда определено, поле ввода автоматически отправляет запрос AJAX, когда пользователь что-либо вводит в поле. Необязательное значение атрибута может определять интервал, в миллисекундах, время ожидания фреимворка перед отправкой запросов.

Когда для элемента задан атрибут data-request, элемент инициирует запрос AJAX, когда пользователь взаимодействует с ним. В зависимости от типа элемента запрос запускается в следующих случаях:

  • Формы - при отправке формы.
  • Ссылки, кнопки - при щелчке по элементу.
  • Поля для ввода текста и пароля - когда текст изменяется и только если представлен атрибут data-track-input.
  • Раскрывающиеся списки, флажки, радиокнопки - когда элемент выбран.

Примеры API атрибутов данных

Запустить обработчик onCalculate, когда форма отправлена. Обновит элемент с идентификатором "result" с чанком calcresult:

<form data-request="onCalculate" data-request-update="calcresult: '#result'">

Запросить подтверждение при нажатии кнопки «Удалить» до отправки запроса:

<form ... >
    ...
    <button data-request="onDelete" data-request-confirm="Are you sure?">Delete</button>

Перенаправить на другую страницу после успешного запроса:

<form data-request="onLogin" data-request-redirect="/admin">

Показывать всплывающее окно после успешного запроса:

<form data-request="onLogin" data-request-success="alert('Yay!')">

Отправит параметр POST mode со значениемupdate:

<form data-request="onUpdate" data-request-data="mode: 'update'">

Отправит параметр POST id со значением7 для нескольких элементов:

<div data-request-data="id: 7">
    <button data-request="onDelete">Delete</button>
    <button data-request="onSave">Update</button>
</div>

JavaScript API

JavaScript API является более мощным, чем API атрибутов данных. Метод request () можно использовать с любым элементом, находящимся внутри формы, или с элементом формы. Когда метод используется с элементом внутри формы, он пересылается в форму.

Метод request () имеет единственный обязательный параметр - имя обработчика AJAX. Пример:

<form onsubmit="$(this).request('onProcess'); return false;">
    ...

Второй атрибут метода request() - это объект options. Вы можете использовать любые опции и методы, совместимые с функцией jQuery AJAX. Для фреймворка October определены следующие параметры:

  • update - объект, задает список чанков и элементов страницы (как селекторы CSS) для обновления: {'чанк': '#select'}. Если перед селекторной строкой стоит символ @, содержимое, полученное с сервера, будет добавлено к элементу вместо замены существующего содержимого.
  • confirm - строка подтверждения. Если установлено, подтверждение отображается до отправки запроса. Если пользователи нажимают кнопку «Отмена», запрос отменяется.
  • data - необязательный объект, указывающий данные, отправляемые на сервер вместе с данными формы: {var: 'value'}.
  • redirect строка, указывающая URL-адрес для перенаправления браузера на после успешного запроса.
  • beforeUpdate - функция обратного вызова, выполняемая перед обновлением элементов страницы. Функция получает 3 параметра: объект данных, полученный с сервера, текстовая строка состояния и объект jqXHR. Переменная this внутри функции разрешает содержимое запроса - объект, содержащий 2 свойства: "handler" и "options", представляющие исходные параметры request().
  • success - функция обратного вызова для выполнения в случае успешного запроса. Если эта опция включена, она отменяет функциональность фреймворка по умолчанию: элементы не обновляются, событие beforeUpdate не запускается, событияajaxUpdate и ajaxUpdateComplete не срабатывают. Обработчик события получает 3 аргумента: объект данных, полученный с сервера, текстовая строка состояния и объект jqXHR. Тем не менее, вы по-прежнему можете вызвать функцию фреймворка по умолчанию, вызывая this.success(...) внутри вашей функции.
  • error - функция обратного вызова выполняется в случае ошибки. По умолчанию выводится предупреждение. Если эта опция переопределена, предупреждение не будет отображаться. Обработчик получает 3 параметра: объект jqXHR, текстовую строку состояния и объект ошибки - см. Функция AJAX jQuery.
  • complete - функция обратного вызова выполняется в случае успеха или ошибки.

Примеры API JavaScript

Запросит подтверждение перед отправкой запроса на удаление:

$('form').request('onDelete', {
    confirm: 'Are you sure?', 
    redirect: '/dashboard'
})

Выполнить обработчик onCalculate и вставить обработанный чанком calracesult результат в элемент страницы с CSS классом result:

$('form').request('onCalculate', {
    update: {calcresult: '.result'}
})

Запустит обработчик onCalculate с некоторыми дополнительными данными:

$('form').request('onCalculate', {data: {value: 55}})

Запустит обработчик onCalculate и запустит некоторый корректирующий код перед обновлением элементов страницы:

$('form').request('onCalculate', {
    update: {calcresult: '.result'}, 
    beforeUpdate: function(){ /* do something */ }
})

Запустит обработчик onCalculate и, если он будет успешным, запустит некоторый корректирующий код и функцию success по умолчанию:

$('form').request('onCalculate', {success: function(data){
    //... do something ...
    this.success(data);
}})

Выполнит запрос без элемента FORM:

$.request('onCalculate', {
    success: function(){
        console.log('Finished!')
    }
})

Запустит обработчик onCalculate и, если успешно, запустит некоторый корректирующий код после выполнения функции success по умолчанию:

$('form').request('onCalculate', {success: function(data){
    this.success(data).done(function() {
        //... do something after parent success() is finished ...
    });
}})

Вызов обработчиков AJAX, определенных в компонентах

Если вам нужно отправить запрос обработчику AJAX, определенному в компоненте, прикрепленном к странице или макету, вы должны указать префикс имени обработчика с кратким именем компонента или его [алиасом] (./cms-components.md#aliases). Следующий пример демонстрирует, как вызвать AJAX обработчик onCalculate, определенный в воображаемом компоненте calculator:

<form data-request="calculator::onCalculate" data-request-update="calcresult: '#result'">

Глобальные события AJAX

Структура AJAX запускает несколько событий над обновленными элементами, формой и объектом окна. События запускаются независимо от того, какой API был использован - API атрибутов данных или API JavaScript.

  • ajaxUpdate - запускается для элемента страницы после того, как он обновлен фреймворком. Обработчик получает 5 параметров: объект события, контекстный объект, объект данных, полученный от сервера, текстовую строку состояния и объект jqXHR.
  • ajaxUpdateComplete - запускается для объекта window после того, как все элементы обновляются фреймворком. Обработчик получает 5 параметров: объект события, контекстный объект, объект данных, полученный от сервера, текстовую строку состояния и объект jqXHR.
  • ajaxBeforeUpdate - запускается в объекте формы сразу после завершения запроса, но до обновления страницы. Обработчик получает 5 параметров: объект события, контекстный объект, объект данных, полученный от сервера, текстовую строку состояния и объект jqXHR.
  • ajaxSuccess - запускается в объекте формы после того, как запрос будет успешно завершен. Обработчик получает 5 параметров: объект события, контекстный объект, объект данных, полученный от сервера, текстовую строку состояния и объект jqXHR.
  • ajaxError - запускается в объекте формы, если запрос встречает ошибку. Обработчик получает 5 параметров: объект события, контекстный объект, текстовую строку состояния и объект jqXHR.

В следующем примере выполняется код JavaScript, когда событие ajaxUpdate запускается для элемента.

$('.calcresult').on('ajaxUpdate', function(){
    console.log('Updated!');
})

Возврат данных из обработчиков AJAX

В продвинутых случаях вы можете захотеть вернуть структурированные данные из ваших обработчиков AJAX. Если AJAX-обработчик возвращает массив, вы можете получить доступ к его элементам в обработчике событий success. Пример обработчика AJAX:

function onFetchDataFromServer()
{
    /* Какай нибудь код на стороне сервера */

    return [
        'totalUsers'=>1000,
        'totalProjects'=>937
    ];
}

Данные могут быть получены с помощью атрибутов данных API:

<form data-request="onHandleForm" data-request-success="console.log(data)">

То же самое с JavaScript API:

<form
    onsubmit="$(this).request('onHandleForm', {
        success: function(data){
            console.log(data)
        }
    }); return false;">

Перенаправления в обработчиках AJAX

Если вам нужно перенаправить браузер в другое место, верните объект Redirect из обработчика AJAX. Фреймворк будет перенаправлять браузер, как только ответ будет возвращен с сервера. Пример обработчика AJAX:

function onRedirectMe()
{
    return Redirect::to('http://google.com');
}

Наверх

© Сайт справки 2024