This tutorial aims to put the options made available by jQuery plugin developers to WordPress Administrators.

Building WordPress themes is a craft in itself, it's an additional layer to a Web Designers job. Indeed it is also true, getting the basics from the CMS (title, the_content, the_excerpt etc) means you are a WordPress Theme Developer.

If you build WordPress themes it can become routine to open theme files in your code editor and make changes, however that may involve having access to your work machine and site files for the quickest outcomes.

Allowing configuration of jQuery plugin settings in wp-admin, just makes sense in my World. Much like offering customisation of theme logos and page headers.

This tutorial will utilise the Options Framework by WPTheming to create a theme options page. The options page will present any available settings (within the jQuery plugin) we make available.

Whilst for this example, 3 plugins have been selected namely Tooltipsy, Sea of Clouds (Twitter) and FlexSlider by WooThemes these could be any plugins you use most.

Coupled with WordPress it would be as simple as incorporating a few snippets and files in future themes you develop to have a reasonably granular level of configuration with jQuery powered elements.

Tutorial Details

• Program: WordPress
• Version (if applicable): n/a
• Difficulty: Beginner
• Estimated Completion Time: 30 mins to 1 hour

Terminology

• Plugin - This refers to a jQuery plugin and not WordPress
• Settings - This refers to possible configurations made available by the jQuery plugin Author. e.g. Twitter username.
• Options - These are options we create using the Options Framework.

Downloads

• Options Framework
• Sea of Clouds - Twitter
• Tooltipsy
• FlexSlider

Documentation provided by corresponding Authors

• Options Framework
• Sea of Clouds - Twitter
• Tooltipsy
• FlexSlider

Step 1 Theme directory and file structure

Let's go ahead and create the bare bones of our theme. The files required for this tutorial are listed below.

• footer.php
• functions.php
• header.php
• index.php
• sidebar.php
• style.css
• inc/register.scripts.php
• inc/options.tooltipsy.php
• inc/options.tweets.php
• inc/options.flexslider.php
• inc/js/jquery.flexslider.js
• inc/js/jquery.tooltipsy.js
• inc/js/jquery.tweet.js
• jquery (Ships with WordPress)
• inc/img/array of sample images *1
• inc/options-framework/ *2

*1 - Denotes sample images used for this tutorial as seen within Twenty Eleven.
*2 - Denotes files within the Options Framework.

Step 2 Theme markup

header.php

We are going to register 3 jQuery plugin files later with WordPress wp_footer(); is required for the output.

Between script tags we will initialise the plugins with any additional settings.

sidebar.php

Line 3 - A div with class of "tweets" is required for the Tweets plugin to function.

index.php

Finally we use index.php to bring our files together to have an all-be-it very basic but functional theme.

• Line 1 - We use get_header();.
• Line 3 - We use "The WordPress Loop".
• Line 10 - We use get_sidebar();.
• Line 11 - We use get_footer();.

The above lines should be super familiar to Theme Developers, if you don't know anything about these good luck with your journey. WordPress is the man!

Step 3 Style

style.css

Styles above have been created to position the header, sidebar and main content areas on the page.

Lines 2, 3, 4 and 5 tells WordPress about our theme.

Some styles for FlexSlider. Very minimal.

In keeping with bare minimum styling for the Twitter stream.

Finally, the tooltip style.

Checkpoint and what's next

To this point we have brought together a very basic WordPress theme to illustrate proof of concept with the 3 jQuery plugins chosen.

Next we will include jQuery plugins with WordPress conventions to reap the benefits this can bring, such as GZipping and Caching of scripts (if you have suitable plugins installed along-side).

Furthermore we will set-up the Options Framework to work with the theme by utilising functions.php. 3 arrays will be created to hold any settings each plugin ships with that we chose to make available (e.g. Callback functions are something that may possibly be best served within theme files and not generated dynamically, unless you wish to write jQuery within wp-admin!).

These arrays will be iterated over in conjunction with the Options Framework conventions to bring any plugin settings to the theme options page.

Step 4 /inc/register.scripts.php

• Line 2 - We use is_admin(); to check wether we are within the wp-admin dashboard.
• Line 3 - We create "$js_path" as a helper to point to the locations of any scripts.
• Line 4 - We use wp_register_script(); to notify WordPress of the script name, its path, dependencies (jQuery is passed here and wp_head() will be used to output), version and wether to use wp_footer as the hook or not.
• Line 5 - We use wp_enqueue_script(); to add the previously registered script to any WordPress output.
• Line 12 - We use add_action(); to attach all scripts to WordPress at runtime, using the function previously created.

Step 5 functions.php

Let's make sure we include the scripts registered in the previous step with our theme within functions.php.

The piece of code above ships with the Options Framework, since we've organised our theme a little differently take note of lines 2 and 3 where we modify the paths slightly.

If you look at the documentation for FlexSlider you'll notice the possible settings available, this is our reference when creating the PHP $flexslider_options array.

Step 6 Plugin Settings to Options Framework Option

Let's take all the options that could reside in the Theme Options page and place them within a PHP multi-dimensional array.

Now let's take a look at some of the settings available to the Twitter plugin.

As a PHP array using the same conventions as we did with $flexslider_options.

