БлогNot. Пишем плагин для WordPress

Пишем плагин для WordPress

В прошлой статье мы просто установили WordPress на локальный компьютер, теперь напишем для него плагин. Зная основы PHP и MySQL, сделать это не так сложно, просто надо соблюдать формат php-файла, который поймёт наш движок. Попробуем обойтись без чтения толстых мануалов, чтобы сделать плагин быстро и интуитивно понятно.

Конечно, сначала нужна идея для плагина, способная сделать его востребованным. Пусть это будет вывод неких "событий дня", скажем, праздников, святцев, примет и именинников, просто я уже писал такой мидлет для телефона и от него вот тут остались данные. Скачав архив, я развернул его без создания новой папки, а ту папку, что была в архиве, переименовал в data и положил в папку, в которой будут размещать все остальные файлы плагина. Потом не забыл двумя кликами мыши в Far'e перекодировать все файлы папки в Юникод из кодировки Windows. Файл с кодом плагина EverydayNotes_Widget.php и файл описания readme.txt нужно тоже создать в Юникоде и в той же папке, выйдет вот что:

файлы и папка с данными плагина, в папке 366 файлов по числу дней года
файлы и папка с данными плагина, в папке 366 файлов по числу дней года

Кстати, ничто не мешает плагину добавить в базу данных wordpress новую таблицу или пользоваться данными существующих таблиц, я не буду этого делать для простоты.

Сначала избавимся от скучных общих требований, сделав описание readme.txt и заголовок плагина в EverydayNotes_Widget.php. Вот полный текст моего readme.txt, я включил в него все секции, которые обычно требуются, составил файл по-английски, но заполнил только минимально необходимые данные:

=== EverydayNotes ===
Contributors: PerS
Donate link: http://nickolay.info/

Requires at least: 3.0.1
Tested up to: 3.8
Stable tag: 1.0.1
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

This plugin lets you add a EverydayNotes widget to your WordPress page.

== Description ==

= Features =

== Installation ==
1. Upload `EverydayNotes_Widget.php` to the `/wp-content/plugins/` directory.
2. Activate the plugin through the `Plugins` menu in WordPress.
3. Go to `Appearance`,  `Widgets` in WordPress.
4. Drag the `EverydayNotes` to the sidebar, for example the `Main Widget Area` or the `Secondary Widget Area`.

== Frequently Asked Questions ==

== Screenshots ==

== Changelog ==

== Upgrade Notice ==

Лицензию и требуемую версию движка я написал "от фонаря", но в сложных виджетах это может быть критично.

Прежде, чем браться за код самого виджета, уясним пару теоретических моментов. Механизм работы плагинов базируется на перехвате и дальнейшей обработке пользовательскими функциями событий движка, называемых на сленге разработчиков этой CMS "хуками" (hook). Для написания плагина нужно просто перехватить соответствующее событие, обработать его и вернуть результат обработки движку.

Для перехвата событий есть два основных метода:

  • add_action позволяет переопределить некую базовую функцию WordPress на пользовательскую;
  • add_filter сработает при вызове существующей базовой функции, вызвав для выполнения пользовательскую функцию.

Соответственно, есть обратные действия — remove_action и remove_filter.

В нашем плагине мы собираемся просто выводить некие данные, которые виджет будет брать из файла с именем, полученным из номеров текущего дня и месяца. Вывод виджета ни от каких внешних событий зависеть не будет, так что нам достаточно применить метод движка add_action для хука widgets_init. Вот если бы мы, к примеру, что-то делали с данными, поступающими для публикации, то помог бы add_filter.

Наш файл EverydayNotes_Widget.php сделаем пока таким:

<?php
/*
Plugin Name: EverydayNotes
Version: 1.0
Author: PerS
Author URI: http://nickolay.info/
*/

class EverydayNotes_Widget extends WP_Widget {
 //!!!
}

function register_EverydayNotes_Widget() {
 register_widget('EverydayNotes_Widget');
}
add_action('widgets_init', 'register_EverydayNotes_Widget');
?>

Здесь уже есть регистрация плагина и пустой класс для него - потомок имеющегося в WordPress класса WP_Widget. Многострочный комментарий с описанием имени, версии и автора (единственное обязательное поле - имя) должен находиться именно на этом месте, сразу после открывающего тега.

Если хотите узнать обо всех хуках Вордпресса - вот линк на базу.

Всё остальное мы будем писать внутри класса вместо //!!!

Нашему классу понадобится конструктор. В несложных случаях достаточно вызвать конструктор родителя, то есть, класса WP_Widget:

function __construct() {
 parent::__construct(false, $name = __('EverydayNotes','EverydayNotes_Widget'));
}

"Загадочный" метод с именем __ (два подчёркивания) здесь и далее переводит свой аргумент, используя текущую локаль. Оберните строки, которые собираетесь использовать в коде, в эту функцию. Вторая функция, полезная для будущих переводов плагина на другие языки - _e, в неё нужно оборачивать функции, которые мы собираемся показывать пользователю.

Второй аргумент функций - имя для пространства перевода вашего плагина. Обычно оно такое же, как имя главного файла вашего плагина (только без .php). Имя должно быть уникальным.

Метод form будет отвечать за форму, выводимую пользователю при установке плагина. "Зашьём" туда возможность изменить заголовок плагина - хуже нет, когда такая возможность недоступна! Нам помогут встроенные в WP_Widget методы get_field_id и get_field_name. Вот функция, которая поможет вам и в других аналогичных виджетах:

public function form ($instance) {
 if (isset($instance['title'])) $title = $instance['title'];
 else $title = 'Заметки дня';
 echo '<p><label for="'.$this->get_field_id('title').'">'._e('Заголовок:','EverydayNotes_Widget').
  '<input class="widefat" id="'.$this->get_field_id('title').'" name="'.$this->get_field_name('title').
  '" type="text" value="'.$title.'" /></label></p>';
}

Имя аргумента $instance не случайно - так обозначается переменная, в которой содержится сущность класса. Объект класса может быть создан только единожды и размещается в этой переменной.

Для сохранения модифицированного пользователем заголовка нам понадобится метод update:

public function update ($new_instance, $old_instance) {
 $instance = array();
 $instance['title'] = (!empty($new_instance['title']))?trim(strip_tags($new_instance['title'])):'';
 return $instance;
}

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

public function widget ($args, $instance) {
 $title = $instance['title']; 
 if ($title=='') $title = 'Заметки дня';
 $title = apply_filters ('widget_title', $instance['title']);
 echo $args['before_widget'];
 if ($title) echo $args['before_title'] . $title. $args['after_title'];
 //основной код
 $file = dirname(__FILE__).'/data/'.date("md").'.txt'; //Получить имя "сегодняшнего" файла ММДД.txt из папки данных
 $content=@file_get_contents($file); //прочитать файл в строку
 echo "".nl2br($content); //заменить разрывы строк на <br> и отдать юзеру
 //
 echo $args['after_widget'];		
}

Теперь просто сделаем из папки EverydayNotes архив .zip вместе с папкой - и виджет готов! Установить его в WordPress можно так:

  • В админке щёлкаем Плагины - Добавить новый;
  • Выбираем ссылку "Загрузить" и наш архив, жмём "Установить". Если всё правильно, плагин загрузился и можно нажать ссылку "Активировать". Если есть ошибки, Wordpress о них сообщит.

Добавим наш плагин на страницу сайта. Для этого щёлкаем Внешний вид - Виджеты и перетаскиваем значок виджета в нужную область сайта из нашего шаблона, например, "Область подвала 1". По перетаскивании он даст возможность изменить заголовок:

Виджет добавлен на сайт
Виджет добавлен на сайт

Жмём "Сохранить", переходим на сайт и смотрим, что вышло:

Виджет в работе, данные за 9 марта
Виджет в работе, данные за 9 марта

Отключение плагина сделать не сложнее - нажать "Удалить" в области сайта, куда добавляли, перейти на страницу админки Плагины - Установленные, нажать Деактивировать и затем Удалить.

 Скачать плагин EverydayNotes для WordPress в архиве .zip (250 Кб)

Обратите внимание, что при установке внешних плагинов WordPress показывает на странице "Установка плагина", откуда он взял архив .zip с кодом. Этот архив всегда можно скачать, развернуть и изучить содержимое файлов. Ну или просто установить нужный плагин и взять содержимое из папки wordpress\wp-content\plugins\имя_плагина\

Ну а для более подробного изучения можно порекомендовать вот эту статью.

Как добавить свой плагин в репозиторий WordPress?

...если хочется ещё и прославиться :) Что ж, это тоже не так сложно.

Регистрируемся на WordPress.org в разделе плагинов. При помощи меню переходим в Developer Center, выбираем Add Your Plugin.

Создаём для плагина файл readme.txt согласно приведённому стандарту. После написания readme.txt проверяем его анализатором-валидатором, который может указать на присутствующие ошибки или одобрить файл.

После одобрения файла валидатором, можно продолжить добавление плагина, заполнив на английском языке форму, предлагаемую в пункте Add Your Plugin. После отправки формы ждём одобрения плагина на указанный при регистрации E-mail.

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

Дальше нужно совершить несколько стандартных действий:

  • Создать локальную папку, в которой будут храниться файлы написанного wordpress-плагина, например, ~/myplugin-dir;
  • Выполнить процедуру SVN Check out (http://svn.wp-plugins.org/myplugin-name - ссылка на репозиторий из письма):
    $ svn co http://svn.wp-plugins.org/myplugin-name ~/myplugin-dir
    > A myplugin-dir/trunk
    > A myplugin-dir/branches
    > A myplugin-dir/tags
    > Checked out revision XXXXX.
  • Скопировать все файлы плагина в директорию ~/myplugin-dir/trunk/ и загрузить их в репозиторий:
    $ svn add ~/myplugin-dir/trunk/*
    > A trunk/example_plugin.php
    > A trunk/readme.txt
  • Перейдя в директорию ~/myplugin-dir, создать релиз текущей версии плагина, сообщив о сделанных изменениях (выполнить commit):
    ~/myplugin-dir$ svn ci -m 'added version 1.0 of my plug-in'
    > Adding trunk/my-plugin.php
    > Adding trunk/readme.txt
    > Transmitting file data .
    > Committed revision XXXXX.

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

Русифицированный плагин можно попробовать добавить и на mywordpress.ru.

SVN-клиентом для Windows может работать TortoiseSVN.

09.03.2015, 17:20 [12359 просмотров]


теги: программирование php дата сервис cms

К этой статье пока нет комментариев, Ваш будет первым