Erstellen eigener Widgets mit verschiedenen WordPress-APIs: Einführung

German (Deutsch) translation by Federicco Ancie (you can also view the original English article)

Final product image — What You'll Be Creating

Widgets sind eine gute Möglichkeit, Websitebesitzern die Kontrolle über das Aussehen (und manchmal die Funktionalität) ihrer WordPress-Websites zu geben. In dieser Serie werden wir eine Handvoll WordPress-Widgets erstellen, indem wir die Widgets-API mit anderen externen APIs kombinieren.

Die Serie besteht aus folgenden Tutorials:

Eine Einleitung
Verwandte Beiträge Widget
Login Widget
FAQ Widget
Widget für die beliebtesen Beiträge mit Google Analytics-Integration
Widget für physische Adressen mit Google Maps-Integration
Abschluss

In diesem Tutorial werde ich Ihnen die WordPress-Widgets-API vorstellen, indem ich ein einfaches Text-Widget (neu) erstelle. Wir werden die verschiedenen Funktionen des Widgets analysieren und untersuchen, um zu verstehen, wie WordPress-Widgets im Allgemeinen funktionieren.

Dieses Widget dient auch als Grundlage, auf der wir beim Erstellen anderer Widgets in den folgenden Teilen dieser Serie aufbauen werden.

WordPress-Widgets

WordPress-Widgets fügen Ihren Seitenleisten oder Widget-Bereichen Ihres Themas Inhalte und Funktionen hinzu. Widgets bieten eine einfache und benutzerfreundliche Möglichkeit, dem Benutzer Design und strukturelle Kontrolle über das WordPress-Thema zu geben, ohne dass er wissen muss, wie man programmiert.

Die meisten WordPress-Widgets bieten Anpassungen und Optionen wie auszufüllende Formulare, optionale Bilder und andere Anpassungsfunktionen.

Untersuchen der Widget-Klasse

Der einfachste Weg, ein WordPress-Widget zu erstellen, besteht darin, die WP_Widget-Klasse zu erben. Auf diese Weise können Sie die integrierten Funktionen verwenden, um das Widget zu aktualisieren, das Widget anzuzeigen und eine Administrationsoberfläche für das Widget zu erstellen.

Um die Funktionsweise von Widgets vollständig zu verstehen, erstellen und untersuchen wir ein leeres Widget. Wir werden dann jede Funktion definieren, aus der das Widget besteht. Sehen Sie also, wie sie zusammenarbeiten, um ein funktionierendes Widget zu erstellen.

Unsere Widget-Definition

<?php
class TutsPlusText_Widget extends WP_Widget {
    
  // widget constructor
  public function __construct(){
    
  }
   
  public function widget( $args, $instance ) {
    // outputs the content of the widget
  }
   
  public function form( $instance ) {
    // creates the back-end form
  }
   
  // Updating widget replacing old instances with new
  public function update( $new_instance, $old_instance ) {
    // processes widget options on save
  }
  
}

Die Funktionen im Detail

Schauen wir uns jede Funktion genauer an:

__construct()

Diese Funktion registriert das Widget bei WordPress

widget()

Diese Funktion ist für die Front-End-Anzeige des Widgets verantwortlich. Es gibt den Inhalt des Widgets aus

update()

Verarbeitet die Widget-Optionen beim Speichern. Verwenden Sie diese Funktion, um Ihr Widget zu aktualisieren (Option). Diese Funktion akzeptiert zwei Parameter:

$new_instance - Werte, die gerade gesendet wurden, um gespeichert zu werden. Diese Werte stammen aus dem in der form()-Methode definierten Formular
$old_instance - Zuvor gespeicherte Werte aus der Datenbank

Stellen Sie sicher, dass Sie alle vom Benutzer übermittelten Werte hier bereinigen. Vom Benutzer übermittelte Werte müssen immer bereinigt werden, bevor sie an die Datenbank gesendet werden

form()

Die Methode/Funktion form() wird verwendet, um das Back-End-Widget-Formular zu definieren, das Sie im Widgets-Bereich im Dashboard sehen. Mit diesem Formular kann ein Benutzer den Titel und andere Optionen für das Widget einrichten.

Diese Funktion akzeptiert die folgenden Parameter:

$instance - Zuvor gespeicherte Werte aus der Datenbank

Unser Widget erstellen

Um unser Widget zu erstellen, gehen Sie folgendermaßen vor:

