In Version 3 we added the ability to manage your theme’s custom settings in a standalone page. This page loads a React app that manages your theme settings for you. Furthermore, there is no need to alter the actual React code to manage the settings and fields (unless you want more specific control over the app). Additionally, this React app auto-saves user input as they interact with the app, so no need to hit an actual Save or Update button. It monitors user interaction and auto-saves all settings 2-3 seconds after a change to any field.
The default React app comes designed to rely on a JSON object that dictates the settings IDs, field types, and more. This means that you DO NOT need to know React to work with this new settings page, you only need to understand the JSON structure. You can find the JSON file in /assets/js/src/admin/settingsFields.json.
{
"tabs": [
{
"id": "tab1",
"tabControl": {
"label": "Page 1"
},
"tabContent": {
"fields": [
{
"name": "option1",
"label": "Option 1",
"type": "text"
},
{
"name": "option2",
"label": "Option 2",
"type": "text"
},
{
"name": "option7",
"label": "Robs Custom Setting",
"type": "text"
},
{
"name": "option8",
"label": "Robs Now with Gulp?",
"type": "text"
},
{
"name": "option5",
"label": "On/Off",
"type": "toggle"
},
{
"name": "option9",
"label": "Live/Die",
"type": "toggle"
}
]
}
},
{
"id": "tab2",
"tabControl": {
"label": "Page 2"
},
"tabContent": {
"fields": [
{
"name": "option3",
"label": "Option 3",
"type": "email"
},
{
"name": "option4",
"label": "Option 4",
"type": "url"
},
{
"name": "option6",
"label": "Select one",
"type": "select",
"options": [
{
"label": "Option 1",
"value": "option-1"
},
{
"label": "Option 2",
"value": "option-2"
}
]
}
]
}
}
]
}
You will notice that the default JSON structure allows you to organize your settings into various tabs for various purposes. Currently, the available field types are limited to:
- Text (string, number, password, email, url, and other value types supported)
- Toggle (enable/disable settings with Boolean values)
- Select dropdown
We anticipate adding support for more field types in later versions.
Reading the JSON structure above is fairly self-explanatory. The most important points here are that the “name” for each field must be unique and is the array index string of the value.
Note: The dev node server must be running (or a build is required after each change) while changes are being made to this JSON file in order for updates to be seen in the settings page, as the JSON file gets imported into the app.
Getting saved values
All values are stored in one array that can be accessed using the standard get_option() function in wordpress and use your theme’s name at the beginning of the option name as so: “{your_custom_theme}_theme_settings”.
Example
// The name of the theme in this example is simply "Example"
$settings = get_option('example_theme_settings');Customizing the settings page
You can customize the settings page to your liking either using PHP (to add content above or below the settings app) or if you are comfortable with React, you can completely customize the app itself, as the build for the app is built right into the regular WP Rig build process. This means that you can add custom settings components like more specific fields types, input mechanisms, or other content.
If you want to remove this settings page to rely on an alternate means of managing your theme’s settings, you can simply disable or remove the Options component in the /inc directory of the theme. If you only want to disable it, then you can find where the component is instantiated towards the bottom of the Theme.php file in the /inc folder and just remove the line new Options\Component(),
