Создание плагина с помощью генератора шаблонов WordPress Plugin Boilerplate

Создание плагина с помощью генератора шаблонов WordPress Plugin Boilerplate значительно экономит время и силы разработчика и в то же время, получаемый код соответствует принципам объектно-ориентированного программирования. В этой статье я подробно опишу, как быстро начать разработку плагинов Wordpress. Для создания плагина в любой cms необходимо следовать набору правил, рекомендуемых разработчиками этой платформы. Плагины по функциональности могут отличаться друг от друга и иногда достаточно одного файла, чтобы расширить возможности cms.

Небольшому плагину нет смысла создавать сложную структуру, его легко поддерживать и несложно написать следуя инструкциям wordpress codex. Но, если в дальнейшем планируется расширение функционала или необходимо создание более сложной структуры  - рекомендуется  организовывать структуру плагина согласно "Best Practices". Я так и делал, пока не нашёл более удобный способ для создания нового плагина - это использование генератора шаблонов плагина - WordPress Plugin Boilerplate.

Генератор создаёт чистый шаблон на основе принципов объектно-ориентированного программирования, и включает в себя все необходимые элементы  для  создания административной части и локализации.

В этой статье я расскажу как создать чистый шаблон в WordPress Plugin Boilerplate и покажу начальные шаги разработки. Этого материала будет достаточно тем, кто уже имеет опыт разработки плагинов, а для новичков в следующих статьях будут описаны конкретные примеры создания плагина.

Итак приступим.

 

1. Создание шаблона

Для того, чтобы создать шаблон перейдите к генератору WordPress Plugin Boilerplate,  заполните форму и нажмите кнопку « Build Plugin» .

WordPress Plugin Boilerplate

Cгенерированный шаблон плагина автоматически будет скачан в виде *.zip файла. После чего его нужно распаковать и добавить в папку plugins вашего текущего проекта. Осталось только найти его в списке плагинов и включить как на рисунке ниже. Всё, плагин полностью готов для дальнейшей с ним работой. Далее рассмотрим структуру плагина более подробно.

список плагинов

 

2. Обзор структуры папок плагина

Теперь, когда плагин установлен, рассмотрим структуру папок. Все файлы включают в своё название краткое наименование плагина (слаг). Ниже показана структура шаблона.


 /my-plugin-name
    /admin
        class-wp-clear-admin.php
        index.php
    /css
        wp-clear-admin.css
    /js
        wp-clear-admin.js
    /includes
        class-wp-clear.php
        class-wp-clear-activator.php
        class-wp-clear-deactivator.php
        class-wp-clear-i18n.php
        class-wp-clear-loader.php
        index.php
    /languages    
        my-plugin.pot
    /public
        /css
            my-plugin-public.css    
        /js
            my-plugin-public.js
        /partials
            my-plugin-public-display.php
        class-my-plugin-public.php    
        index.php        
    index.php
    LICENSE.txt
    my-plugin.php
    README.txt
    uninstall.php

Шаблон делиться на четыре основные папки: admin, includeslanguages и public и другие сопутствующие файлы. Наиболее важные файлы я рассмотрю более подробно:

Папка 'admin'

В папке admin располагается весь код административной части, включая папки CSS, JS и других компонентов. 

css/my-plugin-admin.css - Файл для стилей страницы настроек плагина.

js/my-plugin-admin.js - Файл для js страницы настроек плагина.

class-my-plugin-admin.php - Этот файл содержит класс для создания административной части.

my-plugin-admin-display.php - Файл содержит HTML код страницы настроек плагина.

 

Папка 'includes'

В этой папке находятся:

class-my-plugin.php - Основной файл с классом для работы плагина, куда добавляются все действия и фильтры.

class-my-plugin-activator.php - Файл содержит класс, необходимый для запуска во время активации плагина.

class-my-plugin-desactivator.php - Файл содержит класс для деактивации плагина.

class-my-plugin-i18n.php - Файл интернационализации.

class-my-plugin-loader.php - Файл загрузчика, который регистрирует все события, фильтры и хуки.

 

Папка 'languages'

После генерации шаблона он содержит только один файл.

my-plugin.pot - Файл локализации по умолчанию пуст. Ниже будет описан способ локализации плагина более подробно.

 

Папка 'public'

css/my-plugin-admin.css - Файл для стилей публичной части страницы плагина.

js/my-plugin-admin.js - Файл для js публичной части страницы настроек плагина.

/partials/my-plugin-public-display.php - Файл содержит HTML код страницы если плагин внедряет в шаблон сайта какие либо данные.

class-my-plugin-public.php - Файл содержит класс для публичной части плагина. В методах класса добавляются события и фильтры, необходимые для реализации функциональности плагина.

 

Дополнительные файлы

Список и краткое описание файлов расположенных в корневой папке плагина:

LICENCE.txt - Файл лицензии GPL-2.

README.txt - Файл описания плагина и его установки.

uninstall.php - Файл удаления плагина из WordPress.

