Code Widget Wordpress

WordPress: Erstellen von Widgets

16. Feb. 2017 // Moritz Kanzler //

Widgets stellen tolle Möglichkeiten zur Verfügung, um einerseits den eigenen Code modular zu halten und andererseits einem Theme nützliche Zusatzfunktionen mitzugeben. In diesem Tutorial geht es darum wie man Widgets in einem Theme aktiviert, diese programmiert und mit Leben füllt und um einige Best Practices um Widgets einzubinden, die ich in meiner Arbeit anwende.

Widgets Theorie und Praxis

Widget Ansicht WordPress

Abbildung 1: Widgetbereich Backend

Widgets sind Module in WordPress welche für alle Benutzer einfach in eine registrierte Seitenleiste eingebettet werden können. Sie bieten also sowohl für Redakteure als auch Administratoren eine einfache Möglichkeit Funktionen in die Seite einzubinden. Somit erspart man sich Änderungen im Code um Darstellungsformen in die Seite einzubinden.

Eine klassische Weise Widgets zu verwenden ist in einer Seitenleiste. Dabei sind die verschiedenen Teile einer Seitenleiste die einzelnen Widgets. In WordPress Backend sieht das wie in Abbildung 1 rechts aus.

Widgets sollten aber nicht nur als kleine Gimmicks in der Seitenleiste gesehen werden sondern als nützliche Elemente deiner Seite die man eigentlich überall einbinden kann, so zum Beispiel in:

  • einem Footer,
  • einem Element über oder neben dem Content,
  • als dynamische Elemente innerhalb des Contents.

WordPress hat von Haus aus schon einige hervorragende Widgets mit an Bord, vor allem gängig gebrauchte wie Kategorieübersichten, Tagwolken oder RSS Feed Ausgaben. Dennoch haben mir diese Widgets beim erstellen meines Themes nicht ausgereicht, da ich durch die Einbindung von Bootstrap teilweise Einfluss auf das Markup der Ausgabe haben wollte, oder aber Informationen zusätzlich anzeigen oder weglassen wollte. Deshalb habe ich mich dazu entschlossen die Kategorie- und Tag-Liste für meinen Blog anders zu implementieren. Im Folgenden werde ich beschreiben wie ich ein Kategorie Widget nach meinen Vorstellungen entwickelt und eingebunden habe.

Seitenleisten anlegen

Die Widgetübersicht im Backend findet man normalerweise unter Design -> Widgets im Backend Admin Menü von WordPress. Hat man jedoch eine Theme ganz neu von Grund auf aufgezogen, kann dieser Menüpunkt zunächst fehlen, weil keine Seitenleiste für das eigene WordPress Theme definiert ist.

Wofür braucht man eine Seitenleiste? Wir wollen doch Widgets!

Seitenleiste bedeutet für WordPress einen Platzhalter in dem Widgets abgelegt werden können. Ein Theme kann in WordPress keine oder beliebig viele Seitenleisten haben. Das Wort „Seitenleiste“ ist wie schon oben angeschnitten also nicht wörtlich zu verstehen. Es geht viel mehr um einen Container in dem Widgets abgelegt werden können. Dieser Container kann an beliebigen Stellen des WordPresslayouts eingebunden werden, also auch als Footer oder ähnliches.

Eine Seitenleiste definieren und anlegen

Um also eine erste bzw. weitere Seitenleiste(n) anzulegen, muss man diese zunächst registrieren. Dabei definiert man auch ihre Eigenschaften. Diese Definition wird in die functions.php des Themes eingetragen.

Zunächst legt man sich eine Funktion in der functions.php an, welche die später benötigten Aufrufe enthält. In meinem Fall heißt diese Funktion my_widgets_init(). Der Name ist natürlich frei wählbar.

Um die eigene Widget Funktion in WordPress einzuhängen nutzen man die add_action() Funktion, genauer das widgets_init Tag.

Innerhalb der eigenen my_widgets_init() Funktion registriert man nun eine WordPress Seitenbar:

register_sidebar() sorgt dafür, dass im Backend Bereich eine Seitenbar als Widgetcontainer angelegt wird. Sie trägt eine eindeutige id mit der sie überall im Theme referenziert werden kann. Es gibt noch viele weitere Parameter für die Funktion, ich beschreibe hier nur die häufig gebrauchten:

  • name: Name der Sidebar, wird auch im Backend als Titel im Backend angezeigt.
  • id: Eindeutige ID welche zum Aufruf an verschiedenen Stellen im Theme dient.
  • before_/after_widget*: HTML Element welches, pro eingebautem Widget, um den Widgetcode gelegt wird.
  • before_/after_title*: HTML Element, welches um den Titel jedes Widgets gelegt wird.

*beides muss im eigenen Widget auch verwendet werden, sonst wird es nicht ausgegeben. Bei den vorgefertigten Widgets werden sie aber verwendet!

Nach diesem Schritt ist im Backend der angelegte Widget Container unter Design -> Widget sichtbar und kann per Drag & Drop mit vorhandenen Widgets befüllt werden.

Abbildung 2: Widgetcontainer nach Anlegen

Seitenleiste im Theme ausgeben

Will man eine Seitenleiste ausgeben, zum Beispiel in der sidebar.php, dann muss man lediglich die Funktion dynamic_sidebar() ausführen. Eine if-Abfrage hilft andere Konfigurationen abzufangen.

Widgets anlegen

Jetzt beginnt das Herzstück des Tutorials, das anlegen eines eigenen Widgets welches in einer Seitenleiste ausgeben werden kann.

