AJAX-части в плагинах Cotonti Siena

Введение в AJAX-части плагинов

В Cotonti Siena AJAX-части плагинов представляют собой самостоятельные обработчики, которые выполняются без подключения файлов header.php и footer.php. Эти части используют хук ajax и вызываются через URL вида plug.php?r=yourplug. При таком вызове Cotonti Siena подключает один из файлов плагина, например plugins/yourplug/yourplug.php или plugins/yourplug/yourplug.ajax.php, или любой другой файл, определённый как AJAX-часть.

AJAX-части предназначены для обработки асинхронных запросов, что позволяет обновлять содержимое страницы без полной перезагрузки. В версии Cotonti Siena 0.9.25, выпущенной 3 сентября 2024 года, механизм AJAX-частей плагинов остаётся неизменным по сравнению с предыдущими версиями начиная с 0.9.0, без зафиксированных изменений в релиз-нотах.

Создание AJAX-части плагина

Для создания AJAX-части в плагине Cotonti Siena выполните следующие шаги:

1. Создайте файл части плагина, например my_plug.ajax.php. Имя файла может быть любым.
2. В заголовке файла укажите хук: Hook=ajax.
3. Программируйте файл как обычный плагин, учитывая, что файлы header.php и footer.php не подключаются. Перед выводом любых данных можно отправлять HTTP-заголовки с помощью функции header().
4. Вызывайте AJAX-часть через URL: plug.php?r=my_plug.

В Cotonti Siena при асинхронном запросе страницы система автоматически устанавливает константу COT_AJAX в значение TRUE. В обычном режиме запроса эта константа равна FALSE. Константа доступна из любого места кода и может использоваться для определения специфического поведения:

PHP

if (COT_AJAX) {
 // Код, специфичный для AJAX-режима
} else {
 // Код для обычного режима
}
// Общий код

В AJAX-режиме Cotonti Siena не выводит заголовок и футер страницы, хотя файлы header.php и footer.php всё равно включаются для согласованности.

Вызов AJAX-части через JavaScript

AJAX-часть можно вызывать из JavaScript. В Cotonti Siena для этого используется библиотека jQuery. Пример вызова с методом GET:

JavaScript

$.get('plug.php?r=my_plugin', { id: 123, name: 'Peter' },
 function(data){
 alert("Data Loaded: " + data);
 });

Пример вызова с методом POST:

JavaScript

$.post('plug.php?r=my_plugin', { a: 'send', name: 'Peter' },
 function(data){
 alert("Data Loaded: " + data);
 });

Защита от XSS-атак

В Cotonti Siena при отправке форм через GET (в некоторых случаях) или POST (всегда) необходимо передавать параметр защиты x для предотвращения XSS-атак. Значение параметра x генерируется функцией sed_sourcekey() (в более поздних версиях Cotonti Siena это cot_sourcekey(), но в документации используется sed_sourcekey() для совместимости).

Пример PHP-кода для генерации JavaScript с GET-запросом и параметром x:

PHP

$t->assign('MY_JS_FUNC', "$.get('plug.php?r=my_plugin', { id: $id, x: '" . sed_sourcekey() . "' },
 function(data){
 alert('Data Loaded: ' + data);
 });");

Пример PHP-кода для генерации JavaScript с POST-запросом и параметром x:

PHP

$t->assign('MY_JS_FUNC', "$.post('plug.php?r=my_plugin', { a: 'send', name: 'Peter', x: '" . sed_sourcekey() . "' },
 function(data){
 alert('Data Loaded: ' + data);
 });");

Отправка форм через AJAX

В Cotonti Siena для отправки формы через AJAX используется функция ajaxSend(), которая автоматически собирает данные формы. Пример использования:

JavaScript

ajaxSend({
 url: 'plug.php?r=my_plugin',
 method: 'POST',
 formId: 'myformid'
});

Эта функция доступна, если в настройках администрации Cotonti Siena включены jQuery и AJAX (Администрирование => Конфигурация => Основные настройки).

Автоматическое включение AJAX для ссылок и форм

В Cotonti Siena поддерживается автоматическое включение AJAX для ссылок и форм, если jQuery и AJAX активированы в настройках. Для ссылок добавьте класс ajax к тегу <a>:

HTML

<a href="page.php?al=my_page" class="ajax">Load my page in div</a>

Результат загружается в див с id ajaxBlock по умолчанию.

