Использование библиотеки TGM Plugin Activation в своих темах WordPress

Темы обычно не являются функциональными, однако иной раз нам, разработчикам, требуется внедрить некоторые возможности в нашу тему, чтобы сделать ее чуть лучше и удобнее.

В этом руководстве мы рассмотрим термин «территория плагинов», а также научимся использовать фантастический инструмент, написанный Томасом Гриффином: библиотеку TGM Plugin Activation.

Функциональность темы: вторжение на территорию плагинов

Темы предназначены для того, чтобы изменить дизайн веб-сайта WordPress. В идеале тема должна затрагивать только визуальный аспект. Однако в нашем «золотом веке» WordPress разработчики плагинов зачастую включают в свои темы функциональные особенности, которые позволяют сохранить конкурентоспособность на рынке.

Это вторжение на территорию плагинов. Мы можем представить «территорию плагинов», как некоторые функциональные участки кода. Любой фрагмент кода, меняющий функциональность вашего сайта, должен быть представлен в виде плагина, если указанный код не заложен в ядро WordPress.

Я уже сформулировал ранее в одной из своих статей эмпирическое правило «территории плагинов:

Если особенность связана с визуальным представлением сайта, то в таком случае она должна быть включена в тему; если же она связана с функциональностью, то тогда она должна быть представлена в виде отдельного плагина.

Довольно простое правило. Люди по-прежнему стараются прописать на уровне кода функциональные фрагменты в своих темах, однако каталоги тем (такие как WordPress.org или ThemeForest) не принимают темы, которые вторгаются на «территорию плагинов». Таким образом, предложение функциональности в темах стало определенной проблемой.

К счастью, есть простое решение, которое не идет вразрез с правилом «территории плагинов».

Введение в библиотеку TGM Plugin Activation

TGM Plugin Activation – это легкая библиотека, которая позволяет связать тему со всеми необходимыми плагинами. Идея проста: пользователь, устанавливающий тему, получает рекомендации по установке плагинов из хранилища WordPress.org, внешнего сайта или каталога тем. Вот как сам Томас Гриффин описал работу библиотеки:

TGM Plugin Activation – это PHP-библиотека, которая позволяет вам рекомендовать установку нужных плагинов для своих тем WordPress (и плагинов). Библиотека позволяет вашим пользователям устанавливать и даже автоматически активировать плагины по отдельности или массово, используя родные классы, функции и интерфейсы WordPress. Вы можете запросить установку архивированных плагинов, плагинов из хранилища WordPress, а также плагинов, которые хранятся в любых других участках сети.

Это, пожалуй, самое умное решение проблемы с вторжением на территорию плагинов. И его очень просто применить.

Давайте посмотрим, как это сделать.

Установка TGM Plugin Activation

Установка TGM Plugin Activation очень проста. Просто выполните следующие шаги:

  • Скачайте библиотеку TGM Plugin Activation из раздела Download
  • Откройте zip-архив и извлеките class-tgm-plugin-activation.php в папку с вашей темой
  • Откройте файл functions.php вашей темы и используйте функцию require_once(), чтобы потребовать файл класса в вашей теме.
  • Создайте функцию для настройки TGM Plugin Activation и подцепите ее к tgmpa_register через функцию add_action().
  • Готово!

Все очень просто! Вам даже не нужно писать PHP-код, чтобы потребовать или порекомендовать плагины. Взгляните на код ниже:

<?php
 
/**
 * Since I'm already doing a tutorial, I'm not going to include comments to
 * this code, but if you want, you can check out the "example.php" file
 * inside the ZIP you downloaded - it has a very detailed documentation.
 */
 
require_once dirname( __FILE__ ) . '/class-tgm-plugin-activation.php';
 
add_action( 'tgmpa_register', 'mytheme_require_plugins' );
 
function mytheme_require_plugins() {
 
    $plugins = array( /* The array to install plugins */ );
    $config = array( /* The array to configure TGM Plugin Activation */ );
 
    tgmpa( $plugins, $config );
 
}
 
?>

Теперь вы можете заставить своих пользователей установить новые плагины, настроив переменную $plugins в только что созданной функции.

Давайте посмотрим, как это сделать.

Установка плагинов с помощью TGM Plugin Activation

