Создание плагина с помощью генератора WordPress Plugin Boilerplate
Создание плагина — дело не такое простое, как расписывают многие авторы в своих блогах. Они в основном рассматривают простые варианты. Я перелопатил много материалов по этой теме, и нашел отличную статью Алексея Ртищева о том, как научится грамотно создавать плагины, учитывая правила и кодекс WordPress. Привожу ее целиком для своих читателей, которые заинтересуются созданием плагинов.
Создание плагина с помощью генератора шаблонов WordPress Plugin Boilerplate значительно экономит время и силы разработчика и в то же время, получаемый код соответствует принципам объектно-ориентированного программирования. В этой статье я подробно опишу, как быстро начать разработку плагинов Wordpress. Для создания плагина в любой cms необходимо следовать набору правил, рекомендуемых разработчиками этой платформы. Плагины по функциональности могут отличаться друг от друга и иногда достаточно одного файла, чтобы расширить возможности cms.
Небольшому плагину нет смысла создавать сложную структуру, его легко поддерживать и несложно написать следуя инструкциям wordpress codex. Но, если в дальнейшем планируется расширение функционала или необходимо создание более сложной структуры — рекомендуется организовывать структуру плагина согласно Best Practices. Я так и делал, пока не нашёл более удобный способ для создания нового плагина — это использование генератора шаблонов плагина — WordPress Plugin Boilerplate.
Генератор создаёт чистый шаблон на основе принципов объектно-ориентированного программирования, и включает в себя все необходимые элементы для создания административной части и локализации.
В этой статье я расскажу как создать чистый шаблон в WordPress Plugin Boilerplate и покажу начальные шаги разработки. Этого материала будет достаточно тем, кто уже имеет опыт разработки плагинов, а для новичков в следующих статьях будут описаны конкретные примеры создания плагина.
Итак приступим.
Содержание статьи
1. Создание шаблона
Для того, чтобы создать шаблон перейдите к генератору WordPress Plugin Boilerplate, заполните форму и нажмите кнопку « Build Plugin» .
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, includes, languages и 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-public.css — Файл для стилей публичной части страницы плагина.
js/my-plugin-public.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 скачать и посмотреть его можно тут.
Автор: Алексей Ртищев Источник: delay-delo.com
Всего комментариев: 0