Definieren Sie, was wir erstellen
Registrieren Sie unser Widget bei WordPress
Erstellen Sie das Back-End-Formular
Speichern Sie Werte in der Datenbank
Definieren Sie das Front-End-Display
Registrieren Sie das Widget

Was schaffen wir?

Wie bereits erwähnt, erstellen wir ein einfaches Text-Widget, mit dem ein Benutzer einen Titel und einen beliebigen Text eingeben kann, der dann im Front-End seiner Website ausgegeben wird, auf der das Widget platziert ist.

Widget-Konstruktor

Mit dem Konstruktor können wir unser Widget initialisieren, indem wir die übergeordnete Klasse (Standardklasse WP_Widget) überschreiben.

<?php

public function __construct(){
    
	parent::__construct(
    	'tutsplustext_widget',
		__( 'TutsPlus Text Widget', 'tutsplustextdomain' ),
		array(
			'classname'   => 'tutsplustext_widget',
			'description' => __( 'A basic text widget to demo the Tutsplus series on creating your own widgets.', 'tutsplustextdomain' )
		)
      );
      
      load_plugin_textdomain( 'tutsplustextdomain', false, basename( dirname( __FILE__ ) ) . '/languages' );
      
    }

Im obigen Code rufen wir die Konstruktionsfunktion der übergeordneten WP_Widget-Klasse auf und übergeben ihr die folgenden Argumente:

Basis-ID - Eine eindeutige Kennung für das Widget. Muss in Kleinbuchstaben sein. Wenn leer, wird ein Teil des Klassennamens des Widgets verwendet.
Name - Dies ist der Name für das Widget, das auf der Konfigurationsseite (im Dashborad) angezeigt wird.
Und ein (optionales) Array, das einen Klassennamen und eine Beschreibung enthält. Die Beschreibung wird auf der Konfigurationsseite (im WordPress-Dashboard) angezeigt.

Erstellen des Back-End-Formulars

Das Backend-Formular besteht aus zwei Feldern - einem Titelfeld und einem Textfeld. Hier ist ein Screenshot des Formulars, wie es im Widgets-Bedienfeld angezeigt wird:

Um das obige Formular zu generieren, beginnen wir mit reinem HTML und ersetzen dann einige Attributwerte durch einige PHP-Variablen und Ausdrücke. Das Folgende ist der HTML-Code zum Erstellen der beiden Felder:

<p>
  <label for="title">Title</label>
  <input class="widefat" id="title" name="title" type="text" value="WIDGET TITLE" />
</p>
<p>
  <label for="message">Simple Message</label>
  <textarea class="widefat" rows="16" cols="20" id="message" name="message">message...</textarea>
              
</p>

Um von diesem zu unserem endgültigen Code für die form() -Funktion zu gelangen, müssen wir einige der oben genannten Attribute dynamisch machen - nämlich Name, ID und das Attribut for der Bezeichnung (das mit der ID des HTML-Codes übereinstimmen muss, den die Bezeichnung enthält ist für). Wir werden auch den Wert des Textfelds und den Inhalt des Textfelds durch dynamische Werte aus der Datenbank ersetzen, sofern diese bereits gespeichert wurden.

Hier ist der Code, mit dem wir enden:

<?php
/**
  * Back-end widget form.
  *
  * @see WP_Widget::form()
  *
  * @param array $instance Previously saved values from database.
  */
public function form( $instance ) {    

    $title 		= esc_attr( $instance['title'] );
	$message	= esc_attr( $instance['message'] );
	?>
	
	<p>
		<label for="<?php echo $this->get_field_id('title'); ?>"><?php _e('Title:'); ?></label> 
		<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; ?>" />
	</p>
	<p>
		<label for="<?php echo $this->get_field_id('message'); ?>"><?php _e('Simple Message'); ?></label> 
		<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>
	</p>
	
	<?php 
    }

Der obige Code greift auf zuvor gespeicherte Werte aus der Datenbank zu und weist zwei Variablen zu - $title und $message. Wir verwenden dann esc_attr(), um die zurückgegebenen Werte zu codieren und zu vermeiden, dass unser Code beschädigt wird. Anschließend geben wir das Attribut $title in das Attribut value des Textfelds zurück und geben $message als Inhalt des Textfelds wieder.

Im obigen Code werden Sie zwei Methoden bemerken, die für Sie wahrscheinlich neu sind - get_field_id() und get_field_name().

get_field_id() - Nimmt den Feldnamen als Argument und erstellt ID-Attribute zur Verwendung in form()-Feldern. Es stellt sicher, dass die zurückgegebene Feld-ID eindeutig ist
get_field_name() - Nimmt den Feldnamen als Argument und erstellt Namensattribute zur Verwendung in form()-Feldern. Es stellt sicher, dass der zurückgegebene Feldname eindeutig ist.