Das Widget in diesem Tutorial soll die genutzten Kategorien des WordPressblogs ausgeben. Folgende zusätzliche Optionen sollen angegeben werden können:

  • Eine Überschrift für das Widget soll gesetzt werden können,
  • eine Maximalanzahl für die ausgegebenen Kategorien soll ebenfalls gesetzt werden können,
  • außerdem soll entschieden werden können, ob die Anzahl der Posts pro Kategorien mit ausgegeben werden.

Ein neues Widget definieren

Zunächst legt man eine neue Datei an, die den Code für das Widget enthält. In meinem Fall erstelle ich zunächst aber einen Ordner widgets/ als Verzeichnis für alle Widgets. Da das Widget Kategorien ausgeben soll, lege ich innerhalb des Ordners widgets/ die Datei widgets.myblog-categories.php an.

In diese Datei kopiere ich dann zunächst einen Schablonencode, der nach und nach mit Leben gefüllt wird.

Auch wenn das Widget bisher nichts tut, ist es schon korrekt definiert. Was noch fehlt ist die Bekanntmachung des Widgets mit WordPress und dem eigenem Theme. Dazu wird die Funktion register_widget() innerhalb der eigenen my_widgets_init() genutzt:

Abbildung 3: Selbst angelegtes Widget in der Auswahl

Jetzt sollte das Widget auf der Auswahlseite unter den anderen Widgets zu finden sein und genauso in eine Seitenleiste zu schieben sein, was noch fehlt ist eine Funktionalität und der Inhalt des Widgets.

Eingabemöglichkeit des Widgets definieren

Die meisten Widgets bieten nicht nur eine einfache Ausgabe von bestimmten Daten innerhalb einer „sidebar“ sondern auch noch Einstellungsmöglichkeiten welche die Ausgabe manipulieren können. Auch in diesem Fall sind einige Einstellungen gewünscht. Weiter oben gab es die Anforderungen:

  1. eine Überschrift setzen zu können,
  2. eine Maximalanzahl der auszugebenden Kategorien zu bestimmen,
  3. und zu entscheiden ob die Anzahl der Beiträge pro Kategorie mit ausgegeben werden oder nicht.

Um die Anforderungen abzudecken müssen wir die Methode form() Methode unserer Klasse MyBlog_Categories, also dem Widget anpassen:

Abbildung 4: Kategorie Widget im Backend

Setzt man diesen Code in die form() Methode ein, erhält man in der Widgetauswahl im Backend unter dem eigenen Widget die benötigten Felder (siehe Abbildung 4).

Wie man im Code oben erkennt, legen wir die Text- und Auswahlfelder ganz normal in HTML an (unter //2). Es wird dabei pro Zeile ein p-Tag genutzt. Darunter ein Label und eine Eingabemöglichkeit. Um bei dem Backendstyle von WordPress zu bleiben kann man hier die CSS Klasse widefat nutzen.

Was entscheidend ist, ist die Referenzierung der Felder auf die später abgespeicherten Werte. Um die vorgenommen Einstellungen in einem Widget abzuspeichern und zum Beispiel bei der Ausgabe zu berücksichtigen müssen diese ja zwischengespeichert werden. Dies geschieht in einer Datenbanktabelle für jedes angelegte Widget. Damit WordPress aber weiß welches Eingabefeld (oben) zu welchem Datenbankeintrag gehört muss die eindeutige ID und der Name in den Eingabefeldern mitgegeben werden. Das geschieht über die Funktionen  und .

Um auch vorher definierte Werte als „Voreinstellung“ anzuzeigen können innerhalb der Methode auch die bisher gesetzten Werte geladen werden (siehe //1).

Speichern der Widgeteinstellungen

Um die Werte des eigenen Widgets auch dauerhaft in der Datenbank abspeichern zu können wird die Methode update() in der Widgetklasse genutzt:

Innerhalb der Methode reicht es normalerweise lediglich alle benötigten Attribute aus der Variablen $new_instance in $instance zu speichern und zusätzlich default-Werte anzugeben.

Die Variable $new_instance hält alle Eingabewerte nach dem Drücken auf „Speichern“. $old_instance enthält die bisher gespeicherten Werte. $instance als return-Value stellt den jetzt zu speichernden Datenbestand dar.

Ausgabe des Widgets definieren

Die Ausgabe wird über die Methode widget() genutzt. Es werden zwei Variablen als Argumente übergeben $args und $instance.

$args beinhaltet die Werte aus der register_widget() Funktion. Also umschließende HTML-Container und ähnliches.

$instance hingegen hält alle Werte die in dem Widget in den vorherigen Schritten hinterlegt wurden. Eine Beispielausgabe für die Kategorien ist also zu Beispiel dieser Code:

Abschluss

Damit sind wäre das Widget fertig und voll funktionsbereit und kann genutzt werden. Über die obige Schablone können Widgets für die verschiedensten Anforderungen erstellt werden.

Modularer Aufbau

Bei wenigen Widgets können diese direkt in der functions.php definiert werden. Irgendwann wird diese aber ziemlich aufgebläht. Um dem entgegen zu wirken habe ich die Widgets in eigenen Dateien in dem widgets/ Ordner ausgelagert. Nun müssen diese noch mit der functions.php bekannt gemacht werden. Da auch hier jedes einzelne Widget über die Funktion get_template_part() eingebunden werden müsste habe ich noch eine Zwischenebene angelegt.

Innerhalb des widgets/ Ordner gibt es neben den eigentlichen Widgets noch eine Datei widgets.php. Diese sammelt alle Widgets in dem Ordner und inkludiert diese:

Nun reicht es in der functions.php nur noch die widgets/widgets.php zu referenzieren: