DataViews sind in WordPress ein fantastischer Weg für Entwickler, um Einstellungen an ihren Plugins und Themes in WordPress zu ermöglichen. Es ist so neu, dass es bisher nur wenige Anwendungen gibt, die sie tatsächlich aktiv einsetzen. Ein Grund kann sein, dass es sich um React-basierte Komponenten handelt, die nicht für jeden Entwickler einfach zu verwenden ist. Mein composer Package Easy Settings for WordPress bietet seit kurzem die Möglichkeit genau hier einen einfacheren Weg zu gehen und DataViews dennoch aktiv zu verwenden. Lest hier wie man mit einer JSON-Datei eine DataView-Ansicht verwalten kann.
English version is here: https://medium.com/@tzwirner/defining-dataviews-using-json-44fb84c1d9b5
Hintergrund
Das von mir erstelle composer Package Easy Settings for WordPress entstand im Rahmen der Entwicklung meiner eigenen Plugins. Ich wollte nicht immer wieder den gleichen Code schreiben um Einstellungen an diesen zu ergänzen. Stattdessen habe ich ein Package entwickelt dem ich lediglich sagen muss, was es für Einstellungen geben soll und es kümmert sich letztlich um alles andere.
Um Einstellungen auszulesen, nutzt man einfach das WordPress-eigene get_option(). Auch hier kümmert sich mein Package darum, dass der richtige Datentyp zurückgegeben wird.
DataViews
Im Rahmen der Entwicklung von Gutenberg für WordPress durch die Community, entstanden zahlreiche visuelle Komponenten um Einstellungen für die Ein- und Ausgabe von Inhalten vorzunehmen. DataViews entwickelten sich genau hieraus. Es entstand ein eigenes Package um Einstellungen nicht für Inhalte sondern für Plugins und Themes vornehmen zu können.
Ich möchte hier ungern ein weiteres Mal beschreiben, wie man mit DataViews umgehen kann. Dafür gibt es bereits wunderbare Anleitungen wie diese hier: https://developer.wordpress.org/news/2024/08/using-data-views-to-display-and-interact-with-data-in-plugins/
Auch die DataViews entwickeln sich weiter – selbst heute, denn auch im kommenden WordPress 7.1 wird es Ergänzungen hieran geben. Dennoch sind sie aus meiner Sicht bereits stabil genug um sie für Plugins und Themes einsetzen zu können.
Wichtig: hier geht es um Einstellungsmöglichkeiten für Plugins mit DataViews. Es geht hier nicht um die Ausgabe von Datensätzen von Custom Post Types oder ähnlichem mit Dataviews, was natürlich ebenfalls möglich ist.
Einfachheit
Wie man u.a. an o.g. Anleitung sehen kann, ist die Implementierung von DataViews doch recht komplex. Man muss zahlreiche Daten hinterlegen um überhaupt eine Ausgabe zu bekommen. Darunter sind Angaben zu den anzuzeigenden Daten, den anzuzeigenden Feldern für die Daten und wie diese angeordnet werden sollen.
Mein composer Package Easy Settings for WordPress bot bisher die klassische Ansicht für Einstellungen an (mit der Tab-Navigation oben oder links), die WordPress seit Jahrzehnten mitbringt. Die API des Packages zielt genau darauf ab und ist dennoch allgemein genug gehalten um DataViews als zusätzlichen View mit anbieten zu können.
Dadurch entstanden zahlreiche Kombinationsmöglichkeiten, wie man die eigenen Einstellungen hinterlegen kann:
| Classic | DataView | |
| PHP | X | X |
| JSON | X | X |
Für den Weg per PHP gibt es hier eine Anleitung: https://github.com/threadi/easy-settings-for-wordpress/blob/master/docs/how_to_use_with_php.md
JSON als Basis
Um ein einheitliches JSON-Format zu ermöglichen, habe ich ein JSON-Schema entworfen. Dieses ist hier abrufbar: https://raw.githubusercontent.com/threadi/easy-settings-for-wordpress/refs/heads/master/settings.schema.json – dieses definiert, welche Felder für welche Angaben in der JSON zuständig sind.
Eine einfache JSON sähe z.B. so aus:
{
"$schema": "https://raw.githubusercontent.com/threadi/easy-settings-for-wordpress/refs/heads/master/settings.schema.json",
"slug": "presentation",
"title": "Presentation Settings",
"menu_title": "Presentation Settings",
"menu_slug": "presentation-settings",
"capability": "manage_options",
"default_tab": "presentation_general",
"view": "dataview",
"tabs": [
{
"name": "presentation_general",
"title": "General",
"sections": [
{
"name": "basics",
"title": "Basics",
"settings": [
{
"name": "my_name",
"type": "string",
"default": "",
"field": { "type": "Text", "title": "Name", "placeholder": "Enter your name" }
}
]
}
]
}
]
}
Aber gehen wir das der Reihe nach durch.
Plugin vorbereiten
Erstelle zunächst dein Plugin, welches du mit den Einstellungen versehen willst. Eine einfache PHP-Datei reicht schon dafür aus.
<?php
/**
* Plugin Name: Mein Plugin
* Description: Testplugin
* Author: Mein Name
* License: GPL v3
* License URI: https://www.gnu.org/licenses/gpl-3.0.en.html
* Version: 1.0.0
* Requires PHP: 8.2
*
* @package my-plugin-slig
*/JSON erstellen
Erstelle dann deine JSON-Datei, die die Einstellungen definieren soll. Nimm gerne o.g. Beispiel als Basis. Ein anderes Beispiel findest du hier: https://raw.githubusercontent.com/threadi/easy-settings-for-wordpress/refs/heads/master/docs/example.json
Easy Settings for WordPress installieren
Installiere nun per composer das Package:
composer require threadi/easy-settings-for-wordpressStell sicher, dass du composer wirklich einbindest:
require __DIR__ . '/vendor/autoload.php';Alles vermengen
Jetzt der entscheidende Schritt: binde Easy Settings for WordPress in dein Plugin ein und referenziere in dessen Einstellungen auf deine JSON.
function your_custom_init_for_settings(): void {
$settings_object = new Settings( __FILE__ );
$settings_object->set_json_by_path( ABSPATH . '/wp-content/plugins/your-plugin/settings_schema.json' );
$settings_object->init();
}
add_action( 'init', 'your_custom_init_for_settings' );Achte hier auf den Pfad bei set_json_by_path(). Dieser muss exakt der absolute Pfad zu der von dir vorbereiteten JSON-Datei innerhalb deines Plugin-Verzeichnisses sein.
Das Ergebnis
Sobald du dein Plugin aktivierst, wirst du unter Einstellungen einen neuen Menüpunkt namens „Presentation Settings“ sehen. Klick diesen an um die Einstellungen aus deiner JSON in einer DataView-Ansicht zu sehen.
Geht nicht?
Prüfe folgendes:
- Hast du composer eingebunden, wie oben beschrieben?
- Ist der Pfad bei
set_json_by_path()der richtige? - Ist die JSON-Datei auch unter diesem Pfad zu finden?
- Hast du in deiner JSON ggfs. die Angaben für die Position der Einstellungen oder dere Slug geändert? Schau nach diesen Angaben in deinem Backend.
Wie weiter?
Der Wert aus dem einen Feld kannst du einfach per
echo wp_kses_post( get_option( 'my_name' ) );auslesen. Da es ein Text-Feld ist, muss man nichts weiter beachten – das Package kümmert sich bereits um jegliche Absicherung für dich. Die Verwendung von wp_kses_post() würde ich jedoch empfehlen, um die Kompatibilität mit den WordPress Coding Standards hinsichtlich der Ausgabe von Texten zu erfüllen.
Ergänze nun in der JSON-Datei die weiteren von dir für dein Plugin oder Theme benötigten Felder. Welche zur Verfügung stehen, kannst du im JSON-Schema oder in der Dokumentation hier einsehen: https://github.com/threadi/easy-settings-for-wordpress/blob/master/docs/fields.md
Auch ist es möglich weitere Tabs zu erstellen, um so die Einstellungen auf mehrere einzelne Ansichten aufzuteilen. Schau dir zum Aufbau einfach das Beispiel an: https://github.com/threadi/easy-settings-for-wordpress/blob/master/docs/example.json
Denk auch dran bei Deinstallation deines Plugins die Einstellungen löschen zu lassen. Rufe dazu in der uninstall.php deines Plugins die Funktion delete_settings() vom Settings-Object auf. Das Package kümmert sich, wenn so aufgerufen, um alles andere. Ein Beispiel dafür findest du in der Demo zu dem Package: https://github.com/threadi/easy-settings-for-wordpress-demo/blob/master/uninstall.php
Einschränkungen
Man muss ehrlich sein, denn sowohl die Verwendung von JSON als auch von DataViews unterliegt derzeit noch einigen Einschränkungen.
JSON-Grenzen
Mehrsprachigkeit ist mit dieser Methode derzeit nur auf einem Umweg möglich. Du müsstest pro Sprache eine eigene JSON anlegen. Diese darf sich nur in den Bezeichnungen und nicht in den Einstellungen unterscheiden. Du musst bei set_json_by_path() dann die jeweils sprachspezifische JSON laden.
DataViews-Grenzen
Nicht alle vom composer Package unterstützen Felder sind derzeit in DataViews umsetzbar. Dabei geht es jedoch um wirklich Spezialanwendungen, die man vermutlich nicht oft benötigt:
- FieldTable
- MultiField
- Table
Alle anderen Felder sind problemlos nutzbar, wie man in der Demo auch sehen kann.
Fazit
Mit der Verwendung von JSON zur Definition von Einstellungen für individuelle Plugins und Themes, spart man sich viel Arbeit in der Entwickung. Zudem muss man sich nicht um die Programmierung der DataView-Ansichten kümmern. Es kann für jeden Entwickler ein Mehrwert sein.