Das Attribut label tag for ist so codiert, dass der ID-Wert der Elemente, die sie kennzeichnen, wiedergegeben wird.

Die widefat-Klasse wird verwendet, um sicherzustellen, dass die Felder Ihres Widgets genauso aussehen wie andere Felder im gesamten WordPress-Dashboard.

Aktualisieren unseres Widgets (Optionen)

Um unser Widget zu aktualisieren, schreiben wir den entsprechenden Code in die Aktualisierungsmethode. Hier ist unser Code:

<?php
/**
  * Sanitize widget form values as they are saved.
  *
  * @see WP_Widget::update()
  *
  * @param array $new_instance Values just sent to be saved.
  * @param array $old_instance Previously saved values from database.
  *
  * @return array Updated safe values to be saved.
  */
public function update( $new_instance, $old_instance ) {        
	
	$instance = $old_instance;
	
	$instance['title'] = strip_tags( $new_instance['title'] );
	$instance['message'] = strip_tags( $new_instance['message'] );
	
    return $instance;
    
}

Die obige Funktion akzeptiert zwei Parameter - $new_instance und $old_instance

$new_instance ist ein Array, das die neuen Einstellungen (dieser Instanz des Widgets) enthält, die der Benutzer gerade über das Backend-Formular eingegeben hat, das wir in der Funktion form() definieren.
$old_settings ist ein Array mit alten Einstellungen. Dies sind die Werte, die derzeit in der Datenbank gespeichert sind.

Die Funktion update() gibt eine Reihe von Einstellungen zurück, die gespeichert werden sollen, oder false, um das Speichern abzubrechen.

Im obigen Code weisen wir der $instance-Variablen $old_instance zu und ersetzen ihren Titel und ihre Nachrichtenschlüssel durch Werte aus $new_instance. Durch die Rückgabe des neuen und aktualisierten Arrays aktualisieren wir effektiv unsere Widget-Einstellungen.

Die Funktion strip_tags() entfernt HTML- und PHP-Tags aus einer an sie übergebenen Zeichenfolge. Wir schließen diese Funktion ein, um zu vermeiden, dass die Benutzer Ihres Themas die über das Back-End-Formular eingegebenen Tags nicht schließen können, was dazu führt, dass Ihre Website beschädigt wird (nicht richtig gerendert wird).

Das Front-End definieren

Die Funktion widget() ist für die Front-End-Anzeige des Widgets verantwortlich. Es werden zwei Parameter benötigt - $args und $instance.

$args ist ein Array, das an die Funktion register_sidebar() übergeben wird, wenn der Seitenleisten-/Widget-Bereich definiert wird, in dem das Widget platziert wird. Dies befindet sich in Ihrer Datei functions.php. Unten finden Sie ein Beispiel für eine register_sidebar() - Deklaration:

Das Array enthält Definitionen der öffnenden und schließenden Tags für das Widget selbst und für den Titel des Widgets.

$instance ist ein Array, das die Einstellungen für die bestimmte Instanz des Widgets enthält. Diese Einstellungen wurden aus der Datenbank abgerufen.

Wir verwenden die oben genannten Tags im endgültigen Widget-Code:

<?php
/**  
  * Front-end display of widget.
  *
  * @see WP_Widget::widget()
  *
  * @param array $args     Widget arguments.
  * @param array $instance Saved values from database.
  */
public function widget( $args, $instance ) {    
    
    extract( $args );
    
    $title         = apply_filters( 'widget_title', $instance['title'] );
    $message 	= $instance['message'];
    
	echo $before_widget;
    
    if ( $title ) {
		echo $before_title . $title . $after_title;
	}
						
	echo $message;
    echo $after_widget;
    
}

Im obigen Code können wir endlich das Front-End unseres Widgets codieren. Unser Widget gibt einfach einen Titel und eine beliebige Nachricht (Text) aus. Der Code macht genau das und umschließt das Widget selbst und den Titel des Widgets mit öffnenden und schließenden Tags, die in functions.php für den spezifischen Widget-Bereich (Seitenleiste) definiert sind, in dem sich das Widget befindet.

Wir führen die Funktion extract() ein, mit der einige möglicherweise nicht vertraut sind. Diese Funktion verwendet ein assoziatives Array und gibt seine Schlüssel als Variablen zurück. Es ermöglicht uns, $before_widget anstelle von $args['before_widget'] wiederzugeben, wodurch unser Code ein wenig vereinfacht wird.

