Wordpress-Plugins mit Hilfe versehen

Usability kommt bei vielen WordPress-Plugins leider zu kurz, dabei bietet WordPress diverse Funktionen die dabei helfen. Unter anderem kann man sein eigenes Plugin mit einer Kontext-Hilfe versehen. Damit ist der kleine Reiter „Hilfe“ gemeint, der im Backend auf jeder Seite rechts oben zu sehen ist. Relativ einfach lässt sich hier ein eigener Hilfetext einbauen. Die Funktion dafür ist aber nicht wirklich gut dokumentiert, zumindest musste ich länger suchen, bis ich eine mir genehme Lösung gefunden hatte.

Für das Anpassen des Hilfetextes bietet WordPress die Action contextual_help. Die einfachste Variante einen eigenen Text einzubinden dürfte die folgende sein:

function my_contextual_help($text) {
  $screen = $_GET['page'];
  if ($screen == 'my_plugin') {
    $text = '&lt;h5&gt;Hilfe zum Plugin&lt;/h5&gt;';
    $text .= '&lt;p&gt;Jede Menge Hilfetext und ganz viel Beschreibung, aber auch nicht zu viel, eben so viel, dass es reicht.&lt;/p&gt;';
    $text .= &lt;p&gt;'Vielleicht auch noch ein Link irgendwo hin.&lt;/p&gt;';
  }
  return $text;
}

add_action('contextual_help', 'my_contextual_help');

Zunächst wird überprüft, ob es sich bei der aufgerufenen Seite um die Seite des eigenen Plugins handelt. Nur dann wird der Hilfetext in $text geschrieben und zurückgegeben. Ansonsten wird $text unverändert (übergeben wir der Standard-Hilfetext von WordPress – Links zum Support-Forum und zu WordPress.org) gelassen und zurückgegeben.

Im Codex findet man zur Kontext-Hilfe den Artikel Adding Contextual Help to Administration Menus. Hier wird das ganze ein klein wenig komplizierter gemacht:

function my_plugin_help($contextual_help, $screen_id, $screen) {
  global $my_plugin_hook;
  if ($screen_id == $my_plugin_hook) {
    $contextual_help = 'This is where I would provide help to the user on how everything in my admin panel works. Formatted HTML works fine in here too.';
  }
  return $contextual_help;
}

add_action('contextual_help', 'my_plugin_help', 10, 3);

Die Hilfe-Funktion bekommt hier drei Parameter: Den Text, die Kontext-ID der Hilfeseite und $screen, bei dem ich nicht weiß, was er macht. Die Kontext-ID ist der Rückgabewert der Funktion add_options_page und sollte an der Stelle in einer globalen Variable gespeichert werden, damit man in der Hilfe-Funktion darauf prüfen kann. Beim Anmelden der Action muss dann auch angegeben werden, dass drei Parameter verwendet werden (die 3 im Aufruf von add_action – Die 10 ist die Priorität der Action).

So lange die erweiterte Version nicht echte Vorteile bringt, halte ich die erste Variante allerdings für praktischer. Schade ist allerdings, dass man beim Anmelden der Action nicht gleich mit angeben kann, für welche Seite diese ausgeführt werden soll, denn so kann man auch schnell die Kontext-Hilfe für alle anderen Seiten aus Versehen „kaputt“ machen.

BjoernAhrens.de

WordPress-Plugins mit Hilfe versehen