wp-cbf.php - Файл начальной загрузки плагина. Тут расположена информация о плагине. Версия, автор и другие данные

 

3. Создание страницы настроек плагина (админка)

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

1. Регистрация и создание страницы настроек плагина 

Для начала нужно зарегистрировать плагин в cms и добавить страницу настроек. Для этого в файле admin/class-my-plugin-admin.php нужно добавить несколько методов

add_plugin_admin_menu() - Добавляет и регистрирует страницу настроек плагина.

add_action_links() - Добавляет ссылку на плагин в консоль

display_plugin_setup_page() - Добавляет путь к шаблону с html кодом формы админки


    /**
     * Register the administration menu for this plugin into the WordPress Dashboard menu.
     */

    public function add_plugin_admin_menu() {

     /*
      * Add a settings page for this plugin to the Settings menu.
     */
        add_options_page( 'My plugin and Base Options Functions Setup', 'My plugin', 'manage_options', $this->plugin_name, array($this, 'display_plugin_setup_page')
        );
    }

     /**
     * Add settings action link to the plugins page.
     */

    public function add_action_links( $links ) {
        
       $settings_link = array(
        '<a href="' . admin_url( 'options-general.php?page=' . $this->plugin_name ) . '">' . __('Settings', $this->plugin_name) . '</a>',
       );
       return array_merge(  $settings_link, $links );

    }

    /**
     * Render the settings page for this plugin.
     */

    public function display_plugin_setup_page() {
        
        include_once( 'partials/my-plugin-admin-display.php' );
        
    } 

Осталось зарегистрировать действия (actions) и фильтр (add_filter()) для того, что бы появилась ссылка в меню. Для этого нужно открыть файл includes/class-my-plugin.php и в функцию define_admin_hooks() добавить:


   // Add menu item
   $this->loader->add_action( 'admin_menu', $plugin_admin, 'add_plugin_admin_menu' );

   // Add Settings link to the plugin
   $plugin_basename = plugin_basename( plugin_dir_path( __DIR__ ) . $this->plugin_name . '.php' );
   $this->loader->add_filter( 'plugin_action_links_' . $plugin_basename, $plugin_admin, 'add_action_links' );

Теперь если перейти в меню наcтроек появится новое меню "My plugin" смотри на рисунке ниже.

меню настроек

2. Добавление полей на страницу настроек

В рамках этой статьи я добавлю в виде примера текстовое поле, которое будет выводить в футере введённый в странице настроек текст. Приведу пример валидации и сохранения изменений его состояния.

По сути страница настроек плагина - это простая форма, и тут можно использовать любые элементы форм. Например, текстовые поля позволят выводить телефоны или подписи пользователей. Чекбосксы, списки и кнопки, все может пойти в ход. Принцип обработки данных схож и не вызовет затруднений. Для того, что бы вы могли правильно оформить html код поля следует установить плагин WordPress Admin Style,  он демонстрирует примеры как правильно оформить любой тип элемента формы, с учётом дальнейшей локализации. Дальше я опишу  как с этим работать. 

Html код формы страницы настроек расположен в файле admin/partials/my-plugin-admin-display.php. Изначально страница совершенно пуста . Нужно добавить форму:


  <form method="post" name="my_options" action="options.php">
 
        <?php

        // Загрузить все значения элементов формы
        $options = get_option($this->plugin_name);

        // текущие состояние опций
        $footer_text = $options['footer_text'];

        // Выводит скрытые поля формы на странице настроек
        settings_fields( $this->plugin_name );
        do_settings_sections( $this->plugin_name );
        
        ?>

    <h2><?php echo esc_html( get_admin_page_title() ); ?></h2>

        <fieldset>
            <legend class="screen-reader-text"><span><?php _e('Text in the footer', $this->plugin_name);?></span></legend>
            <label for="<?php echo $this->plugin_name;?>-footer_text">
                <span><?php esc_attr_e('Text in the footer', $this->plugin_name);?></span>
            </label>
            <input type="text"
                   class="regular-text" id="<?php echo $this->plugin_name;?>-footer_text"
                   name="<?php echo $this->plugin_name;?>[footer_text]"
                   value="<?php if(!empty($footer_text)) esc_attr_e($footer_text, $this->plugin_name);?>"
                   placeholder="<?php esc_attr_e('Text in the footer', $this->plugin_name);?>"
            />
        </fieldset>

        <?php submit_button(__('Save all changes', $this->plugin_name), 'primary','submit', TRUE); ?>

  </form>

В итоге получим скромную страницу настроек. Я несколько сократил код, оставил лишь необходимый минимум для дальнейшей работы. На изображении ниже  видно текстовое поле с меткой и placeholder-ом. Все тексты помещены  в  функцию esc_attr_e() - это позволит в дальнейшем добавить  переводы на другие языки.

Страница настроек

3. Валидация  данных элементов формы