Die endgültige Ausgabe auf einer tatsächlichen Website sieht ungefähr so aus:

Registrieren des Widgets

Das Widget muss nach seiner Definition bei WordPress registriert werden, damit es im Widget-Bereich unseres WordPress-Dashboards verfügbar ist.

1	<?php
2	add_action( 'widgets_init', function() {
3	register_widget( 'TutsplusText_Widget' );
4	});

Der endgültige Code

Um den Endbenutzern unserer Widgets die Arbeit zu erleichtern, werden wir unseren Widget-Code in ein WordPress-Plugin einbinden, damit er einfach zu installieren ist.

Auf diese Weise können wir auch den gesamten Code, den wir während der gesamten Serie erstellen, in einer einzigen Datei speichern.

Hier ist der endgültige Code:

<?php
/*
Plugin Name: Tutsplus Widget Pack
Plugin URI: http://code.tutsplus.com
Description: A plugin containing various widgets created in a TutsPlus series on WordPress widgets
Version: 0.1
Author: Tutsplus
Author URI: http://code.tutsplus.com
Text Domain: tutsplustextdomain
License: GPLv2

Copyright 2014  Tutsplus

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.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
*/


class TutsplusText_Widget extends WP_Widget {

    public function __construct() {
    
		parent::__construct(
    		'tutsplustext_widget',
			__( 'TutsPlus Text Widget', 'tutsplustextdomain' ),
			array(
				'classname'   => 'tutsplustext_widget',
				'description' => __( 'A basic text widget to demo the Tutsplus series on creating your own widgets.', 'tutsplustextdomain' )
				)
		);
      
		load_plugin_textdomain( 'tutsplustextdomain', false, basename( dirname( __FILE__ ) ) . '/languages' );
      
    }

	/**  
	 * Front-end display of widget.
	 *
	 * @see WP_Widget::widget()
	 *
	 * @param array $args     Widget arguments.
	 * @param array $instance Saved values from database.
	 */
	public function widget( $args, $instance ) {    
	    
	    extract( $args );
	    
	    $title     	= apply_filters( 'widget_title', $instance['title'] );
	    $message 	= $instance['message'];
	    
		echo $before_widget;
	    
	    if ( $title ) {
			echo $before_title . $title . $after_title;
		}
							
		echo $message;
	    echo $after_widget;
	    
	}

 
	/**
	  * Sanitize widget form values as they are saved.
	  *
	  * @see WP_Widget::update()
	  *
	  * @param array $new_instance Values just sent to be saved.
	  * @param array $old_instance Previously saved values from database.
	  *
	  * @return array Updated safe values to be saved.
	  */
	public function update( $new_instance, $old_instance ) {        
		
		$instance = $old_instance;
		
		$instance['title'] = strip_tags( $new_instance['title'] );
		$instance['message'] = strip_tags( $new_instance['message'] );
		
	    return $instance;
	    
	}
 
	/**
	  * Back-end widget form.
	  *
	  * @see WP_Widget::form()
	  *
	  * @param array $instance Previously saved values from database.
	  */
	public function form( $instance ) {    
	
	    $title 		= esc_attr( $instance['title'] );
		$message	= esc_attr( $instance['message'] );
		?>
		
		<p>
			<label for="<?php echo $this->get_field_id('title'); ?>"><?php _e('Title:'); ?></label> 
			<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; ?>" />
		</p>
		<p>
			<label for="<?php echo $this->get_field_id('message'); ?>"><?php _e('Simple Message'); ?></label> 
			<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>
		</p>
	
	<?php 
    }
    
}

/* Register the widget */
add_action( 'widgets_init', function(){
     register_widget( 'TutsplusText_Widget' );
});

Abschluss

In diesem Tutorial haben wir die Serie vorgestellt - Erstellen eigener WordPress-Widgets mit verschiedenen APIs. Wir haben uns genauer angesehen, was sie sind, wie sie funktionieren und wie man sie erstellt.

Der Zweck dieses Tutorials bestand darin, eine gründliche Einführung in die Widgets-API zu geben und ein Basis-Widget bereitzustellen, aus dem die anderen Widgets in dieser Reihe erstellt werden können.

Im nächsten Teil der Serie werden wir ein Widget für verwandte Beiträge erstellen. In der Zwischenzeit können Sie Fragen oder Kommentare im unten stehenden Formular hinterlassen.

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	});