Создание виджетов для WordPress

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

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

Главный файл плагина

WordPress автоматически распознает плагины расположенные в папке wp-content/plugins. Для создания нового плагина, нужно создать новую папку в этой директории. Имя этой подпапки может быть каким угодно, но лучше назвать папку именем вашего плагина. Старайтесь избегать распространенных слов, например: «textwidget» или «shoppingcart», т.к. эти имена уже могут быть заняты и могут вызвать проблемы, если вы соберетесь выложить ваш плагин в общий доступ (подробнее об именовании в статье Создание плагина для WordPress). Для нашего примера создадим папку php_examplewidget.

WordPress распознает доступный плагин по комментарию, расположенному в главном PHP файле плагина. Этот комментарий должен содержать основную информацию о вашем плагине: назначение плагина, имя автора, информацию о лицензии и т.п. Эта информация помогает системе идентифицировать плагин. Создадим в папке php_examplewidget файл widget_init.php со следующим содержанием:

<?php
/*
Plugin Name: Simple TextWidget Plugin
Plugin URI: http://www.example.com/textwidget
Description: An example plugin to demonstrate widgets API in WordPress
Version: 0.1
Author: Author Name
Author URI: http://www.example.com
License: GPL2 

    Copyright 2011 Author Name

    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License,
    version 2, as published by the Free Software Foundation. 

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.
*/

Это обязательный минимум для любого WordPress плагина. Теперь зайдите на страницу ваших плагинов в WordPress и вы увидите, что ваш плагин распознан и готов к активации:

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

Файл, который мы только что создали — стартовая точка вашего плагина. Код расположенный после комментария будет автоматически выполняться.

Виджеты в WordPress

В WordPress есть класс WP_Widget, который предоставляет доступ к API виджетов. Когда вы наследуете этот класс, ваш виджет будет доступен для любого сайдбара, который поддерживает ваша тема. В комплекте WordPress уже есть некоторые виджеты, например «Свежие записи» или «Архив», они тоже наследуют класс WP_Widget.

Класс WP_Widget содержит четыре метода, которые должны быть перегружены:

• __construct() — вызывает родительский конструктор и инициализирует виджет.
• form() — выводит форму для настройки виджета.
• update() — обновление настроек виджета, которые были указаны в форме аминистратором.
• widget() — отображение плагина на сайте.

Конструктор

Конструктор ничем не отличается от тех, что вы обычно пишете. Главное, что нужно сделать — это вызвать родительский конструктор, который принимает три аргумента: идентификатор виджета, название виджета (это имя будет показано на странице виджетов) и массив с другими деталями виджета (нужно только «description»):

<?php
class TextWidget extends WP_Widget
{
    public function __construct() {
        parent::__construct("text_widget", "Simple Text Widget",
            array("description" => "A simple widget to show how WP Plugins work"));
    }
}

Теперь нужно зарегистрировать виджет. Для этого используется функция register_widget(), которая в качестве аргумента принимает имя класса вашего виджета. Эта функция должна быть вызвана в определенное время, поэтому нам нужно использовать систему хуков в WordPress. Нужный нам хук называется «widgets_init». Для связи регистрации виджета с хуком будем использовать функцию add_action(), у которой два аргумента: первый — имя хука, второй — имя функции, которую надо выполнить (вторым аргументом может быть строка или замыкание). Этот код должен быть расположен после комментария в файле widget_init.php:

add_action("widgets_init", function () {
    register_widget("TextWidget");
});

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

Метод form()

Виджет, который мы делаем должен давать возможность вводить заголовок и немного текста для отображения на страницах сайта. Исходя из этого нам надо создать форму для ввода этих значений. Метод form() используется для отображения настроек виджета на странице виджетов. У метода один аргумент — $instance — массив переменных, связанных с виджетом. Когда форма отправится на сервер, будет вызван метод update() и мы сможем обновить переменные в массиве $instance. После, метод widget() будет использовать этот массив для отображения виджета.

public function form($instance) {
    $title = "";
    $text = "";
    // если instance не пустой, достанем значения
    if (!empty($instance)) {
        $title = $instance["title"];
        $text = $instance["text"];
    }

    $tableId = $this->get_field_id("title");
    $tableName = $this->get_field_name("title");
    echo '<label for="' . $tableId . '">Title</label><br>';
    echo '<input id="' . $tableId . '" type="text" name="' .
    $tableName . '" value="' . $title . '"><br>';

    $textId = $this->get_field_id("text");
    $textName = $this->get_field_name("text");
    echo '<label for="' . $textId . '">Text</label><br>';
    echo '<textarea id="' . $textId . '" name="' . $textName .
    '">' . $text . '</textarea>';
}

Методы get_field_id() и get_field_name() класса WP_Widget используются для генерации уникальных имен и идентификаторов для полей вашего плагина. Использование этих методов позволяет избежать конфликтов.

Внешний вид формы виджета на странице виджетов:

Родительский элемент <form>, кнопки «удалить», «закрыть» и «Сохранить» WrodPress генерирует автоматически, что сильно упрощает нам жизнь. Эта форма отправит введенные значения на сервер и вызовет метод update(), что бы мы смогли сохранить их.

Метод update()

Этот метод дает вам возможность проверить и обработать переданные значения перед использованием. Также у нас есть возможность принимать решения исходя из старых значений. Метод update() должен возвращать массив, содержащий переменные, которые вы собираетесь использовать для отображения виджета на сайте. WordPress передает два аргумента: массив новых значений и массив оригинальных значений.

public function update($newInstance, $oldInstance) {
    $values = array();
    $values["title"] = htmlentities($newInstance["title"]);
    $values["text"] = htmlentities($newInstance["text"]);
    return $values;
}

WordPress сохранит эти значения самостоятельно, об этом можно не беспокоиться.

Метод widget()

Этот метод используется для отображения виджета непосредственно в сайдбаре на сайте. У метода два аргумента: $args — аргументы виджета (массив, содержащий некоторую информацию о виджете), $instance — массив со связанными с виджетом переменными. В нашем случае $args не имеет значения.

public function widget($args, $instance) {
    $title = $instance["title"];
    $text = $instance["text"];

    echo "<h2>$title</h2>";
    echo "<p>$text</p>";
}

В итоге мы получим окончательный вид виджета:

Готово! Этот очень простой плагин позволяет отображать простой текст на вашем сайте с помощью виджетов.