Написание виджета для WordPress

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

Так выглядят виджеты, которые выводят список рубрик и облако тегов

Синтаксис
При написании виджетов в WordPress опираются на два синтаксиса. Первый актуален до версии 2.8. Второй, новый, актуален в версиях 2.8+. Про старый синтаксис написано предостаточно статей. И на русском тоже. Поэтому в этой заметке мы рассмотрим новый синтаксис написания виджетов.

Быстрый старт
Вот код простейшего виджета.
helloworld.php

<?php
/*
Plugin Name: HelloWorld
Plugin URI: http://www.web-junior.net
Description: This plugin creates a widget 
Author: web-junior
Author URI: http://www.web-junior.net/
Version: 1.0
*/
class HelloWorld extends WP_Widget{
 
	public function HelloWorld() {
		$widget_ops = array( 'classname' => 'helloworld', 
		'description' => 'Displays HelloWorld block at'.
' sidebar.' );
		$control_ops = array( 'width' => 200, 'height' => 250, 
		'id_base' => 'helloworld' );
		parent::__construct( 'helloworld', 'HelloWorld',
		$widget_ops, $control_ops );
	}
 
	public function form($instance) {?>
		<p><label for="<?php echo $this->get_field_id('hello'); 
		?>"><?php _e("Введите ваше приветствие"); ?></label>:
		<textarea id="<?php echo $this->get_field_id('hello'); 
		?>" name="<?php echo $this->get_field_name('hello'); 
		?>" cols="25" rows="5"><?php echo $instance['hello']; 
		?></textarea></p><?php 
	}
 
	public function update($new_instance, $old_instance) {
		return $new_instance;
	}
 
	public function widget($args, $instance) {
		echo $args['before_widget'],$args['before_title'] .
		'Hello World' . $args['after_title'];
		if ( $instance['hello'] ){
			echo nl2br($instance['hello']);
		}
		echo $args['after_widget'];
	}
}
 
// register HelloWorld widget
add_action('widgets_init', create_function('', 
'return register_widget("HelloWorld");'));
?>

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

Результат работы виджета HelloWorld

Теперь посмотрим на код. С начала идет комментарий.

/*
Plugin Name: HelloWorld
Plugin URI: http://www.web-junior.net
Description: This plugin creates a widget 
Author: web-junior
Author URI: http://www.web-junior.net/
Version: 1.0
*/

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

Виджет HelloWorld в списке плагинов

В новом синтаксисе, в отличие от старого, каждый виджет должен быть классом, наследующим WP_Widget. В старом достаточно было только несколько функций.
Конструктор класса пишется в стиле php4:

class HelloWorld extends WP_Widget{
 
	public function HelloWorld() {
		$widget_ops = array( 'classname' => 'helloworld', 
		'description' => 'Displays HelloWorld block'.
' at sidebar.' );
		$control_ops = array( 'width' => 200, 'height' => 250, 
		'id_base' => 'helloworld' );
		parent::__construct( 'helloworld', 'HelloWorld',
		$widget_ops, $control_ops );
	}

В нем чаще всего происходит вызов конструктора предка (WP_Widget), со следующими параметрами:

public function WP_Widget($id_base = false, 
$name, $widget_options = array(), $control_options = array())

• $id_base – уникальный идентификатор виджета, должен быть написан в нижнем регистре без пробелов в начале, середине и конце. Чаще всего – это имя класса в нижнем регистре;
• $name – имя виджета, которое будет отображаться на панели управления виджетами и сайдбарами в админке;
• $widget_options – массив с опциями, которые будут переданы в функцию wp_register_sidebar_widget()
  • description – текстовое описание, которое будет отображаться на панели управления сайдбарами под соответствующим виджетом;
  • classname – имя css-класса, который будет применен к виджету на сайдбаре;
  • также могут быть другие параметры на выбор. Все параметры будут переданы в метод widget() в массиве $args (см. далее)
• $control_options – массив с опциями, которые будут переданы в функцию wp_register_widget_control()
  • height – высота формы виджета в админке. В документации сказано, что этот параметр никогда не используется. И действительно, какую высоту не задавай, больше или меньше чем размер всех элементов формы она не становится;
  • width – ширина формы виджета. Ширина, в отличие от высоты может быть больше, чем ширина всех элементов формы виджета. Но меньше быть не может;
  • в функцию wp_register_widget_control() передается еще и параметр id_base, но он является идентичным параметра $id_base конструктора WP_Widget и класс сам заботится о его значении;

Для обеспечение нормальной функциональности виджета достаточно переопределить 3 метода из класса WP_Widget.
Для вывода формы ввода некоторых данных в админке, нужно переопределить метод form.

	public function form($instance) {?>
		<p><label for="<?php echo $this->get_field_id('hello'); 
		?>"><?php _e("Введите ваше приветствие"); ?></label>:
		<textarea id="<?php echo $this->get_field_id('hello'); 
		?>" name="<?php echo $this->get_field_name('hello'); 
		?>" cols="25" rows="5"><?php echo $instance['hello']; 
		?></textarea></p><?php 
	}

По умолчанию этот метод выводит текст «There are no options for this widget.» (на соответствующем языке). HTML-код формы, который выводится в этом методе не должен содержать тега <form>. WordPress об этом позаботится сам.
Каждый элемент формы должен иметь имя и идентификатор (поскольку WordPress сверстан на XHTML). Имя и идентификатор генерируются с помощью методов get_field_name() и get_field_id() соответственно. Для того, чтобы сгенерировать идентификатор или имя для поля, нужно вызвать соответствующий метод и передать ему желаемое уникальное имя. Метод вернет текст идентификатора или имени.
Параметр $instance является массивом с данными формы, которые были сохранены ранее. В результате реализации этого кода получается такая форма.

Форма администрирования виджета

Для вывода виджета в сайдбаре на страничках блога предназначен метод widget.

	public function widget($args, $instance) {
		echo $args['before_widget'],$args['before_title'] .
		'Hello World' . $args['after_title'];
		if ( $instance['hello'] ){
			echo nl2br($instance['hello']);
		}
		echo $args['after_widget'];
	}

Этот метод обязательно должен быть переопределен. В качестве параметров в этот метод передаются аргументы виджета $args, а также данные, которые были сохранены из формы в админке $instance.
Массив $args содержит некоторые перменные, такие как before_widget, after_widget, before_title, after_title и др. В переменных before_widget и after_widget содержится html-код, который пишется в теме перед и после виджета соответственно. В переменных before_title и after_title содержится html-код, который должен быть расположен перед и после названия виджета соответственно.
Для проверок на корректность введенных в форму данных, используется метод update.

	public function update($new_instance, $old_instance) {
		return $new_instance;
	}

В метод передаются два массива. В $new_instance находятся данные из формы в админке, которые только что сохранил админ. В $old_instance находятся данные той-же формы, но сохраненные ранее. После завершения всех проверок, метод должен вернуть массив с данными для сохранения. Или вернуть false для отмены сохранения.
Последние две строчки кода

// register HelloWorld widget
add_action('widgets_init', create_function('', 
'return register_widget("HelloWorld");'));

регистрируют новый виджет HelloWorld.

Популярность: 10%

Интересное из других блогов: