1. Documentation
  2. WooFramework Codex

Adding Theme Options

Introduction ↑ Back to top

All Woo themes come with a massive amount of settings/options that allow you to easily enhance your theme. These options typically allow you to add a new logo to your site, assign ad space, add analytics tracking code, change theme styles and much more.

On top of that, themes are all unique and have more settings tailor-made to that specific theme, like adding background images, adding a post slider, creating advanced homepage layouts, and setting element colors individually, just to mention a few.

The Settings Panel ↑ Back to top

Every theme (even free ones) come with a settings panel, built-in and ready-to-use. It’s neatly tucked away under the comments tab in the WordPress backend sidebar.

Screen Shot 2014-07-07 at 16.46.31

 

Pre-defined options ↑ Back to top

Every Woo theme comes with built-in or pre-defined options. Settings like custom logo uploading, alternative style selectors, custom CSS input, custom RSS links and tracking code input are common in all our themes.

But that is just the tip of the iceberg. Themes come with a huge amount of options over and above the ones mentioned already. Settings for sliders, ad spaces, colors, images, layouts, typography, and plenty more for fine-tuning your theme for your specific needs.

Some of the options available.
Some of the options available.

Understanding the Settings ↑ Back to top

Adding your own custom options is not as hard as you might think. Theme WooFramework does all the heavy lifting and it’s up to you to get creative. There is one file that will be of great interest once you want to start adding your own options.

Locate the /includes/theme-options.php file. Inside you should see the following:

$options[] = array( "name" => "General Settings",
                    "type" => "heading");

$options[] = array( "name" => "Theme Stylesheet",
                    "desc" => "Select your themes alternative color scheme.",
                    "id" => $shortname."_alt_stylesheet",
                    "std" => "default.css",
                    "type" => "select",
                    "options" => $alt_stylesheets);

$options[] = array( "name" => "Custom Logo",
                    "desc" => "Upload a logo for your theme, or specify the image address of your online logo. (http://yoursite.com/logo.png)",
                    "id" => $shortname."_logo",
                    "std" => "",
                    "type" => "upload");    

$options[] = array( "name" => "Text Title",
                    "desc" => "Enable if you want Blog Title and Tagline to be text-based. Setup title/tagline in WP -> Settings -> General.",
                    "id" => $shortname."_texttitle",
                    "std" => "false",
                    "type" => "checkbox");

$options[] = array( "name" => "Custom Favicon",
                    "desc" => "Upload a 16px x 16px Png/Gif image that will represent your website's favicon.",
                    "id" => $shortname."_custom_favicon",
                    "std" => "",
                    "type" => "upload"); 

$options[] = array( "name" => "Tracking Code",
                    "desc" => "Paste your Google Analytics (or other) tracking code here. This will be added into the footer template of your theme.",
                    "id" => $shortname."_google_analytics",
                    "std" => "",
                    "type" => "textarea");        

$options[] = array( "name" => "RSS URL",
                    "desc" => "Enter your preferred RSS URL. (Feedburner or other)",
                    "id" => $shortname."_feed_url",
                    "std" => "",
                    "type" => "text");

The “heading” is the start of an options panel/section. Under the “heading” option you should see the sub-sections that make up the options under the relative heading.

Options Types ↑ Back to top

It’s important to notice that the non-heading options all have a type index that defines their purpose. Currently these include:

  • text – Single line text/HTML input
  • textarea – Multiple lines of text/HTML input
  • select – Dropdown select input; v1
  • select2 – Dropdown select input; v2
  • radio – Radio button group
  • checkbox – Single checkbox input
  • multicheck – Multiple checkboxes
  • upload – Ajax upload button with text input
  • upload_min – Ajax upload button
  • color – Colorpicker
  • border – Border combo; size, style & color
  • typography – Typography combo; size, font, style,
  • images – Selecting mechanism with the use of images

A quick note on the multicheck field types ↑ Back to top

The multicheck and multicheck2 field types make use of an “options” setting, using an array of the options to be output. While multicheck2 uses both the keys and values supplied to that option (key as the stored value and the value as the label), multicheck uses the value for both the stored value and the label for the checkbox in question.

An example of each of these field types would be as follows:

$options[] = array( "name" => "My Title",
                    "desc" => "The title of my new option.",
                    "id" => $shortname."_my_title",
                    "std" => "",
                    "options" => array( 'one' => __( 'One', 'woothemes' ), 'two' => __( 'Two', 'woothemes' ), 'three' => __( 'Three', 'woothemes' ) ),
                    "type" => "multicheck2");

Adding Custom Options ↑ Back to top

The following is a step-by-step guide on how to add your own panel, with it’s own unique options and then how to use those options in your theme. For this example we are going to add a title, text and image input options in the themes footer. Let’s get started…

Creating your new options ↑ Back to top

We will need a text, textarea and image option. Preceded by a heading so that we can easily differentiate between out own option and the predefined option. The options will look something like this:

$options[] = array( "name" => "My New Option",
                    "type" => "heading");

$options[] = array( "name" => "My Title",
                    "desc" => "The title of my new option.",
                    "id" => $shortname."_my_title",
                    "std" => "",
                    "type" => "text");

$options[] = array( "name" => "My Description",
                    "desc" => "The description of my new option.",
                    "id" => $shortname."_my_description",
                    "std" => "",
                    "type" => "textarea");

$options[] = array( "name" => "My Image",
                    "desc" => "The image that goes along with my new option.",
                    "id" => $shortname."_my_image",
                    "std" => "",
                    "type" => "upload");

Amending theme-options.php ↑ Back to top

Adding the above code to your backend is a matter of deciding where you want to place it. For the purpose of this tutorial we will add it to the front of the pre-defined options for ease of access. For example:

…
$options = array();   

// ADD NEW OPTION CODE HERE <------

$options[] = array( "name" => "General Settings",
                    "type" => "heading");
 …

Result:

…
$options = array();   

$options[] = array( "name" => "My New Option",
                    "type" => "heading");

$options[] = array( "name" => "My Title",
                    "desc" => "The title of my new option.",
                    "id" => $shortname."_my_title",
                    "std" => "",
                    "type" => "text");

$options[] = array( "name" => "My Description",
                    "desc" => "The description of my new option.",
                    "id" => $shortname."_my_description",
                    "std" => "",
                    "type" => "textarea");

$options[] = array( "name" => "My Image",
                    "desc" => "The image that goes along with my new option.",
                    "id" => $shortname."_my_image",
                    "std" => "",
                    "type" => "upload");

$options[] = array( "name" => "General Settings",
                    "type" => "heading");
 …

Save changes. Upload it to your server if you are testing on a live server. The result should look like the following:

Screen Shot 2014-07-07 at 16.44.26

Populate and Save ↑ Back to top

The next step is to get some data in those new options. So proceed to add text for the title and the description along with uploading an image. After the values have been added click “Save Options”.

Using the Options ↑ Back to top

After creating the options, adding them to the options back end and populating them with data, it’s time to actually start using the saved values. WordPress makes it easy to retrieve values from the database with the use of the get_option() function. So calling the saved values will look like this:

get_option('woo_my_title');

The following example will produce a table like output with the new options in your theme’s footer, added into the themes footer.php.

<table>
<tbody>
<tr>
<td>
       <img style="margin: 0pt 20px 20px 0pt;" src="<?php echo get_option('woo_my_image'); ?>" alt="" /></td>
<td></td>
</tr>
</tbody>
</table>

The end result is a little custom piece of backend that is easy to update.

Resulting footer output from new options

New Woo global options array ↑ Back to top

New in WooFramework v2.7.0 is the $woo_options variable. Instead of using the above get_option, you can use this pre-populated array, which holds all the options. This will save you accessing the database to get your option, which in turn will ease the load on your server.

You need to define $woo_options as a global in the template you want to use it in. You only need to define it once per template file. Example:

<?php global $woo_options; ?>
<h1><?php echo $woo_options['woo_my_title']; ?></h1>
<?php 
if ( $woo_options['woo_a_checkbox_option'] == "true" )  
    echo "<p>The checkbox is set</p>";
else
    echo "<p>The checkbox is NOT set</p>";
?>

Summary ↑ Back to top

Looking over the pre-defined option panel in any theme will give you a good sense of what can be done. Making use of the various options available will just take a little bit of inspection and ingenuity. Good Luck!

WooCommerce - the most customizable eCommerce platform for building your online business.

  • 30 day money back guarantee
  • Support teams across the world
  • Safe & Secure online payment