Finally the Tooltip settings available.

... and as a PHP array using the same conventions we get...

Now that the plugin settings have been mimicked as PHP arrays we can keep these as a snippet and re-use in future theme theme development should the need arise. In the event the plugin is updated the snippet can be updated pretty effectively.

I prefer to offload these arrays into their own files for future usage. Whichever plugins you use in a theme it will be a case of grabbing the settings file, setting up the options framework, and outputting within your theme.

Now that the arrays have their own home make sure to include each within functions.php as required.

With that in mind let's move on and create a panel for FlexSlider within the Theme Options page.

Using the Options Framework this is done with the following code.

To create an option for each setting we add to the $options array.

First let's make sure we can have global access to each array by setting their scope within the optionsframework_options() function...

Using the $flexslider_options array and a foreach loop we can create an option / input at each iteration to match the settings.

The $options[] array is a convention of the Options Framework and explanations are loosely cited from the example files provided by the Author below.

• Line 1 - A counter is initialised.
• Line 3 - name - Human readable title, outputted within Theme Options page.
• Line 4 - desc - Human readbale description, describing the particular option.
• Line 5 - id - Unique identifer (we will use this for theme output).
• Line 6 - type - Possible field types: text, textarea, checkbox, select, radio, upload (an image uploader), images (use images instead of radio buttons), background (a set of options to define a background), multicheck, color (a jquery color picker), typography (a set of options to define typography), editor.
• Line 7 - std - Default input value.
• Line 8 - class - Possible values: mini, tiny, small
• Line 9 - options - Array of possible values for supported fields.

Further discussion

On line 3 we use the ternary operator to define a value if set. Some flexibility was considered whilst creating the arrays to hold any settings. This will allow for custom titles to be displayed along with each option whilst defaulting to the setting name if none provided.

Line 5 an incremental value is used to store a unique identifier with each option.

All other lines are standard values which should be followed as directed by the Options Framework Author taken from our settings array using corresponding keys.

It is now a case of lather, rinse and repeat for $tweet_options and $tooltip_options.

First a new panel is created.

Next we loop over those settings and add to the $options[] array. Notice the value of id, this will be useful later.

One more time...

First we create a new panel and give it a heading.

Finally we set the values, again the only change here is the settings array being passed and the id value.

As directed by the Options Framework we lastly return the $options array which is now populated with the plugin settings and outputted as options for the chosen 3 plugins.

The optionsframework_options() function is now complete.

Checkpoint and what's next, part 2

The Options Framework should now be functioning with the theme nicely which will present 3 panels within the theme options page and any corresponding options.

Plugin settings were registered with the Options Framework by iterating over the arrays created, we'll take a similar approach as we output theme options values to the theme in the final step.

Step 7 Applying the settings footer.php

First let's make sure we have access to the settings created and offloaded to their relevent files namely options.flexslider.php, options.tooltipsy.php and options.tweets.php.

The plugin settings are included with functions.php at each page load, we can gain access to these previously created setting arrays by making them global much like we did within functions.php.

With that let's consider the output required from each plugin used.

FlexSlider requirement

A pretty standard object containing settings which can be passed to the plugin upon initialising.

Line 7 as highlighted will remain the same, outputting a dynamic object with any settings is what we're looking for here.

To retrieve any stored values from the Options Framework the Author has created a helper function which accepts the option id as a parameter to retrieve its value. Back in Step 6 an option id was created using plugin_opt_n where n is a number starting from 0 to infinity. This is helpful and index order is unimportant.

A foreach loop will do the trick here to grab that data using a counter again to obtain the key and values dynamically in conjunction with the ever helpful helper function (tautology anyone?). Let's get to it.

• Line 1 - Here we setup an object to be passed to the plugin.
• Line 3 - We initialise a counter and set its value to 0.
• Line 4 - The syntax when compiling objects requires no comma seperation, using a storing the max value of our array allows us to check for this later on line 8.
• Line 6 - We store the returned option value as a variable for convenience.
• Line 7 - $key is the plugin setting, its value is outputted with a colon as we build the object.
• Line 8 - Here an we check that the item being iterated is the last item. If so we need to output without a comman.
• Line 9 - Again the syntax of an object requires boolean values to be written without comma delimeters so we check the values for "true", "false" and integers.
• Line 14 - The alternative syntax when not iterating / outputting the final item / setting in the object.

Once more we lather, rinse and repeat to finish up with the tutorial.

Twitter requirement

Retrieval of settings.

Tooltipsy requirement

Retrieval of settings.

Now you should be able to configure the plugins via the Theme Options page and see those changes reflected immediately within the theme.

Conclusion

Whilst many may not see a direct benefit to this tutorial, I've found this technique useful when any Administrators of a WordPress site need some access to finite tuning of existing theme features, the FlexSlider example in particular here showcases this technique well.

Having a Theme Options page has many practical uses, configuring jQuery plugins is one example however the Options Framework gives lots of potential. For example you could use it for logo uploads with its upload field type or you could use it to configure typography within the theme with the very helpful typography fields (a combination of select inputs and a colour wheel). The possibilities are only limited to your functional brief.

I hope this tutorial yields some improvements to your workflow and any questions related to the implementation of the Options Framework and theme here please do ask.