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:
synved_option_register('my_test', $test_options);
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.
The complete code snippet
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');
Conclusions
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.
20 Comments
Just ran across this site and your WordPress Options might just be what I need. I need an Option Block on the Page Edit page that will have a list of about 100 URL sites that can be chosen to appear as links on that page. Also, there would be a way to set the order of those items chosen.
If you can let me know if I’m in the ball park by looking at your plugin – it would be much appreciated.
Thanks!
Unfortunately at the moment the plugin only allows adding options to settings pages in WordPress and not on posts/pages but it is a planned feature and high on the priority list so it will likely be added to the next release as soon as there is the time.
How do I retrieve the options in my theme?
get_option(‘option_name’);
doesnt seem to work?
OK, I searched the code and figured it out, in case anyone else is having trouble due to lack of documentation:
synved_option_get(‘group_name’, ‘option_name’);
will return the value.
For example, using the code in the post above, to get the header_logo_image:
echo synved_option_get(‘my_test’, ‘header_logo_image’);
//will print the image url.
You have to use synved_option_get(‘id’, ‘name’)
I realize the documentation on this plugin is still scarce. What you can do is download our other plugin WordPress Shortcodes or the Stripefolio theme and search for “synved_option_” in their files and you can get a better idea on the available APIs for the plugin itself.
Thanks! I just figured it out at the same time.
Can you provide an example of how the tips, sections and pages work? I cant seem to understand from the functions.php in the theme..
The sections, pages and tips are all interface-related.
You create an “options-page” options to create a specific page in the WordPress backend pages/settings and you can use the “parent” attribute to place it anywhere you want.
An “options-section” type instead defines a single section with a title in the page.
Tips are just shown as descriptions for individual options, in a paragraph underneath sections or as global descriptions in the settings pages you create.
Can you provide a simple example of the array to create a new page in the “Appearance” admin section of wordpress?
Also, can you provide a simple example of the array to create two sections on a settings page?
What are the array keys/structure needed?
Thanks for your help and good work!! I want to add a tooltip icon for the tips, I will try to submit some code to you over the next few days. Do you have a github?
We use BitBucket but the code is still not published on the repository mostly for lack of time. If you have any suggestions or patches you can add them here:
https://bitbucket.org/synved/wordpress-options/
I will try update this tutorial with a more advanced example using custom pages and sections hopefully in the next 3-4 hours. Stay tuned!
Hi,
Any progress on the tutorial? I am also having trouble with the ‘category’ type and I dont see an example. I assumed it would let me select from the active category list…
I apologize for the delay but I’m swamped these days. Would you mind waiting until the weekend? If it’s really urgent I can try and put something together today.
By the way if you paste the ‘category’ type option snippet I can tell if there’s anything wrong.
Hi Elia,
Thanks for you help on categories. I figured out the problem the categories were all empty at the time, so they didnt appear in your dropdown until I added some new posts… I think it should probably always show all the categories, so I leave it up to you to decide if its a bug.. :)
Thanks for your help, I am excited to see the documentation, this is a very good module, and I am looking forward to helping you!
Yes that is a problem with the WordPress APIs not returning empty categories by default, I will look into adding an option to ignore that behavior.
Thanks for the patience. I will try put something together this weekend ;)
Here is my first contrib/hack… Pure CSS tooltips on hover.
I made two changes to your files:
1) I added to the end of synved-option/style/admin.css
http://pastebin.com/uHG1Y5Gp
2) Changed the $out at the end of synved-option/synved-option-render.php
http://pastebin.com/JkiZ8Und
You know you don’t have to modify the plugin’s code to achieve this effect, you can simply use callbacks ;)
The UI for the options created by the plugin is structured in a way as to match WordPress built-in display of settings to make everything look fully integrated.
You could use a single callback and a custom enqueued CSS to easily achieve the effect there. The callback mechanism is probably worth a whole tutorial on its own.
In the future I also intend to add easier ways to customize the look of your options, including displaying sections in tabs/accordions etc.
No docs, so im stuck… ;)
Yeah I know I’ll try document that as well if I get the time.
Ok so I was able to piece together another tutorial, here:
http://synved.com/blog/help/tutorials/introduction-to-using-wordpress-options-part-2/
There’s quite a bit of information there on many aspects of the framework. I’m not sure if the package for the WordPress Options plugin is up to date to match that tutorial. I will update it as soon as I have the time next week.
In case things in the examples don’t work you download the WordPress Shortcodes plugin and simply copy and paste the
synved-optionfolder from there to the WordPress Options plugin main folder and replace any files.I have a request for a “gallery” type maybe we can select gallery from a post?
Or maybe even “nextgen-gallery” type?
What do you think?
Also, I dont think WP Admin has native tooltips, I havent seen it…
No WordPress doesn’t show tooltips but uses the grey description span tag, which is why the plugin shows the tip that way.
My intention for the future of the plugin is to add “context” so you can attach the list of options to any data, like posts. I’d also like to allow people to add their own custom option types so they can display all sort of options,, including the ones you mention. The only problem right now is lack of time :\