Defining DataViews using JSON
In WordPress, DataViews offer developers a fantastic way to implement settings for their plugins and themes. The feature is so new that few applications are actively using it so far. One reason may be that they are React-based components, which are not necessarily easy for every developer to work with. My Composer package, “Easy Settings for WordPress,” recently introduced a way to simplify this process while still actively utilizing DataViews. Read on to learn how to manage a DataView using a JSON file.
Background
I created the Composer package “Easy Settings for WordPress” while developing my own plugins. I didn’t want to keep writing the same code over and over to add settings to them. Instead, I developed a package where I simply specify the desired settings, and it handles everything else.
To retrieve settings, you simply use WordPress’s built-in `get_option()`. Here, too, my package ensures that the correct data type is returned.
DataViews
As the community developed Gutenberg for WordPress, numerous visual components emerged for managing content input and output settings. DataViews evolved directly from this context; a dedicated package was created to handle settings not just for content, but for plugins and themes as well.
I do not wish to repeat the details of how to work with DataViews here. There are already excellent guides available, such as this one: https://developer.wordpress.org/news/2024/08/using-data-views-to-display-and-interact-with-data-in-plugins/
DataViews continue to evolve — even now, with further enhancements planned for the upcoming WordPress 7.1 release. Nevertheless, in my view, they are already stable enough for use in plugins and themes.
Important: This discussion focuses on using DataViews for plugin settings. It does not cover displaying datasets from Custom Post Types or similar entities using DataViews - though that is, of course, also possible.
Simplicity
As the aforementioned guide demonstrates, implementing DataViews is actually quite complex. You have to provide a significant amount of data just to generate any output at all — including details on the data to be displayed, the specific fields to show, and how they should be arranged.
My Composer package, “Easy Settings for WordPress,” previously offered only the classic settings view — featuring the tabbed navigation (positioned at the top or side) that has been a staple of WordPress for decades. While the package’s API is designed specifically for that standard layout, it remains flexible enough to also support DataViews as an additional view option.
You can find instructions for the PHP method here: https://github.com/threadi/easy-settings-for-wordpress/blob/master/docs/how_to_use_with_php.md
JSON as a basis
To ensure a consistent JSON format, I have designed a JSON schema. It is available here: https://raw.githubusercontent.com/threadi/easy-settings-for-wordpress/refs/heads/master/settings.schema.json — this defines which fields correspond to which data within the JSON.
Get Thomas Zwirner’s stories in your inbox
Join Medium for free to get updates from this writer.
A simple JSON example would look like this:
{
"$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" }
}
]
}
]
}
]
}But let’s go through this step by step.
Prepare plugin
First, create the plugin to which you want to add settings. A simple PHP file is sufficient for this.
<?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
*/Create JSON
Next, create the JSON file that will define the settings. Feel free to use the example mentioned above as a starting point. You can find another example here: https://raw.githubusercontent.com/threadi/easy-settings-for-wordpress/refs/heads/master/docs/example.json
Install Easy Settings for WordPress
Now, install the package using Composer:
composer require threadi/easy-settings-for-wordpressMake sure you actually include Composer:
require __DIR__ . '/vendor/autoload.php';Mix everything together
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' );Pay attention to the path used in `set_json_by_path()` here. It must be the exact absolute path to the JSON file you prepared within your plugin directory.
The result
As soon as you activate your plugin, you will see a new menu item called “Presentation Settings” under Settings. Click on it to view the settings from your JSON in a DataView.
Still not working?
Check the following:
- Have you included Composer as described above?
- Is the path in `set_json_by_path()` correct?
- Is the JSON file located at this path?Have you changed the settings location or slug in your JSON file? Check your backend for these details.
What’s next?
You can simply retrieve the value from one field using
echo wp_kses_post( get_option( 'my_name' ) );Since it is a text field, no further action is required — the package already handles all necessary security measures for you. However, I would recommend using `wp_kses_post()` to ensure compliance with WordPress coding standards regarding text output.
Now, add any additional fields required for your plugin or theme to the JSON file. You can view the available options in the JSON schema or the documentation here: https://github.com/threadi/easy-settings-for-wordpress/blob/master/docs/fields.md
You can also create additional tabs to organize settings across multiple views. Simply refer to the example to see how this is structured: https://github.com/threadi/easy-settings-for-wordpress/blob/master/docs/example.json
Also, remember to delete the settings when your plugin is uninstalled. To do this, call the `delete_settings()` function from the settings object within your plugin’s `uninstall.php` file. When called this way, the package handles everything else. You can find an example of this in the package’s demo: https://github.com/threadi/easy-settings-for-wordpress-demo/blob/master/uninstall.php
Limitations
To be fair, both the use of JSON and DataViews is currently subject to certain limitations.
JSON Limitations
Supporting multiple languages with this method currently requires a workaround. You would need to create a separate JSON file for each language. These files must differ only in their labels, not in their settings. You then need to load the specific JSON file for the relevant language when calling `set_json_by_path()`.
DataView Limitations
Not all field types supported by the composer package can currently be implemented using DataViews. However, this applies only to highly specialized use cases that are unlikely to be needed frequently:
- FieldTable
- MultiField
- Table
All other field types can be used without issues, as demonstrated in the demo.
Conclusion
Using JSON to define settings for custom plugins and themes saves a significant amount of development effort. Furthermore, there is no need to handle the programming of DataView views. This approach offers added value for any developer.