Для форм добавьте класс ajax к тегу <form> и укажите уникальный id:

HTML

<form id="my_form" action="{MY_FORM_ACTION}" method="post" class="ajax">
 <input type="text" class="text" name="title" value="{MY_FORM_TITLE}" />
 <input type="submit" class="submit" value="{PHP.L.Submit}" />
</form>

Данные формы отправляются асинхронно, результат отображается в ajaxBlock.

Для указания целевого дива в формах используйте синтаксис класса с хэш-адресом, например class="ajax post-myDivId". Для ссылок укажите в атрибуте rel:

HTML

<a href="page.php?al=my_page" class="ajax" rel="get-myDivId">Load my page in div</a>

Хэш-адреса в AJAX

В Cotonti Siena хэш-адреса используются для поддержки закладок и истории браузера в AJAX-приложениях. Формат хэш-адреса:

text

get|post[-DIV_ID][;PATH_TO_SCRIPT][;QUERY_STRING]

• get или post — метод запроса.
• DIV_ID — id целевого дива (опционально).
• PATH_TO_SCRIPT — относительный путь к скрипту (опционально, если совпадает с текущим).
• QUERY_STRING — параметры запроса, разделённые &.

Примеры хэш-адресов:

• get;m=config&s=main — запрос текущего скрипта с параметрами m=config&s=main в ajaxBlock.
• get-container;m=config&s=main — то же, но в див container.
• get;list.php;c=articles — загрузка list.php?c=articles в ajaxBlock.
• get-mainPreview;index.php; — загрузка index.php в див mainPreview.
• get-posts;plug.php;e=posts&id=123 — вывод в див posts результата plug.php?e=posts&id=123.
• post-form_container;plug.php;e=submitter — для POST-форм, отправка в plug.php?e=submitter.

Хэш-адреса можно использовать в адресной строке после #, в атрибуте rel ссылок или в классе форм. Для POST-форм хэш-адреса не влияют на историю браузера.

URL можно генерировать функцией cot_url(), заменяя ? на ; для совместимости.

Поддержка пагинации в AJAX

В Cotonti Siena функция cot_pagenav() поддерживает AJAX. Сигнатура функции:

PHP

function cot_pagenav($module, $params, $current, $entries, $perpage, $characters = 'd', $hash = '', $ajax = false, $target_div = '', $ajax_module = '', $ajax_params = array());

• $module — имя модуля или скрипта.
• $params — параметры URL.
• $current — текущая страница.
• $entries — общее количество записей.
• $perpage — записей на страницу.
• $characters — символ для параметра пагинации.
• $hash — хэш-часть URL.
• $ajax — флаг включения AJAX (по умолчанию false).
• $target_div — id целевого дива.
• $ajax_module — имя модуля для AJAX, если отличается.
• $ajax_params — параметры для AJAX.

Пример базовой пагинации:

PHP

$pagenav = cot_pagenav('plug', 'e=myplug&item=' . $item_id, $d, $totalitems, $perpage);

С включением AJAX:

PHP

$pagenav = cot_pagenav('plug', 'e=myplug&item=' . $item_id, $d, $totalitems, $perpage, 'd', '', true);

С указанием целевого дива:

PHP

$pagenav = cot_pagenav('plug', 'e=myplug&item=' . $item_id, $d, $totalitems, $perpage, 'd', '', true, 'myDivId');

Если URL для AJAX отличаются:

PHP

$pagenav = cot_pagenav('users', 'm=details&id=' . $urr['user_id'] . '&u=' . $urr['user_name'], $dpt, $pt_items, $pt_perpage, 'dpt', '', true, 'points', 'plug', 'e=points&uid=' . $urr['user_id']);

Функция возвращает ассоциативный массив: ['prev'], ['main'], ['next'], ['last'].

Кастомное программирование на клиентской стороне

В Cotonti Siena доступна переменная ajaxEnabled, указывающая, включён ли AJAX в настройках ( true или false):

JavaScript

if (ajaxEnabled) {
 // AJAX-код
}

Функция ajaxSend() принимает объект настроек для отправки запросов. Пример базовой структуры:

JavaScript

var mySettings = {
 method: 'GET',
 // Другие параметры
};
ajaxSend(mySettings);

Доступны параметры: method (GET или POST), url, data, formId (для автоматического сбора данных формы), и другие для обработки запросов.

Cotonti Siena поддерживает jQuery для продвинутых AJAX-операций, включая обработку XML и JSON.