Ever wanted an easier way to add settings to your WordPress plugin? Whether you're an experienced developer looking to speed up your workflow or a new developer overwhelmed by the Settings API, I'm happy to share a handy bit of code I've written to simplify the process of saving, retrieving, and displaying a settings page.
Including the Class
First, grab a copy of Refactored Settings on GitHub. If you're unfamiliar Git, just choose "Download ZIP" and extract the files. Next you'll need to create a new folder named php/ in your plugin's directory. So if your plugin is in wp-content/plugins/awesome-plugin/, you'll now have wp-content/plugins/awesome-plugin/php/. Now copy the class-refactored-settings.php file we downloaded into this folder.
Now that we have the settings class in place, we can start to incorporate it into our plugin. Don't worry if you're unfamiliar with classes, for now just know that it's a collection of variables and functions.
Open up your plugin's main file and before any of your functions add this line:
require_once( dirname(__FILE__) . '/php/class-refactored-settings.php' );
This will load the code for our settings class. Now we need to open the class-refactored-settings.php file to take a quick look at the class name we'll be using. Near the beginning of the file you'll see a line like this:
class Refactored_Settings_0_2 {
This means the name of our class is RefactoredSettings02. The "02" in this example is a version number for the class, which ensures plugins will be compatible with each other even if they're written using different versions of this class.
Configure the Settings Arguments
Now we need to configure our settings. Open up your main plugin file and after the requireonce() line we added, create an array named $settingsargs. If you want to quickly see how everything works you can copy and paste the one below, or you can scan through it to get an understanding of how to define your settings.
$settings_args = array(
'file' => __FILE__, // Plugin file (used to add/remove settings on activation/deactivation)
'version' => '0.1', // Plugin version
'name' => 'Refactored Settings Example Plugin', // The name of the plugin
'slug' => 'refactored_settings_example', // The slug to reference and store settings
// An array of option sections
'options' => array(
// An option section array ("general" is the slug for this section)
'general' => array(
'name' => 'General Settings', // The name to display for this settings section
'description' => 'These settings are general.', // A description to display
// An array of fields to display in this section
'fields' => array(
// A settings field array
'color' => array(
'name' => 'Color', // The display name
'type' => 'text', // The type of input
'default' => '', // The default value
'description' => 'Your favorite color' // A description
),
// A settings field array
'milkshake' => array(
'name' => 'Milkshake', // The display name
'type' => 'checkbox', // The type of input
'default' => '1', // The default value
'description' => 'Would you like a milkshake with that?' // A description
)
)
),
// An option section array ("advanced" is the slug for this section)
'advanced' => array(
'name' => 'Advanced Settings', // The name to display for this settings section
'description' => 'The settings are advanced.', // A description to display
// An array of fields to display in this section
'fields' => array(
// A settings field array
'candy' => array(
'name' => 'Candy', // The display name
'type' => 'dropdown', // The type of input
'default' => 'mms', // The default value
// An array of options with values and display names
'options' => array(
'gummy-bears' => 'Gummy Bears',
'skittles' => 'Skittles',
'mms' => 'M&Ms'
),
'description' => 'Your favorite candy' // A description
),
// A settings field array
'pizza' => array(
'name' => 'Pizza Toppings', // The display name
'type' => 'multicheckbox', // The type of input
// Because multiple checkboxes will have multiple values, the default is an array
'default' => array(
'pepperoni'
),
// An array of options with values and display names
'options' => array(
'extracheese' => 'Extra Cheese',
'pepperoni' => 'Pepperoni',
'sausage' => 'Sausage',
'mushroom' => 'Mushroom'
),
'description' => 'Select your favorite pizza toppings' // A description
),
// A settings field array
'drink' => array(
'name' => 'Drink', // The display name
'type' => 'radio', // The type of input
'default' => 'coke', // The default value
// An array of options with values and display names
'options' => array(
'coke' => 'Coke',
'dr-pepper' => 'Dr. Pepper',
'sprite' => 'Sprite'
),
'description' => 'What would you like to drink?' // A description
)
)
)
)
);
Create an Instance
Now that we have our settings arguments, it's time to create our Refactored Settings instance. Take the class name we found earlier and add this line:
$my_awesome_settings = new Refactored_Settings_0_2( $settings_args );
Be sure to replace the RefactoredSettings0_2 with whichever version of the settings class you're using. At this point you should be able to see your new settings page in the dashboard, but we haven't incorporated any of the settings into our plugin.
Using the Settings
To use a setting in your plugin, you can use $myawesomesettings like so:
echo $my_awesome_settings->options['general']['color'];
If you're accessing $myawesomesettings from within a function, be sure to include it as a global:
function my_plugin_function() {
global $my_awesome_settings;
// Now you can access your settings
// ...
}
Conclusion
Hopefully you've found this class helpful, let me know if you have any questions. Be sure to watch Refactored Settings on GitHub for updates and feel free to create an issue or submit a pull request!