This article is a quick introduction tutorial to the WordPress Options plugin and how to use its APIs from your own products, regardless of them being either themes or plugins. In a hurry? Jump straight to the code snippet!
Using the plugin is extremely easy and only requires three steps:
- Embedding the plugin files into your own product (optional)
- Creating your options array with all of your settings
- Calling into the plugin’s API to register your settings
So let’s now look into each one of the steps and how to complete them.
Embedding the plugin
This step is not necessary but highly recommended as it allows for options to work out of the box without forcing your users to install an extra plugin. All you have to do is to download the plugin itself and extract it into your main product’s folder.
At this point all you have to do is simply include the file
synved-options/synved-wp-options.php from either the
functions.php in your theme or the main file within your plugin. Don’t worry about checking if the plugin was already loaded or included. Just include
synved-options/synved-wp-options.php, everything else will be handled automatically by the plugin!
Creating the options
This step is very easy. Just create an array that contains all of your options. The framework is quite flexible in that the amount of required parameters to get a functional options page is very minimal and the array will just become as complex as you want it to be, depending on your needs.
A simple example of a minimal options array that creates 3 options is the following:
$test_options = array( 'show_tips' => array( 'default' => false, 'label' => __('Show Tips', 'my-test') ), 'background_image' => array( 'type' => 'image', 'label' => __('Background Image', 'my-test') ), 'header_logo_image' => array( 'type' => 'image', 'label' => __('Logo Image', 'my-test'), 'tip' => __('Maximum size is 1024x150 pixels', 'my-test') ) );
As you can see the format for creating options is very simple and clear. All you do is add an extra element in the array for every option you want to create, together with info on the type of the option as well as a label that describes the option and a tip that gives further information.
Note: this is just the absolute simplest example snippet that you can get but you can go much more complex than this and specify many more parameters as well as creating nested options sections and place them in pages anywhere you want in the WordPress admin menu.
Registering the options
This last step is absolutely the simplest in the whole process. All you have to do is to call a specific API function
synved_option_register and pass in a unique ID as well as the options array created in the above step. Like this:
Once you make this function call you will see a new page under the WordPress Settings tab, called “My Test” and when you open the page you will see something very similar to when you open a built-in WordPress settings page, with an options section called “General Settings”.
All of this, including page name and title as well as section name can be customized easily by slightly adjusting the options array. More on that on a future tutorial. Alternatively you can download our free theme Stripefolio and look into its
functions.php file for a more complete example.
Here’s all of the above code in one single easy to copy snippet:
$test_options = array( 'show_tips' => array( 'default' => false, 'label' => __('Show Tips', 'my-test') ), 'background_image' => array( 'type' => 'image', 'label' => __('Background Image', 'my-test') ), 'header_logo_image' => array( 'type' => 'image', 'label' => __('Logo Image', 'my-test'), 'tip' => __('Maximum size is 1024x150 pixels', 'my-test') ) ); synved_option_register('my_test', $test_options);
Getting the options
Retrieving the values for the options is now very easy. All you have to do is call the API function
synved_option_get with the id you used to register the options in the call to
synved_option_register and the name of the option. For instance to retrieve the value for the
background_image option above you would use this code:
$background_image = synved_option_get('my_test', 'background_image');
This is just an introductory tutorial, you can now go on and check part 2 of this introductory tutorial with more complex examples exposing some of the advanced features that WordPress Options provides.