Как вы могли видеть выше, переменная $plugins является массивом. Чтобы определить плагины, которые требуется установить, вам нужно создать массивы внутри данного массива (чтобы задавать собственные параметры для каждого плагина). На деле все выглядит просто:

<?php
 
$plugins = array(
    array( /* my first plugin */ ),
    array( /* my second plugin */ ),
    array( /* my third plugin */ ),
    // ...
    array( /* my nth plugin */ )
);
 
?>

Вы можете использовать следующие параметры:

  • name (string, required) – название плагина
  • slug (string, required) – слаг плагина (обычно название его папки).
  • required (boolean, required) – если задано в true, ваша тема будет «требовать» плагин. Если false, то «рекомендовать» его.
  • source (string, в некоторых случаях required) – источник плагина. Если это плагин с WordPress.org, то в таком случае параметр не должен использоваться; иначе он требуется.
  • version (string, optional) – минимальная версия плагина. Если пользователь темы уже имеет требуемый плагин, но с версией ниже, чем минимальная, то TGM Plugin Activation уведомит пользователя о необходимости обновления.
  • force_activation (boolean, optional) – если задан в true, пользователь не сможет деактивировать плагин, пока ваша тема является активной. Немного раздражает, но очень важно для определенных случаев.
  • force_deactivation (boolean, optional) – если задан в true, плагин будет деактивирован, как только пользователь сменит тему.
  • external_url (string, optional) – если задан, название плагина будет привязано к данному адресу в уведомлении о требуемом плагине.

У вас есть три варианта, чтобы заставить ваших пользователей установить плагины с помощью TGM Plugin Activation: вы можете потребовать плагин либо из хранилища плагинов WordPress, либо из внешнего источника (такого как ваш собственный сервер или CDN), либо из папки с вашей темой (как, к примеру, /my-theme/plugins/shortcodes.zip).

Требование плагина из WordPress.org

<?php
 
$plugins = array(
    array(
        'name'      => 'BuddyPress',
        'slug'      => 'buddypress',
        'required'  => false, // this plugin is recommended
    )
);
 
?>

Требование плагина из внешнего источника

<?php
 
$plugins = array(
    array(
        'name'               => 'My Awesome Plugin',
        'slug'               => 'my-awesome-plugin',
        'source'             => 'http://files.my-website.com/my-awesome-plugin.zip',
        'required'           => true, // this plugin is required
        'external_url'       => 'http://my-website.com/introducing-my-awesome-plugin', // page of my plugin
        'force_deactivation' => true, // deactivate this plugin when the user switches to another theme
    )
);
 
?>

Требование плагина из папки с темой

<?php
 
$plugins = array(
    array(
        'name'               => 'My Super Sleek Slider',
        'slug'               => 'my-super-sleek-slider',
        'source'             => get_stylesheet_directory() . '/lib/plugins/my-super-sleek-slider.zip', // The "internal" source of the plugin.
        'required'           => true, // this plugin is required
        'version'            => '1.2', // the user must use version 1.2 (or higher) of this plugin
        'force_activation'   => false, // this plugin is going to stay activated unless the user switches to another theme
    )
);
 
?>

admin-notice

Настройка TGM Plugin Activation

Обратите внимание на функцию tgmpa() с двумя параметрами в самом конце кода. Второй параметр – это переменная $config, которая также является массивом, как и $plugins. Как и следует из ее названия, вы можете настраивать библиотеку TGM Plugin Activation с помощью данного массива. Переменная принимает и свой собственный набор опций:

  • id (string) – уникальный id для библиотеки TGM Plugin Activation в вашей теме. Это очень важно: если другие плагины также используют TGM Plugin Activation, разные ID предотвратят возможные конфликты.
  • default_path (string) – дефолтный абсолютный путь для плагинов в вашей теме. Когда вы установите его, вы сможете использовать название ZIP-файла в качестве значения параметра source для вашего плагина.
  • menu (string) – слаг меню для страницы установки плагинов.
  • has_notices (boolean) – если задан в true, администраторские уведомления будут выдаваться для требуемых/рекомендованных плагинов.
  • dismissible (boolean) – если задан в true, пользователь может «закрыть» уведомления.
  • dismiss_msg (string) – если опция dismissible задана в false, данное сообщение будет показано над администраторским уведомлением.
  • is_automatic (boolean) – если задано в true, плагины будут активированы после того, как пользователь согласится их установить.
  • message (string) – дополнительный HTML, выводимый перед таблицей плагинов.
  • strings (array) – массив, который включает в себя выводимые сообщения. Вы можете задавать их как транслируемые строки. Посмотрите файл example.php, чтобы увидеть полный список всех сообщений.

