-
Notifications
You must be signed in to change notification settings - Fork 52
Модификация поведения плагина: общие сведения
Если вы разработчик, у вас есть возможность модифицировать поведение Лейки с точки зрения пользователя, включая отображение различных визуальных компонентов (виджетов, шорткодов и т.д.).
В своей работе Лейка полагается на систему хуков WordPress (hooks). Фактически, это означает, что при выполнении каждого процесса (например, совершения пожертвования) у плагина есть "поведение по умолчанию". Поведение в рамках этого процесса логически разделяется на этапы - каждый этап получает на входе определённые данные и должен выполнить определённые действия.
Эти этапы программного процесса и обслуживаются хуками. Хуки бывают двух видов:
- action ("действие"). Может получать на входе ряд параметров. Не возвращает значения.
- filter ("фильр"). Обязательно получает на входе как минимум один параметр. Обязательно возвращает значение.
У каждого хука (любого из этих двух типов) обязательно есть название (строка). Все хуки в Лейке имеют название, начинающееся с "leyka_" (например, "leyka_init_actions").
Как и все остальные хуки WordPress, хуки Лейки применяются плагином с помощью функций do_action() и apply_filters().
Соответственно, добавить собственный код на каждый хук можно с помощью функций add_action() и add_filter().
Пожертвование считается оплаченным, когда оно получает статус "оплачено" (funded). При изменении статуса записи типа "leyka_donation" либо на "funded", либо с "funded" на любой другой, вызывается хук-action "leyka_donation_funded_status_changed":
do_action('leyka_donation_funded_status_changed', $donation->id, $old, $new);
Здесь видно, какие параметры принимает этот action:
- первый по счёту параметр ($donation->id) - целое число, идентификатор поста-пожертвования;
- второй параметр ($old) - статус пожертвования до его изменения;
- третий параметр ($new) - статус пожертвования после изменения (то есть новый статус).
Например, мы хотим отправлять отдельное email-уведомление администратору сайта, если проводится новое рекуррентное пожертвование, причём только в случае самой рекуррентной подписки (дальнейшие списания по подписке нас не интересуют).
Это можно было бы сделать с помощью следующего кода:
add_action('leyka_donation_funded_status_changed', function($donation_id, $old_status, $new_status){
if($new !== 'funded') { // применять наш код только если пожертвование становится оплаченным
return;
}
$donation = new Leyka_Donation($donation_id);
if( !$donation->is_init_recurring_donation ) { // применять наш код только в случае оплаты рекуррентной подписки
return;
}
// все условия соблюдены, отправляем письмо:
wp_mail('[email protected]', 'Новая рекуррентная подписка!', "Добрый день! На сайте появилась новая рекуррентная подписка с ID = {$donation_id}");
}, 11, 3);
1.2. Пример использования filter: добавление новой иконки в список для способа оплаты на форме пожертвования
На форме для пожертвования при выборе каждого способа оплаты автоматически отображаются соотв. иконки (например, иконки Visa, MasterCard, ЮKassa и др.). Список иконок для каждого способа оплаты можно поменять - например, убрать ненужные иконки или добавить в него собственные. Для этого служат хуки-фильтры "leyka_icons_{$gateway_id}_{$payment_method_id}".
Примечание: в этом примере название хука содержит переменные, т.к. для каждого конкретного способа оплаты хук будет иметь немного отличающееся название. Например, для способа оплаты "банковская карта" (ID = "card") в платёжном операторе CloudPayments (ID = "cp") хук будет называться "leyka_icons_cp_card".
Мы можем добавить иконку в список следующим образом:
add_filter('leyka_icons_cp_card', function($icons_list){
$icons_list[] = '//our-site.org/wp-content/uploads/img/our-new-icon.svg';
return $icons_list; // хук-фильтр обязательно должен возвращать значение
}, 11, 1);
В предыдущем разделе страницы рассказывалось о том, как может выглядеть кастомный код, который модифицирует поведение плагина. В этом разделе будут описаны способы добавления этого кастомного кода на сайт.
Примечание: если просто изменить файлы плагина - например, добавить код в один из его файлов - то он исчезнет при обновлении Лейки, т.к. изменённый файл будет автоматически перезаписан его "штатной" версией.
Чтобы этого избежать, можно использовать один из следующих подходов:
Если тема вашего сайта не будет обновляться (например, если она разработана вручную), можно добавить кастомный код в файл functions.php. Этот файл есть у каждой темы сайта. Пример для п.1.2 выше:
add_filter('leyka_icons_cp_card', function($icons_list){
$icons_list[] = '//our-site.org/wp-content/uploads/img/our-new-icon.svg';
return $icons_list; // хук-фильтр обязательно должен возвращать значение
}, 11, 1);
Если тема сайта будет обновляться, размещать код в ней не стоит, т.к. он будет перезаписан при её обновлении. В этом случае нужно будет создать отдельный мини-плагин для сайта и поместить кастомный код в него.
В простейшем случае, плагин WordPress - это просто единственный файл, который помещён в папку /wp-content/plugins/ и имеет нужный заголовок-комментарий. Подробно о том, как создать собственный мини-плагин и добавить его на сайт, можно прочитать здесь.
В остальном кастомный код будет выглядеть так же, как и в примере из пп. 2.1. Изменится только то, что он будет в файле плагина, а не в файле functions.php в папке темы сайта.