Создание собственных виджетов с использованием различных API WordPress: Вступление

Виджеты - это аккуратный способ дать владельцам сайтов некоторый контроль над внешним видом (а иногда и функциональностью) своих сайтов WordPress. В этой серии мы собираемся создать несколько виджетов WordPress, объединив Widgets API с другими внешними API.

Серия будет состоять из следующих руководств:

1. Вступление
2. Похожие сообщения Widget
3. Вход Widget
4. FAQ Widget
5. Самые популярные сообщения Widget с интеграцией Google Analytics
6. Физический адрес Widget с интеграцией с Google Maps
7. Вывод

В этом уроке я познакомлю вас с API-интерфейсом WordPressWidgets (re), создав простой текстовый виджет. Мы проанализируем и рассмотрим различные функции, виджет составляющие, чтобы понять, как виджеты WordPress работают в целом.

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

Виджеты WordPress

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

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

Изучение класса виджета

Самый простой способ создать виджет WordPress - наследовать класс WP_Widget. Таким образом вы можете использовать встроенные функции для обновления виджета, отображения виджета и создания интерфейса администратора для виджета.

Чтобы полностью понять, как работают виджеты, мы создадим и рассмотрим пустой виджет. Затем мы определим каждую функцию, составляющую виджет, чтобы посмотреть, как они работают вместе, чтобы создать рабочий виджет.

Определение нашего виджета

1

<?php

2

class TutsPlusText_Widget extends WP_Widget {

3

4

  // widget constructor

5

  public function __construct(){

6

7

  }

8

9

  public function widget( $args, $instance ) {

10

    // outputs the content of the widget

11

  }

12

13

  public function form( $instance ) {

14

    // creates the back-end form

15

  }

16

17

  // Updating widget replacing old instances with new

18

  public function update( $new_instance, $old_instance ) {

19

    // processes widget options on save

20

  }

21

22

}

Подробные функции

Давайте рассмотрим каждую функцию более подробно

__construct()

Эта функция регистрирует виджет с помощью WordPress

widget()

Эта функция отвечает за внешний вид виджета. Он выводит содержимое виджета

update()

Обработка параметров виджетов при сохранении. Используйте эту функцию для обновления виджета (опция). Эта функция принимает два параметра:

1. $new_instance - значения, отправленные только для сохранения. Эти значения будут поступать из формы, определенной в методе form ()
2. $old_instance - ранее сохраненные значения из базы данных

Не забудьте очистить все представленные пользователем значения. Пользовательские значения всегда должны быть дезинфицированы перед отправкой в ​​базу данных

form()

Метод / функция form () используется для определения формы виджетов внешнего вида, которую вы видите на панели виджетов в информационной панели. Эта форма позволяет пользователю настроить заголовок и другие параметры виджета.

Эта функция принимает следующие параметры:

• $instance - ранее сохраненные значения из базы данных

Создание нашего виджета

Чтобы создать наш виджет, мы выполним следующие шаги:

• Определите, что мы создаем
• Зарегистрируйте наш виджет в WordPress
• Создание внутренней формы
• Сохранение значений в базе данных
• Определение интерфейсного дисплея
• Зарегистрировать виджет

Что мы создаем?

Как мы упоминали ранее, мы создаем простой текстовый виджет, который позволяет пользователю вводить заголовок и некоторый произвольный текст, который затем будет выводиться в интерфейсе ихнего веб-сайта, где размещается виджет.

Конструктор виджета

Конструктор позволяет нам инициализировать наш виджет, перезаписав исходный класс (стандартный класс WP_Widget).

1

<?php

2

3

public function __construct(){

4

5

  parent::__construct(

6

    	'tutsplustext_widget',

7

		__( 'TutsPlus Text Widget', 'tutsplustextdomain' ),

8

		array(

9

			'classname'   => 'tutsplustext_widget',

10

			'description' => __( 'A basic text widget to demo the Tutsplus series on creating your own widgets.', 'tutsplustextdomain' )

11

		)

12

      );

13

14

      load_plugin_textdomain( 'tutsplustextdomain', false, basename( dirname( __FILE__ ) ) . '/languages' );

15

16

    }