Для валидации формы нужно добавить метод validate в класс My_Plugin_Admin, он расположен в файле admin/class-my-plugin-admin.php.


   /**
   * Validate options
   */
   public function validate($input) {
     $valid = array();
     $valid['footer_text'] = (isset($input['footer_text']) && !empty($input['footer_text'])) ? $input['footer_text'] : '';
     return $valid;
   }

В примере функция validate() получает текущие состояния inputa с именем footer_text и с помощью тернарного оператора проверяет пуст он или нет. Таким образом можно проверить и провести санацию полученных данных из формы, после чего вернуть текущие состояния элементов формы в виде массива. 

После проверки данных нужно обновить данные на странице настроек. Для этого под функцией validate добавим ещё одну update.


    /**
     * Update all options
     */
    public function options_update() {
        register_setting($this->plugin_name, $this->plugin_name, array($this, 'validate'));
    }

Остался последний шаг - это регистрация события обновления. Нужно в файле includes/class-my-plugin.php в функцию define_admin_hooks() добавить такие строки:


   // Save/Update our plugin options
   $this->loader->add_action('admin_init', $plugin_admin, 'options_update');

Итак, что у нас получилось. Был сгенерирован шаблон, на его основе создана страница настроек. Данные с этой страницы успешно сохраняются. Осталось  реализовать в публичной части плагина работу с введёнными данными. В рамках этой статьи в футере активной темы будет выведен текст со страницы настроек.

4. Публичная часть плагина

Осталось обеспечить взаимодействие нашего плагина с сайтом WordPress. Для начала нужно получить данные со страницы настроек и вывести их используя события и хуки. Для получения данных нужно в конструкторы классов My_Plugin_Admin и My_Plugin_Public добавить следующую строку:


  $this->my_plugin_options = get_option($this->plugin_name);

Это позволит получить значение любого параметра плагина указав ключ/имя. Пример получения значения нашего текстового поля:


  $this->my_plugin_options['footer_text']

Воспользоваться и вывести значение в футере поможет небольшая функция, которую нужно добавить в виде публичного метода класса My_Plugin_Public который находится в файле public/class-my-plugin-public.php


  /**
  * The function of adding text to the footer
  */

  public function add_text_footer(){

   if( !empty($this->my_plugin_options['footer_text']) )
     {
        echo '<h3 class="center">'.$this->my_plugin_options['footer_text'].'</h3>';
     }
  }

Что бы всё заработало осталось зарегистрировать событие в файле includes/class-my-plugin.php. Добавив строку  в функцию define_public_hooks() :


 $this->loader->add_action( 'wp_footer', $plugin_public, 'add_text_footer' );

Всё. Небольшой плагин готов и его можно протестировать. Включить/выключить в списке плагинов. На странице настроек сменить текст.

Перейдём к последнему этапу - локализации плагина.

5. Локализация плагина

Все поля которые мы задействовали, использовали конструкцию:


 <?php esc_attr_e( $text, $this->plugin_name) ?>

Это позволяет "зацепить" любую строку для перевода и сделать плагин дружественным на любом языке. В плагине присутствует папка languages она содержит единственный пустой файл my-plugin.pot.  Автоматизировать и сделать процесс перевода простым и удобным, нам поможет проект poedit. Это редактор переводов прекрасно подойдёт для перевода тем и плагинов. Эту программу нужно скачать и установить.

Пользоваться ею очень легко. После запуска программы  нужно выбрать в меню  вариант  "Перевод модуля или темы Worrdpress". Откроется диалоговое окно как на рисунке ниже слева. В место где указывает стрелочка переместить плагин или тему. Программа сама сканирует наличие переводимых полей. После чего всё сохраняем в файл my-plugin.pot заменяя старый.

создание файла переводовсоздание файла переводов

 

Теперь осталось только добавить перевод для русского языка и перевести все поля. Создание перевода показано на рисунке сверху справа. После сохранения будет доступна локализация на вашем языке. 

Небольшое замечание. Иногда программа создаёт файл в формате ru-RU.mo и плагин не хочет видеть перевод. Я нашёл решение - нужно перед  названием перевода ставить слаг модуля, то есть  my-plugin-ru_RU.mo и всё заработает нормально. Надеюсь в следующей версии poedit это учтут.

 

 

Заключение

Вот и все. Мы создали плагин WordPress с нуля благодаря генератору шаблонов WordPress Plugin Boilerplate. Я постарался написать небольшую инструкцию как разработать плагин на принципах ООП. Используя многочисленные хуки, события и фильтры CMS Wordpress возможно создание плагина любой сложности.

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

Андрей 01 октября, 2019

Здравствуйте, спасибо за ваш труд.
Жаль не удается найти дату публикации статьи. Я как-то привык на это смотреть в первую очередь. Думаю статья опубликована не ранее 2014 года. И кажется, по сей день она актуальна.

Андрей 02 октября, 2019

Пардон, уже обнаружил дату:
07 февраля, 2019

Оставить комментарий

Похожие материалы