plugin-table

<?php
 
$config = array(
    'id'           => 'mytheme-tgmpa', // your unique TGMPA ID
    'default_path' => get_stylesheet_directory() . '/lib/plugins/', // default absolute path
    'menu'         => 'mytheme-install-required-plugins', // menu slug
    'has_notices'  => true, // Show admin notices
    'dismissable'  => false, // the notices are NOT dismissable
    'dismiss_msg'  => 'I really, really need you to install these plugins, okay?', // this message will be output at top of nag
    'is_automatic' => true, // automatically activate plugins after installation
    'message'      => '<!--Hey there.-->', // message to output right before the plugins table
    'strings'      => array(); // The array of message strings that TGM Plugin Activation uses
);
 
?>

Заключение

Как вы можете видеть, предложить функциональность в темах WordPress возможно – вы просто должны думать в первую очередь о пользователях, которые могут переключиться с одной темы на другую. Библиотека TGM Plugin Activation предлагает действительно умный способ для этого.

Что вы думаете по поводу данного инструмента? Использовали ли вы его когда-либо, планируете ли вы его использовать в будущем? Делитесь своими мыслями!

Источник: code.tutsplus.com

Блог про WordPress
Комментарии: 11
  1. Дмитрий

    Отличный инструмент. Использую её в своих проектах около года для установки необходимых плагинов с wordpress.org или из темы.
    Поправьте меня если я не ошибаюсь — также есть возможность устанавливать плагин с GitHub-репозитория.

    1. Дмитрий (автор)

      Безусловно, можно.
      Для этого в параметре external_url прописывается адрес нужного репозитория.

  2. Проф-Партнер

    Если особенность связана с визуальным представлением сайта, то в таком случае она должна быть включена в тему; если же она связана с функциональностью, то тогда она должна быть представлена в виде отдельного плагина. Очень четко сказано. В свою очередь добавлю что действительно отличный инструмент, который используется мной уже продолжительное время.

  3. Михаил

    Как выбрать языковой пакет?

    1. Дмитрий (автор)

      Насколько я понимаю, это делается уже в пределах WordPress при установке темы.

  4. point111

    А как настроить язык уведомлений, ведь у планина есть кучка переводов в папке languages?

    1. Дмитрий (автор)

      Переводы автоматом подтягиваются в зависимости от языка вашей установки WordPress.

      Вот тут можете подробно посмотреть, только на примере с плагином Yoast SEO:

      https://kb.yoast.com/kb/plugin-english-site-another-language/

      1. Дмитрий (автор)

        Если уведомления на английском, то, возможно, перевод неполный и потому их пропустили. Или ваша установка на английском, а потому и все уведомления тоже на английском.

  5. point111

    Установка WordPress на русском (wordpress-5.2.2-ru_RU), и в создаваемой теме проверил, что у неё выставлен язык RU. Мозила русская. Открыл tgmpa-ru_RU.po — там нет пропусков в переводе сообщений. Поэтому и считал, что язык надо выставлять в конфиге плагина. Yoast SEO предлагает обновить переводы из админки WordPress (стандартно, как и все плаги), но TGM ставится так, что не попадает в список плагов в админке (в functions.php подключаем «require get_template_directory() . ‘/tgm/тема.php’;»). И ещё, версия 2.6.1 TGM Plugin Activation генерериуется под конкретную установку через визард на сайте скачивания, не могли бы вы помочь разобраться с этим визардом (у меня с английским ну очень туго), а то я её скачивал с GitHub и ставил «по старинке».

    1. Дмитрий (автор)

      Честно говоря, про этот конкретный плагин и его особенности установки не в курсе. Видимо да, надо детально смотреть визард и читать их доки. Так навскидку сложно сказать, почему проблемы с языком.

      Предполагаю, что они просто не все перевели. А точнее, не сделали некоторые строки переводимыми. Потому они и идут в en версии. Но это лишь догадки.

  6. Князь

    Вы так говорите, как разработчик для themeforest

Добавить комментарий для Дмитрий Отменить ответ

Получать новые комментарии по электронной почте.