В приведенном выше коде мы вызываем родительскую конструкторскую функцию класса WP_Widget и передаем ей аргументы:

• Base ID - уникальный идентификатор для виджета. Должно быть в нижнем регистре. Если оставить пустым, будет использоваться часть имени класса виджета.
  
• Имя - это имя виджета, отображаемого на странице конфигурации (на панели инструментов).
  
• И (необязательный) массив, содержащий имя класса и описание. Описание показано на странице конфигурации (в панели инструментов WordPress).

Создание обратной формы

Внутренняя форма будет состоять из двух полей: поля заголовка и поля textarea. Вот скриншот формы, как он будет выглядеть в панели Widgets:

Чтобы сгенерировать приведенную выше форму, мы начнем с чистого HTML, а затем заменим некоторые значения атрибутов на некоторые переменные и выражения PHP. Ниже приведен код HTML для создания двух полей:

1

<p>

2

  <label for="title">Title</label>

3

  <input class="widefat" id="title" name="title" type="text" value="WIDGET TITLE" />

4

</p>

5

<p>

6

  <label for="message">Simple Message</label>

7

  <textarea class="widefat" rows="16" cols="20" id="message" name="message">message...</textarea>

8

9

</p>

Чтобы перейти от этого к нашему окончательному коду для функции form (), нам нужно будет сделать некоторые из атрибутов выше динамического - а именно, имя, идентификатор и атрибут label для атрибута (который должен соответствовать идентификатору HTML, что есть метка). Мы также заменим значение текстового поля и содержимого поля textarea динамическими значениями из базы данных, если они уже были сохранены.

Вот код, в котором мы заканчиваем:

1

<?php

2

/**

3

  * Back-end widget form.

4

  *

5

  * @see WP_Widget::form()

6

  *

7

  * @param array $instance Previously saved values from database.

8

  */

9

public function form( $instance ) {    

10

11

    $title 		= esc_attr( $instance['title'] );

12

	$message	= esc_attr( $instance['message'] );

13

	?>

14

15

	<p>

16

		<label for="<?php echo $this->get_field_id('title'); ?>"><?php _e('Title:'); ?></label> 

17

		<input class="widefat" id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo $title; ?>" />

18

	</p>

19

	<p>

20

		<label for="<?php echo $this->get_field_id('message'); ?>"><?php _e('Simple Message'); ?></label> 

21

		<textarea class="widefat" rows="16" cols="20" id="<?php echo $this->get_field_id('message'); ?>" name="<?php echo $this->get_field_name('message'); ?>"><?php echo $message; ?></textarea>

22

	</p>

23

24

	<?php 

25

    }

Приведенный выше код получает доступ и присваивает ранее сохраненные значения из базы данных двум переменным - $title и $message. Затем мы используем esc_attr() для кодирования возвращаемых значений и во избежание нарушения нашего кода. Затем мы возвращаем атрибут $ title в атрибут value текстового поля и echo $ message как содержимое поля textarea.

В приведенном выше коде вы заметите два метода, которые, вероятно, новы для вас: get_field_id () и get_field_name ().

• get_field_id () - принимает имя поля в качестве аргумента и создает атрибуты id для использования в полях form (). Это гарантирует, что идентификатор возвращаемого поля является уникальным
• get_field_name () - принимает имя поля в качестве аргумента и строит атрибуты имени для использования в полях form (). Он гарантирует уникальность имени возвращаемого поля.

Атрибут метки for атрибута закодирован так, чтобы отображать значение id элементов, которые они маркируют.

Класс widefat используется для обеспечения того, чтобы поля вашего виджета были похожи на другие поля на панели инструментов WordPress.

Варианты обновления нашего виджета

Чтобы обновить наш виджет, мы напишем соответствующий код в методе обновления. Здесь есть наш код:

1

<?php

2

/**

3

  * Sanitize widget form values as they are saved.

4

  *

5

  * @see WP_Widget::update()

6

  *

7

  * @param array $new_instance Values just sent to be saved.

8

  * @param array $old_instance Previously saved values from database.

9

  *

10

  * @return array Updated safe values to be saved.

11

  */

12

public function update( $new_instance, $old_instance ) {        

13

14

	$instance = $old_instance;

15

16

	$instance['title'] = strip_tags( $new_instance['title'] );

17

	$instance['message'] = strip_tags( $new_instance['message'] );

18

19

    return $instance;

20

21

}

Вышеупомянутая функция принимает два параметра: $new_instance и $old_instance

• $new_instance - это массив, содержащий новые настройки (этого экземпляра виджета), которые только что были введены пользователем через бэкэнд-форму, которую мы определяем в функции form ().
• $old_settings - это массив, содержащий старые настройки. Это значения, которые в настоящее время хранятся в базе данных.

Функция update () возвращает массив настроек для сохранения или false для отмены сохранения.

В приведенном выше коде мы присваиваем $old_instance переменной $instance и заменяем ее заголовок и ключи сообщений значениями $new_instance. Возвращая новый и обновленный массив, мы эффективно обновляем наши настройки виджета.

Функция strip_tags () удаляет теги HTML и PHP теги из строки, которая передается ему. Мы включаем эту функцию, чтобы избежать ситуации, когда пользователи вашей темы не могут закрыть теги, введенные через внешнюю форму, в результате чего ваш сайт разбивается (не обрабатывается должным образом).

Определение Front-End

Функция widget () отвечает за внешний вид виджета. Он принимает два параметра: $args и $instance.

$args - это массив, переданный функции register_sidebar () при определении боковой области / виджетной области, в которой размещен виджет. Это можно найти в файле functions.php. Ниже приведен пример объявления register_sidebar ():

Массив содержит определения тегов открытия и закрытия самого виджета и заголовка виджета.

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

Мы используем теги, упомянутые выше, в последнем коде виджета:

1

<?php

2

/**  

3

  * Front-end display of widget.

4

  *

5

  * @see WP_Widget::widget()

6

  *

7

  * @param array $args     Widget arguments.

8

  * @param array $instance Saved values from database.

9

  */

10

public function widget( $args, $instance ) {    

11

12

    extract( $args );

13

14

    $title         = apply_filters( 'widget_title', $instance['title'] );

15

    $message 	= $instance['message'];

16

17

	echo $before_widget;

18

19

    if ( $title ) {

20

		echo $before_title . $title . $after_title;

21

	}

22

23

	echo $message;

24

    echo $after_widget;

25

26

}

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

Введем функцию extract (), которую некоторые могут не знать. Эта функция принимает ассоциативный массив и возвращает его ключи как переменные. Это позволяет нам выводить $before_widget вместо $args ['before_widget'], что немного упрощает наш код.

Окончательный результат на фактическом веб-сайте будет выглядеть примерно так:

Регистрация виджета

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

1

<?php

2

add_action( 'widgets_init', function() {

3

     register_widget( 'TutsplusText_Widget' );

4

});

Итоговый код

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

Это также позволит нам сохранить весь код, который мы будем создавать во всей серии в одном файле.

Вот окончательный код:

1

<?php

2

