Introduction to using WordPress Options, part 1

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:

  1. Embedding the plugin files into your own product (optional)
  2. Creating your options array with all of your settings
  3. 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.

facebooktwittergoogle_plusredditpinterestlinkedinmail
Posted In: Tutorials Tags: , , , , ,

22 Comments

  1. Posted October 16, 2012 at 6:31 pm | Permalink

    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!

    • elia
      Posted October 16, 2012 at 9:06 pm | Permalink

      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.

  2. Ethan
    Posted October 17, 2012 at 7:20 pm | Permalink

    How do I retrieve the options in my theme?

    get_option(‘option_name’);

    doesnt seem to work?

    • Ethan
      Posted October 17, 2012 at 7:26 pm | Permalink

      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.

  3. elia
    Posted October 17, 2012 at 7:26 pm | Permalink

    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.

    • Ethan
      Posted October 17, 2012 at 7:28 pm | Permalink

      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..

      • elia
        Posted October 17, 2012 at 7:34 pm | Permalink

        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.

        • Ethan
          Posted October 17, 2012 at 7:37 pm | Permalink

          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?

          • elia
            Posted October 17, 2012 at 7:48 pm | Permalink

            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!

  4. Ethan
    Posted October 18, 2012 at 4:20 am | Permalink

    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…

    • elia
      Posted October 18, 2012 at 12:57 pm | Permalink

      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.

      • Ethan
        Posted October 19, 2012 at 12:44 am | Permalink

        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!

        • elia
          Posted October 19, 2012 at 12:58 am | Permalink

          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 ;)

  5. Ethan
    Posted October 19, 2012 at 1:37 am | Permalink

    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

    • elia
      Posted October 19, 2012 at 2:15 am | Permalink

      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.

      • Ethan
        Posted October 19, 2012 at 3:02 am | Permalink

        No docs, so im stuck… ;)

        • elia
          Posted October 19, 2012 at 11:15 am | Permalink

          Yeah I know I’ll try document that as well if I get the time.

        • elia
          Posted October 22, 2012 at 2:43 am | Permalink

          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-option folder from there to the WordPress Options plugin main folder and replace any files.

  6. Ethan
    Posted October 19, 2012 at 5:14 am | Permalink

    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…

    • elia
      Posted October 19, 2012 at 11:20 am | Permalink

      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 :\

  7. S
    Posted January 15, 2014 at 12:42 pm | Permalink

    Thanks for your plug-in

    It’s work great, I have only 1 problem.

    I need to specify different role like “create_users”.
    The admin can manage the new option, the users with “create_users” role can edit the options but can’t save, they see “Cheatin uh?”

    how to solve this?

    Tnx

    • elia
      Posted January 15, 2014 at 2:04 pm | Permalink

      You can specify a “role” property in the settings array and set it to “create_users”.

Post a Comment

Your email is never published nor shared. Required fields are marked *

*
*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>