Als Entwickler von WordPress-Plugins ärgert man sich immer wieder aufs neue, wenn man in seinem Plugin Einstellungen für den Nutzer ermöglichen möchte. Zwar liefert WordPress genau hierfür einige mächtige Tools mit, sie zu verwenden ist jedoch je nach Komplexität, die das Plugin annimmt, durchaus aufwendig – und man schreibt immer den selben Code aufs neue. Ich habe daher bereits vor einigen Jahren damit begonnen für meine eigenen Plugins eine fertige Bibliothek zu verwenden, die alles wichtige für mich übernimmt. Diese steht als Easy Settings for WordPress auch allen anderen Entwicklern zur Verfügung.
register_setting()
WordPress stellt mit register_setting() eine mächte Funktion zur Verfügung, die es dir ermöglicht, Einstellungen für dein Plugin oder Theme im CMS zu registrieren. Dadurch, dass sie registriert wird, kannst du sie wiederum mit weiteren Funktionen im Backend ausgeben lassen.
In der Form registrierte Einstellungen werden in der options-Tabelle gespeichert. Jede Einstellung ist ein Feld und kann, abhängig von ihrer Registrierung, auch nur ein bestimmtes Datenformat annehmen. Möchtest du bspw. ein Häkchenfeld speichern, wird das als Integer-Wert 0 oder 1 gespeichert. Arrays werden generell durch WordPress automatisch serialisiert gespeichert und beim Auslesen automatisch auch wieder umgewandelt.
Was aber, wenn du diese Einstellungswerte vor der Speicherung prüfen willst? Oder sie verschlüsseln und entschlüsseln willst? Oder sie eine Event auslösen sollen?
Hooks sind magisch
Die o.g. Funktion register_setting() bringt lediglich eine Option „sanitize_callback“ mit. Damit kann man den eingegebenen Wert absichern – auch wichtig, aber nicht für alle Fälle anwendbar.
Und genau hier stieß ich auf die Grenzen, die es beim Registrieren von Einstellungen in WordPress gibt. Gleichzeitig ist WordPress jedoch dermaßen flexibel, dass man die Werte für diese Einstellungen auch auf anderem Weg prüfen und sogar anpassen kann. Mit dem Hook pre_update_option_* ist es z.B. möglich einen zu speichernden Wert vor dessen Speicherung nochmals zu prüfen oder auch zu verändern.
Genau das nutzte ich Anfangs für verschiedene Einstellungen aus, meist um diese zu verschlüsseln (ist ein eigenes Thema zu dem es auch einen Blog-Beitrag geben wird :) ). Aber es zeigte mir auch, dass ich immer wieder den gleichen Quellcode schreiben musste, der sich oft nur in den Namen und Beschriftungen der Felder sowie deren Callbacks unterschied.
Easy Settings for WordPress
Als Entwickler versucht man wiederkehrende Codes in Bibliotheken auszulagern, so dass man sie nicht jedes Mal neu schreiben muss. Ich habe daher zunächst damit begonnen, diese wiederkehrenden Zeilen für Einstellungen meiner Plugins zu kapseln. Und das klappte erstaunlich gut. So gut, dass ich daraus eine eigene Bibliothek baute, die auch allen anderen Entwicklern zur Verfügung steht: https://github.com/threadi/easy-settings-for-wordpress
Um sie in ein Projekt einzubinden, ist folgendes notwendig:
- Die Bibliothek muss per composer eingebunden werden:
composer require threadi/easy-settings-for-wordpress - Die zentrale Datei muss einmal instantiiert werden und kann dann sowohl Eigenschaften für das Projekt mitgeben als auch Einstellungen hinterlegen.
Ein sehr grobes und minimales Beispiel:
$settings_obj = easy_settings_for_wordpress_demo_get_settings_object();
$settings_obj->set_slug( 'demo_settings' ); // use a slug to use intern.
$settings_obj->set_menu_title( _x( 'Demo Settings', 'settings menu title', 'easy-settings-for-wordpress-demo' ) ); // set the menu title.
$settings_obj->set_title( __( 'Demo Settings', 'easy-settings-for-wordpress-demo' ) ); // set the settings title.
$settings_obj->set_menu_slug( 'demo-settings' ); // set the menu slug.
$settings_obj->set_menu_parent_slug( 'options-general.php' ); // set where the settings are assigned to, e.g., 'options-general.php' for the WordPress-own settings menu.
// add setting for a Checkbox.
$setting = $settings_obj->add_setting( 'esfw_demo_checkbox' );
$setting->set_type( 'integer' );
$setting->set_default( 0 );
$setting->set_section( $section );
$field = new Checkbox( $settings_obj );
$field->set_title( __( 'Checkbox', 'easy-settings-for-wordpress-demo' ) );
$field->set_description( __( 'This is a checkbox. It could be used to enable or disable things.', 'easy-settings-for-wordpress-demo' ) );
$setting->set_field( $field );
$settings_obj->init();Was hier passiert:
- Die Einstellungs-Bibliothek wird initiiert und mit Einstellungen versehen, u.a. dass diese im WordPress-Backend unter Einstellungen > Demo Settings zu finden sein werden.
- Ein Häkchenfeld mit dem Namen „esfw_demo_checkbox“ wird als Einstellung ergänzt. Es wird inital nicht angehakt.
Die Folge:
- Du wirst in deinem Projekt unter Einstellungen > Demo Settings die Einstellungen finden.
- Dort auch das o.g. Häkchenfeld, welches nicht angehakt ist.
- In der Datenbank wird das Feld bereits reserviert sein, inkl. Markierung für den Autoloader für eine performante Nutzung.
Es gibt inzwischen sehr viele Optionen, die man pro Einstellung setzen kann. Die Bibliothek unterstützt 19 verschiedene Feldtypen, die im Backend angezeigt werden können, darunter auch Passwort, Text und MultiSelect. Viele dieser Feldtypen haben eigene Einstellungen, die meisten sind aber identisch. Jedes Feld kann, muss aber nicht, in der REST API angezeigt werden. Du kannst jegliche Beschriftungen und Beschreibungen individuell setzen – das Plugin gibt keinerlei Angaben selbst vor. Du kannst alle in WordPress möglichen Datentypen für die Felder verwenden, sie werden auf Grund fehlender Datentypen-Prüfungen in WordPress selbst, durch die Bibliothek validiert bevor sie gespeichert werden.
Die Bibliothek kümmert sich für dich zudem um die Installation der Einstellungen bei Aktivierung deines Plugins wie auch die Löschung, wenn dein Plugin gelöscht werden sollte. Du musst sich hierbei nicht mehr um die Bereinigung selbst kümmern, außer, dass du dafür sorgen musst, dass die Bibliothek in dem Moment dafür auch aufgerufen wird. Dadurch bleiben bei Löschung des Plugins wirklich saubere Datenbanken zurück.
Schon wieder ein neues Layout im Backend?
Nein, damit fange ich gar nicht erst an. Es gibt genug Plugins, die das Backend mit verwirrend vielen bunten Farben und Anordnungen durcheinander bringen. Die Bibliothek Easy Settings for WordPress verwendet für die Ausgabe der Einstellungen im Backend das, was das WordPress Backend selbst bereits mitbringt: die Tab-Navigation sowie die Ausgabe der Felder.
Für eine minimale Flexibilität, habe ich in der neuesten Version zumindest noch eine vertikale Ansicht der Tab-Navigation ergänzt. Styling kommt wieder 1:1 von WordPress, nur die Anordnung ist vertikal. Man kann diese Ansicht über eine Einstellung am Haupt-Objekt aktivieren. Es ist natürlich auch möglich eigene Ansichten für Einstellungen zu registrieren und zu verwenden.
Eine Demo
Vor kurzem habe ich dazu auch eine Demo bereitgestellt, so dass man ein praktisches Beispiel hat anhand dessen man die Bibliothek für sich selbst adaptieren kann. Ihr findet sie hier: https://github.com/threadi/easy-settings-for-wordpress-demo – einfach das Release-ZIP runterladen und installieren um zu schauen, wie es wirkt.
Die Bibliothek wird natürlich auch in den meisten meiner Plugins verwendet. Du findest sie z.B. in Download Listen Block mit Icons, Externe Dateien in der Mediathek oder Personio Integration Light.
Die Zukunft?
Ich sehe die Bibliothek lange nicht als das Allheilmittel für jeden. Sie nimmt mir aber enorme Arbeit bei jedem neuen Plugin oder Theme, was ich entwickle, ab. Der Aufwand in der Umsetzung verringert sich für mich erheblich (besser als mit jeder KI – ich hab es schon probiert ;) ).
Für die Zukunft würde ich gerne die Ausgabe noch über die Gutenberg DataForms ermöglichen. Da das aber aus meiner Sicht noch zu unstet und instabil in der Entwicklung ist, bin ich es noch nicht angegangen. Die Struktur der Daten im Plugin sollte es aber ermöglichen, das recht einfach umzusetzen, wenn es dann mal soweit ist, vlt. ja als neuer Style.
Und jetzt Du
Du findest hier alle Informationen um sie zu verwenden: https://github.com/threadi/easy-settings-for-wordpress
Und die Demo ist hier: https://github.com/threadi/easy-settings-for-wordpress-demo
Bei Fragen gerne an mich wenden :)