/*

3

Plugin Name: Tutsplus Widget Pack

4

Plugin URI: http://code.tutsplus.com

5

Description: A plugin containing various widgets created in a TutsPlus series on WordPress widgets

6

Version: 0.1

7

Author: Tutsplus

8

Author URI: http://code.tutsplus.com

9

Text Domain: tutsplustextdomain

10

License: GPLv2

11

12

Copyright 2014  Tutsplus

13

14

This program is free software; you can redistribute it and/or modify

15

it under the terms of the GNU General Public License, version 2, as

16

published by the Free Software Foundation.

17

18

This program is distributed in the hope that it will be useful,

19

but WITHOUT ANY WARRANTY; without even the implied warranty of

20

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

21

GNU General Public License for more details.

22

23

You should have received a copy of the GNU General Public License

24

along with this program; if not, write to the Free Software

25

Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

26

*/

27

28

29

class TutsplusText_Widget extends WP_Widget {

30

31

    public function __construct() {

32

33

		parent::__construct(

34

    		'tutsplustext_widget',

35

			__( 'TutsPlus Text Widget', 'tutsplustextdomain' ),

36

			array(

37

				'classname'   => 'tutsplustext_widget',

38

				'description' => __( 'A basic text widget to demo the Tutsplus series on creating your own widgets.', 'tutsplustextdomain' )

39

				)

40

		);

41

42

		load_plugin_textdomain( 'tutsplustextdomain', false, basename( dirname( __FILE__ ) ) . '/languages' );

43

44

    }

45

46

	/**  

47

	 * Front-end display of widget.

48

	 *

49

	 * @see WP_Widget::widget()

50

	 *

51

	 * @param array $args     Widget arguments.

52

	 * @param array $instance Saved values from database.

53

	 */

54

	public function widget( $args, $instance ) {    

55

56

	    extract( $args );

57

58

	    $title     	= apply_filters( 'widget_title', $instance['title'] );

59

	    $message 	= $instance['message'];

60

61

		echo $before_widget;

62

63

	    if ( $title ) {

64

			echo $before_title . $title . $after_title;

65

		}

66

67

		echo $message;

68

	    echo $after_widget;

69

70

	}

71

72

73

	/**

74

	  * Sanitize widget form values as they are saved.

75

	  *

76

	  * @see WP_Widget::update()

77

	  *

78

	  * @param array $new_instance Values just sent to be saved.

79

	  * @param array $old_instance Previously saved values from database.

80

	  *

81

	  * @return array Updated safe values to be saved.

82

	  */

83

	public function update( $new_instance, $old_instance ) {        

84

85

		$instance = $old_instance;

86

87

		$instance['title'] = strip_tags( $new_instance['title'] );

88

		$instance['message'] = strip_tags( $new_instance['message'] );

89

90

	    return $instance;

91

92

	}

93

94

	/**

95

	  * Back-end widget form.

96

	  *

97

	  * @see WP_Widget::form()

98

	  *

99

	  * @param array $instance Previously saved values from database.

100

	  */

101

	public function form( $instance ) {    

102

103

	    $title 		= esc_attr( $instance['title'] );

104

		$message	= esc_attr( $instance['message'] );

105

		?>

106

107

		<p>

108

			<label for="<?php echo $this->get_field_id('title'); ?>"><?php _e('Title:'); ?></label> 

109

			<input class="widefat" id="<?php echo $this->get_field_id('title'); ?>" name="<?php echo $this->get_field_name('title'); ?>" type="text" value="<?php echo $title; ?>" />

110

		</p>

111

		<p>

112

			<label for="<?php echo $this->get_field_id('message'); ?>"><?php _e('Simple Message'); ?></label> 

113

			<textarea class="widefat" rows="16" cols="20" id="<?php echo $this->get_field_id('message'); ?>" name="<?php echo $this->get_field_name('message'); ?>"><?php echo $message; ?></textarea>

114

		</p>

115

116

	<?php 

117

    }

118

119

}

120

121

/* Register the widget */

122

add_action( 'widgets_init', function(){

123

     register_widget( 'TutsplusText_Widget' );

124

});

Заключение

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

Цель этого руководства состояла в том, чтобы предоставить подробное введение в API Widgets и предоставить базовый виджет, из которого могут быть созданы другие виджеты в этой серии.

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