Schnellstart zur Widget-Programmierung für WordPress
Widgets sind kleine Module, die der Sidebar eines Blogs neue Funktionen beibringen. Schon mit WordPress wird ein Hand voll Widgets mitgeliefert, die man beispielsweise für die Anzeige der jüngsten Kommentare oder die Textsuche im Blog einsetzen kann.
Daneben gibt’s eine raue Menge von Widgets aus der Werkstatt unabhängiger Programmierer. Diese Widgets sind nachträglich installierbare Plugins, die einigen Vorgaben für die Einbettung in WordPress folgen.
Ich werde das Vorgehen bei der Widgetprogrammierung an Hand der Entwicklung eines Widgets, das den Body Mass Index errechnen kann, Schritt für Schritt aufdröseln und mit Beispielcode erläutern (Warum gerade was zum BMI? Nun, aus Faulheit – der Codeschnippsel war schon hier im Einsatz und musste nur als Widget verpackt werden).
So wird das fertige Widget aussehen – versuch’s mal!
Das Programmiermodell von WordPress-Widgets
Namensraum
Widgets teilen den Namensraum für Variable, Optionen, Funktionen, DOM-Elemente und anderes mit dem Rest von WordPress.
Um Kollisionen mit WordPress oder auch Widgets anderer Autoren zu vermeiden, ist es daher am klügsten, ein neues Widget eindeutig zu benennen und diesen Namen als Präfix für alle globalen Objekte zu verwenden.
Integration in das Basissystem
Das Plugin muss zumindest den Code für Darstellung des Widgets im öffentlich sichtbaren Bereich der Website enthalten. Viele Widgets enthalten zusätzlich noch einen Konfigurationsdialog, der im Backend genutzt wird – den so genannten Controller.
Das Plugin registriert seine eigenen Funktionen für die öffentliche Darstellung und für den Controller beim Laden über die beiden WordPress-Funktionen wp_register_sidebar_widget() und wp_register_widget_control(), und WordPress sorgt anschließend dafür, dass das Widget bei Bedarf die Kontrolle erhält.
Ein Widget-Rohgerüst
Das rohe Skelett eines Widgets sieht demnach so aus:
- Einleitender Kommentar, den WordPress auf der Plugin-Seite im Backend anzeigt
- Initialisierungsfunktion als Eventhandler für den Event
widget_init
- Funktion für die Verarbeitung der Benutzereingaben und die Ausgabe auf der öffentlichen Seite der Website (view)
- Funktion für die Konfiguration des Widgets (controller)
<?php
/*
Plugin Name: Body Mass Index (BMI)
Plugin URI: http://bikinifigur.at/goodies/wp-bmi-rechner
Description: Allows the user to calculate the BMI from body weight and height.
Author: Robert Wetzlmayr
Version: 1.0
Author URI: http://wetzlmayr.at/
License: GPL 2.0, @see http://www.gnu.org/licenses/gpl-2.0.html
*/
function wet_bmicalc_init() {
// check for the required WP functions, die silently for pre-2.2 WP.
if ( !function_exists('wp_register_sidebar_widget') )
return;
// front end view
function wet_bmicalc($args) {
extract($args);
// the widget's form, themeable through $args
echo $before_widget . $before_title . $title . $after_title;
echo '<div style="margin-top:5px;">';
echo '</div>';
echo $after_widget;
}
// back end controller
function wet_bmicalc_control() {
}
// let WP know of this plugin's widget view entry
wp_register_sidebar_widget('wet_bmicalc', 'Body Mass Index',
'wet_bmicalc',
array(
'classname' => 'wet_bmicalc',
'description' =>'Allows the user to calculate the Body Mass Index'.
' (BMI) from body weight and height.'
)
);
// let WP know of this widget's controller entry
wp_register_widget_control('wet_bmicalc', 'Body Mass Index',
'wet_bmicalc_control',
array(
'width' => 300
)
);
}
add_action('widgets_init', 'wet_bmicalc_init');
?>
Download
Das Widget-Gesicht gestalten
Im nächsten Schritt wird der view für das Frontend mit Leben gefüllt: Zwei Eingabefelder für Körpergröße und Gewicht, ein Ausgabeelement für den daraus errechneten BMI und die eigentliche Rechenfunktion in Form eines Scripts reichen für dieses einfache Widget.
wet_bmicalc sieht dann so aus:
<?php
/* ... */
function wet_bmicalc($args) {
extract($args);
echo <<<JS
<script type="text/javascript">
function wet_bmicalc()
{
var theform = document.getElementById('wet_bmicalc_form');
var bmi = document.getElementById('wet_bmicalc_bmi');
var pane = document.getElementById('wet_bmicalc_pane');
var h = theform.wet_bmicalc_height.value;
var result_value;
// ...calculation of result_value done here...
bmi.innerHTML = result_value;
pane.style.display = "block";
}
</script>
JS;
// the widget's form, themeable through $args
echo $before_widget . $before_title . $title . $after_title;
echo '<div style="margin-top:5px;">';
echo '<noscript><p>This Widget requires Javascript</p></noscript>';
echo <<<FORM
<form id='wet_bmicalc_form' method='post'>
<label for='wet_bmicalc_height'>Grösse</label><br />
<input id='wet_bmicalc_height' type='text' name='wet_bmicalc_height' value='' />
<label for='wet_bmicalc_weight'>Gewicht</label><br />
<input id='wet_bmicalc_weight' type='text' name='wet_bmicalc_weight' value='' />
<p id='wet_bmicalc_pane' style='display:none'>
BMI: <strong id='wet_bmicalc_bmi'></strong>.
</p>
<input type='submit' value='Los!' onclick='wet_bmicalc(); return false;' />
</form>
FORM;
echo '</div>';
echo $after_widget;
}
/* ... */
?>
Download
Die richtige Einstellung zu WordPress-Widgets
Widgets sollen flexibel sein, damit sie möglichst universell eingesetzt werden können. Das BMI-Widget hat zwei triviale Optionen: die Buttonbeschriftung und den Titel.
Die Einstellung von Optionen für ein Widget passiert im Backend über ein Formular, das WordPress bei der Administration öffnet, und das im Widget-Controller codiert ist.
// back end options dialogue
function wet_bmicalc_control() {
$options = get_option('wet_bmicalc');
if ( !is_array($options) )
$options = array('title'=>'Body Mass Index', 'buttontext'=>'Calculate');
if ( $_POST['wet_bmicalc-submit'] ) {
$options['title'] = strip_tags(stripslashes($_POST['wet_bmicalc-title']));
$options['buttontext'] = strip_tags(stripslashes($_POST['wet_bmicalc-buttontext']));
update_option('wet_bmicalc', $options);
}
$title = htmlspecialchars($options['title'], ENT_QUOTES);
$buttontext = htmlspecialchars($options['buttontext'], ENT_QUOTES);
echo '<p style="text-align:right;">'.
'<label for="wet_bmicalc-title">Title:'.
' <input style="width: 200px;" id="wet_bmicalc-title"
name="wet_bmicalc-title" type="text" value="'.
$title.'" /></label></p>';
echo '<p style="text-align:right;">'.
'<label for="wet_bmicalc-buttontext">Button Text:'.
' <input style="width: 200px;" id="wet_bmicalc-buttontext"
name="wet_bmicalc-buttontext" type="text" value="'
.$buttontext.'" /></label></p>';
echo '<input type="hidden" id="wet_bmicalc-submit"
name="wet_bmicalc-submit" value="1" />';
}
Download
Diese Optionen werden später in wet_bmicalc() wieder geladen und im Markup verwendet, ich spare mir den entsprechenden Codeausschnitt hier und verweise auf den Download des vollständigen Plugins.
Widgets mit Fremdsprachenkenntnissen
Alle Textausgaben sind tief im Code begraben – nicht gerade ideal für ein international einsetzbares Widget. Besser ist, ebenso wie WordPress selbst Sprachdateien zum Widget zu erstellen, in alle Zielsprachen zu übersetzen und die passenden Texte abhängig von der Spracheinstellung des Website zu laden.
Zur Lokalisierung von WordPress mit poEdit habe ich ja schon ein wenig geschrieben, das auch bei Widgets anwendbar ist. Linuxer haben alle nötigen Werkzeuge an Bord und können sofort loslegen, bei Windows hilft gettext for Win32.
Einfach zum Mitnehmen
Das fertige Widget kannst du hier herunterladen.
