SMOF Documentation

This documentation will serve as a starting point for you to setup SMOF and will be updated from time to time as the SMOF is further developed in the future. Ultimately, I will probably just dedicate a full page documentation on this site, and include a downloadable HTML copy of it on Github. Enough talking, let’s get started.

The Basics

Requirements:

WordPress v3.2 or later
A WordPress theme compatible with WP 3.2
PHP 5
Notepad++ (optional)

Preliminary steps:

Download a copy of SMOF on Github
Extract the folder admin and images inside your theme
Turn off WP_DEBUG. You can turn it on later for debugging.

Installation

Copy the codes inside functions.php file and put that into your own theme’s functions.php file

Reset your options

For first time activation, you need to hit RESET to store your default options in the database. You would also do this when you’re upgrading from an older version of the SMOF.

This step is unnecessary for your users since the default options will be stored automatically on theme activation.

Using the Options

This section will tell you how set up the options that was added/modified in SMOF, and where applicable show how to use them in your theme.

Basic

If you open up theme-options.php, you should see an array of options and how they were written. As I’m sure many of you are talented and well experienced coders & WordPress developers, I’m not going to explain each one of them as that would quickly eat out my time from writing all of the other good stuff. I just hope you will find in your time to test how each option works. But as a starting point, here’s a line by line explanation example:

$of_options[] = array( "name" => "Media Uploader",
	"desc" => "Upload images using native media uploader.",
	"id" => "media_upload",
	"std" => "",
	"type" => "media");

1. name – This is the title that will be displayed on the options panel.
2. desc – Description for the option
3. id – A unique id for your option.
4. std – A standard value for the option.
5. type – The type of option

Note that some options requires different array keys, for example “options” and “mod”. Almost all of the options has already been defined in the theme-options so you can have a good study on how each one works.

Using it in your theme

This is how a basic example of how the above option would be called inside your theme.

global $data; //fetch options stored in $data
echo $data['media_upload']; //get $data['id'] then echo the value

As you would’ve guessed, the above code will output the URL to the image which was uploaded from the option panel. Also take a look at the documentation on variable scope for a better understanding of what global does.

You will notice that for some options like textarea or input, you will need to do a little sanitization to ensure the output would display correctly. Here’s an example:

echo do_shortcode(stripslashes($data['homepage_slogan']));

stripslashes will ensure that your output data will be free from any which is saved automatically everytime a " or : etc are present in the database.

More examples

Now that we’ve got the basics down, it’s time that we look at more examples. Currently these are the only two options that I will be explaining as they’re a little more complicated than the rest.

  • Slider
  • Sorter
Slider

The slider option populates most of the common data used by a slider, i.e. the image, title, description and link, while also enabling the user to drag and drop each slide to organize them. This is pretty much the simplest and intuitive way to set-up a slider.
Example option:

$of_options[] = array( "name" => "Slider Options",
	"desc" => "Unlimited slider with drag and drop sortings.",
	"id" => "example_slider",
	"std" => "",
	"type" => "slider");

That one is pretty self-explanatory. Just give it a unique id and you’re good to go.

Example usage:
The data for slider option is stored in multi-dimensional array. What that means basically is that you have a few levels of arrays that stores the data. To make everything simpler, this is the structure:

    [example_slider] => Array
        (
            [1] => Array
                (
                    [order] => 1
                    [title] => Title 1
                    [url] => http://url1.com/image1.jpg
                    [link] => http://link1.com/etc
                    [description] => etc etc
                )
            [2] => Array
                (
                    [order] => 1
                    [title] => 
                    [url] => 
                    [link] => 
                    [description] => 
                )
        )

To fetch all of these data, while retaining the order on which they were saved to the database will require you to do a simple foreach loop.

Below is just a basic example of how you may do it.

$slides = $data['example_slider']; //get the slides array

foreach ($slides as $slide) {
	echo $slide['title'];
	echo $slide['url'];
	echo $slide['link'];
	echo $slide['description'];
}

The above code will iterate through each of the slide and display whatever stored in them. Apparently, if you need to create a slider then you will need to echo the values inside your own HTML structure.

Sorter

The sorter enables the user to disable/enable block and organize them with simple drag & drop manner. The “blocks” can be anything at all, depending on the theme author’s creativity.

Example option:
First we need to create an array of the blocks.

$of_options_homepage_blocks = array( 
	"disabled" => array (
		"placebo" 		=> "placebo", //REQUIRED!
		"block_one"		=> "Block One",
		"block_two"		=> "Block Two",
		"block_three"	=> "Block Three",
	), 
	"enabled" => array (
		"placebo" => "placebo", //REQUIRED!
		"block_four"	=> "Block Four",
	),
);

Notice that the “placebo” array is required. It will not be shown on the option panel, but will be saved to database nonetheless. Continue:

$of_options[] = array( "name" => "Homepage Layout Manager",
	"desc" => "Organize how you want the layout to appear on the homepage",
	"id" => "homepage_blocks",
	"std" => $of_options_homepage_blocks,
	"type" => "sorter");

The above option uses our previously defined $of_options_homepage_blocks as the default values, and order them in which manner they were structured.

Example usage:
To display the saved blocks will require a combination of foreach and switch. As I’m sure you’re already familiar with these functions, here’s a code snippet how you would use them:

<?php
$layout = $data['homepage_layout']['enabled'];

if ($layout):

foreach ($layout as $key=>$value) {

    switch($key) {

    case 'block_one':
    ?>
    <!--do something here-->

    <?php
    break;
    case 'block_two':
    ?>
    <!--do something here-->

    <?php
    break;
    //repeat as many times necessary    

    }

}

endif;
?>

In the above code, you’re basically fetching the data stored inside the ‘enabled’ array of the ‘homepage_layout’ option. You then use a foreach loop to get the $key, which you will then use to determine what to do with each case of the key. I know that doesn’t sound very technical from me, but that’s how I understand it. :)

Summary

So far we have covered:
1. Setting up SMOF and porting it inside your theme
2. Defining the options
3. Using it in your theme

I hope you get a little clue from my somewhat deficient documentation, and give you the starting point on how you can use SMOF to its full potential. To streamline all the support questions, I will not be answering coding-related questions in the comment section. Please open a ticket on the SMOF’s Github Page instead. Thanks for reading and have fun theming! :)

70 Responses

  • Patrick Bagby

    This is a beautiful options panel! Thanks for sharing. I had to change ADMIN_DIR from get_template_directory_uri to get_stylesheet_directory_uri because I’m making a child theme. I mention this because it might help others.

    • Syamil

      Thanks for Patrick. And I’m glad you liked the options panel :)

      • AKshay

        how its work with child theme?

  • Skat

    Hi there,

    I just want to say that SMOF is amazing. I’ve just started to play with it and changed the input checkboxes to display an iphone like on/off and added a range slider too. Everything went fine but I noticed one thing: the “Background Pattern” option is not displaying anything – just the title and description of the option. The rest just works perfectly.

    Thanks for sharing.

    Cheers!

    • Syamil

      Hey there Skat, glad you liked it! :)

      Make sure the bg images path are correct, and don’t forget to hit Options Reset afterwards.

      Cheers

    • Itachi

      Hi,

      you wrote, that you add range slider and change the checkboxes to iphone style :) I really like it, can you send me code for this features? I would be really glad. If you don’t want to send me whole code can you please tell me about some good tutorial how to change checkbox style to ios look.

      Thanks for your time!

  • Skat

    Sweet, works like charm. Do you have a donate button here somewhere? Or a pp address? I wanna treat you with a coffee/beer? :)

    Thanks.

    • Syamil

      Nice :)

      Appreciate your generous offer, but these guys would probably enjoy the coffee more than I do https://www.wfp.org/donate/fillthecup :)

      Cheers

      p/s: Would love to see the theme when it’s ready!

      • Skat

        Done it. You have a great heart also :)

        Here’s the theme but I’m currently upgrading it with SMOF:

        http://www.freaklife.com/dwa

        Cheers and thanks again for your great work.

      • Syamil

        Hey thanks a lot Skat, you have a good heart too :)

        The theme’s looking good, I like it! ;)

        Cheers

  • Skat

    Hey,

    Sorry for bothering again, but I’ve encountered a problem and I have no one to ask :D.

    I have set up a checkbox, false by default. When I try to echo the result I get nothing. When I enable it and echo the result it displays 1. But when I disable it again and echo the result it displays: “Notice: Undefined index: slider_on_off”

    With my old theme options (I think it was based on the KIA one) I had this code that was handling the checkbox value:


    elseif($new_value == '' && $type == 'checkbox'){ // Checkbox Save
    update_option($id,'false');
    }
    elseif ($new_value == 'true' && $type == 'checkbox'){ // Checkbox Save
    update_option($id,'true');
    }

    and this for the checkbox itself:


    case "checkbox":
    $std = $value['std'];
    $saved_std = get_option($value['id']);
    $checked = '';
    if(!empty($saved_std)) {
    if($saved_std == 'true') {
    $checked = 'checked="checked"';
    }
    else {
    $checked = '';
    }
    }
    elseif( $std == 'true') {
    $checked = 'checked="checked"';
    }
    else {
    $checked = '';
    }
    $output .= '';
    break;

    With this code every time I enabled/disabled the checkbox it displayed “true” or “false”.

    Can you please point me in the right direction (I’m just a beginner in php).

    Cheers!

    • Syamil

      Hi Skat,

      Would you mind opening a ticket on Github? – https://github.com/sy4mil/Options-Framework/issues

      The comment section is a little inadequate to handle codes, I’m having a little problem reading your codes since it’s not indented properly.

      Cheers

  • Wes

    Hey there! quick question, if I want to build in a child-theme to one of my themes will the path definition STYLESHEETPATH mess up SMOF?

    • Syamil

      I’m not too sure honestly. Perhaps the best way is to try it out. :)

  • Smith

    Hi, i want to show all the pages list in the Homepage layout manager Disabled area. is there any way to include it for the replacement of this
    "disabled" => array (
    "placebo" => "placebo", //REQUIRED!
    "block_one" => "Block One",
    "block_two" => "Block Two",
    "block_three" => "Block Three",
    ),

    • Syamil

      You can actually just use the disabled array, but it would be more logical to change the key to something else, for example:

      
      "myblocks" => array (
        "placebo" => "placebo", //REQUIRED!
        "block_one"	 => "Block One",
        "block_two"	 => "Block Two",
        "block_three"	=> "Block Three",
      ),
      
  • AnyDog

    Hi,
    there are couple of features inside SMOF (I found it in “admin-intrerface.php, inside “switch”) in which I’m very interested and not sure how to use it:
    1. backup
    2. backround (with options for “repeat” and “position)
    The first (backup) and really don’t have a clue how to use it in “theme-options.php”. For “background” I tried to use:

    $of_options[] = array( "name" => "Background image",
    "desc" => "Upload images for site background and set up repeat and position",
    "id" => "background",
    "std" => "",
    "options" => array(
    "color" => "",
    "image" => "",
    "repeat" => "",
    "position" => ""
    ),
    "type" => "background"
    );
    , but I got this errors:
    Notice: Undefined index: background in ..admin-interface.php on line 1324

    Notice: Undefined variable: option_name in ..admin-interface.php on line 1328

    Fatal error: Call to undefined function optionsframework_medialibrary_uploader() in ..admin-interface.php on line 1335.Thanks

  • mostfool

    Syamil, thanks! A great options panel!
    I used to use KIA Thematic Options Panel, now I have switched all my themes to SMOF. Feel free to have a visit: http://www.colorvila.com, any advice is welcome!

  • Joey

    Quick question

    I’m newer to wordpress (haven’t really gotten into options yet)

    To use an option in the theme it says to use:

    global $data; //fetch options stored in $data
    echo $data['media_upload']; //get $data['id'] then echo the value

    So would this end up looking like:

    Also, php question I suppose, is there a way to rename $data, for instance as $SMOF or something else, so it would be:

    Thanks, great framework!

  • Joey

    grr, it took out my second code part….
    omg it hid my code areas… rofl

    line beginning with Also, php question I suppose, is there a way to rename $data, for instance as $SMOF or something else, so it would be:

    CONTINUED

    so it could be ?php global $myoptions; echo $myoptions['media_upload']; ?>

    • Syamil

      You can store the options in any variable name you like, e.g. :

      $smof = get_options(‘mythemename_options’);

      Then use anywhere in your file:

      $something_value = $smof['something_id'];

      Cheers

  • Ana

    Hi,

    i need some help with style switcher.

    I made more different color style.css files for my template,like red.css, blue.css and so on.
    In example of the SMOF is: $of_options[] = array( “name” => “Theme Stylesheet”,
    “desc” => “Select your themes alternative color scheme.”,
    “id” => “alt_stylesheet”,
    “std” => “default.css”,
    “type” => “select”,
    “options” => $alt_stylesheets); ——————————————–>do i need to change here something or i can use it as it is

    and also this is important for that part:
    //Stylesheets Reader
    $alt_stylesheet_path = LAYOUT_PATH; —————————————> what i need to add here to become to read from my css folder, because i tried some things but without success.

    In my header.php i have this two lines for styles:
    <link href="/css/style.css” rel=”stylesheet” type=”text/css” />
    <link href="/style.css” rel=”stylesheet” type=”text/css” />

    what i need to write in header.php to connect it with the theme options and with my styles in css folder that i have.

    Sorry to bother u with this, want to learn this also, tried on myself on many ways, but didn’t find the right one.Thanks for your email, i posted question here more time,so that others can see this to, maybe someone will need it.

    Thanks so much

  • Joey

    I dont have a github account (have too many other accounts), that’s why Im posting here…

    The index.php in admin shows up in the theme editor in wordpress instead of the theme’s index.php

    • Syamil

      Hi Joey. Please post your questions on our Github page. It really won’t take a lot of time to create a new account, and actually saved you (and me) from unreadable codes etc.

      Regarding your problem with the index.php file, I wasn’t able to replicate this issue on my local testing server. See here – http://i.imgur.com/Tk3is.png

      Cheers

  • Daniel

    Hey,

    Is it possible to add another image uploader to the slider controls? I need a thumbnail uploader.

  • Jdsans

    Hi,

    I’m not able to access the options using global $data in the functions.php

    I have an condition that i want to use in the function.php and theme-functions.php. But after declaring and inserting the condition nothing happens.

    This only happens for these two files only not any other

  • Ruturaaj

    This Options Panel is already wonderful. It will be great if you add “Multiple Add/Remove” groups. I don’t know if I’ve phrased it properly, so let me put it in little descriptive way.

    Let’s say I want to offer a settings page for 125×125 Ads in sidebar. Here I wish to offer a button “Add Ad Block” and upon click, two text boxes will appear underneath along with a “Remove” button. The Remove will remove the control-group. Here, I wish to define the control group with any controls and the “Add” button will simply repeat the control group. FOREACH loop should be fine to fetch the values of controls in array, much the same way as you’ve implemented Sorter.

    You may refer to the WPAlchemy Meta-Box Class for the implementation of this functionality. I’m not so good at jQuery. I attempted to implement this feature in one of my theme options before, but I couldn’t make it to work well. Perhaps you’re the person who can do it much better than an intermediate jQuery + PHP developer like me.

    What you think? :-)

    • syamilmj

      Thanks for the brilliant suggestion Raj, will surely look into it ;)

  • Mark

    Great framework! I need a little help with radio button images. Can you please put a sample of how to get and display the Radio button VALUE in the theme template. thanks!

    • syamilmj

      Added some sample to the thread you opened on TF. In the future please post questions like this on SMOF’s Github issue page. I get email notifications each time people post issues there so you’ll get my reply quicker & it’s more convenient to post codes etc there.

      Cheers

  • Azhari Subroto

    Hi syamilmj,
    Have you any Idea how to add wordpress editor in the framework just like the latest upadate of Devin’s option framework? http://wptheming.com/options-framework-theme/

    • syamilmj

      You need to use the wp_editor() function – codex.wordpress.org/Function_Reference/wp_editor

      It’s not exactly straightforward to integrate though, so good luck ;)

      • Mendel

        +1 for the Editor!

  • Marc

    I was getting errors trying to add the newest version to a child theme. It seems the newest version relies on TEMPLATEPATH and get_template_directory_uri — I switched it to STYLESHEETPATH and get_stylesheet_directory_uri and everything works as expected now. I don’t believe there are any drawbacks to using stylesheet instead of templatepath; perhaps its something to consider? Unless it was just overlooked. Either way, great looking framework, I can’t wait to really get my hands into it. Thanks!

    • Flickapix

      Marc, i believe templatepath & stylesheetpath is deprecated now, If you run the themecheck plugin it suggests not using them

  • Mike

    Hi

    Any chance someone can share a theme which is using the Admin Panel, I’m interested in seeing some default usage.

    Thanks

  • hchouhan

    Hello,

    Thanks for the code. Just wanted to point out that the screenshots/images are not working on this page.

  • SuitableWeb

    Thanks alot syamilmj.
    We will develop it and use it at our future themes

  • Mike

    I have a hard time getting this to work, it seems there’s no such thing as admin-interface.php or theme-options.php in the download. So there’s no clear example code to start from. Is this changed in recent versions?

    If so, could you please update this post, since it seems no longer correct.

    Thanks!

  • SuitableWeb

    Hello,
    how are you syamilmj?
    I told you before that we will build our framework on your theme options.
    we will build a home page builder on slider type (insert new box with ajax and drag & drop capability) these the most important featured at home builder.
    almost all things will complete very soon, but there are a single problem: when we rearrange the slides the data back to the default value at theme options page but all rights at database
    How we control at the order of slides.?

    very thenks.

  • SuitableWeb

    how are you, syamilmj?
    we solve the order problem, but we want to ad multi-checkbox at slider.

  • SuitableWeb

    this is our code bu don’t work>
    $hp_block .= ‘Select Category:’;
    $multi_stored_values = $val['tab_categories'];
    global $cats_ids;
    foreach ($cats_ids as $key => $option){

    if (!isset($multi_stored_values[$key])) {$multi_stored_values[$key] = ”;}

    $of_key_string = $id . ‘_’ . $key . ‘_’ . $new_order;
    $hp_block .= ”;

    $hp_block .= ”. get_cat_name($option) . ”;

    $hp_block .= ”;
    }
    $hp_block .= ”;

  • Scott

    Hello Syamilmj ,

    Thank you so much for this great framework.

    I am having an issue with all of the theme options resetting when I upgrade the WordPress core. I have tested this a couple of times and upgrading WP is the equivalent of pushing the “Reset” button within the theme options panel.

    Could you help me resolve this? I would gladly pay you for your time. Please email me at your earliest convenience :)

    Thank you – Scott

  • Scott

    Update: I fixed the issue by upgrading to the latest version.

    Thanks! – Scott

  • lenanghai

    Very Good!
    Thank you !

  • Aidan

    Just found this framework. Very impressed. Actually everything I’ve found on this site is fantastic. Thanks so much for your hard work!

  • AKshay

    its showing me that Error

    Warning: require_once(E:\xampp\htdocs\cad/wp-content/themes/cardiff-newadmin/index.php): failed to open stream: No such file or directory in E:\xampp\htdocs\cad\wp-content\themes\cardiff-new\functions.php on line 31

    Fatal error: require_once(): Failed opening required ‘E:\xampp\htdocs\cad/wp-content/themes/cardiff-newadmin/index.php’ (include_path=’.;E:\xampp\php\PEAR’) in E:\xampp\htdocs\cad\wp-content\themes\cardiff-new\functions.php on line 31

  • Terkel

    Amazing stuff! Keep up the good work, can’t imagin developing themes without SMOF!

  • Dima

    Hello ,I introduced typography options
    $of_options[] = array( “name” => “Body Font”,
    “desc” => “Specify the body font properties”,
    “id” => “body_font”,
    “std” => array(‘size’ => ’12px’,’face’ => ‘arial’,’style’ => ‘normal’,’color’ => ‘#000000′),
    “type” => “typography”);
    ,how code can I show it in loop template,please help me ?

  • Mohsen Elgendy

    Dude, This ROCKS ;)

  • ETNO

    Can I do in sortable field a set of different options like inputs, textarea. For example, I want to do homepage builder. I have group of options for news block, for slider, for ads block and I want to do this blocks sortable. Can I do this?

    And can I do repeater field like in slider, but simple input fields?

  • SrFranky

    Sorry, let me save the settings, shoot me error. Forgive my Inglés Salu2

  • youarethemanmyfriend

    Just wanted to I love what you’ve done!

    Unfortunately I don’t like that you require attribution for it now.

    You should just come to terms with it: when you create something awesome that people want to use, people are going to use it regardless. I think it actually stops people from developing with it further by requiring it.

    You should drop back it down to GPL2 if only for the people that came before you that didn’t require such stipulations.

    Other than that, love the framework more than dirt, but i will have to fork it, customize it, and not be able to share my updates because of that attribution.

    • syamilmj

      The attribution link is not required at all, actually ;)

      Cheers

  • youarethemanmyfriend

    say**

  • bo

    hello there
    after following the directions above i am getting an error like akshay above:

    Warning: require_once(E:\xampp\htdocs\cad/wp-content/themes/cardiff-newadmin/index.php): failed to open stream: No such file or directory in E:\xampp\htdocs\cad\wp-content\themes\cardiff-new\functions.php on line 31

    Fatal error: require_once(): Failed opening required ‘E:\xampp\htdocs\cad/wp-content/themes/cardiff-newadmin/index.php’ (include_path=’.;E:\xampp\php\PEAR’) in E:\xampp\htdocs\cad\wp-content\themes\cardiff-new\functions.php on line 31

    can anyone confirm how to get the initial install to work
    is it:
    /**
    * SMOF
    */
    require_once (‘admin/index.php’); // Theme Options

    or is it

    /*——————————————*/
    /* Options Framework
    /*——————————————*/

    // Paths to admin functions
    define(‘ADMIN_PATH’, STYLESHEETPATH . ‘/admin/’);
    define(‘ADMIN_DIR’, get_bloginfo(‘stylesheet_directory’) . ‘/admin/’);
    define(‘LAYOUT_PATH’, ADMIN_PATH . ‘/layouts/’);

    // You can mess with these 2 if you wish.
    $themedata = get_theme_data(STYLESHEETPATH . ‘/style.css’);
    define(‘THEMENAME’, $themedata['Name']);
    define(‘OPTIONS’, ‘of_options’); // Name of the database row where your options are stored

    // Build Options
    require_once (ADMIN_PATH . ‘admin-interface.php’); // Admin Interfaces
    require_once (ADMIN_PATH . ‘theme-options.php’); // Options panel settings and custom settings
    require_once (ADMIN_PATH . ‘admin-functions.php’); // Theme actions based on options settings
    require_once (ADMIN_PATH . ‘medialibrary-uploader.php’); // Media Library Uploader

    please help as this is a great piece of software!

  • bo

    i got through this by simply following the directions
    sorry for the rediculous lack of reading
    cheers
    bo

  • jasim

    Hello,

    Is there any Tiny MCE Editor port into this framework with image upload option ?

  • crazyfrom

    How to Add Tiny MCE Editor port into this framework too?I tried a lot of methods are unable to successfully

  • atinder

    awesome work.
    how about making in multilingual ?

  • daVinci

    Hello Syamil,

    I’m excited to see such a well-made framework. But I have one question about the MUST to Reset.
    You have written, quote: ”This step is unnecessary for your users since the default options will be stored automatically on theme activation.”

    What do You mean by “users”?
    So, as an example: If someone download my template and install it, will not have to click the reset button? Do I understand it?
    Where this option will be storage?
    Thank You for Your work.
    I love it.

    Daniel M. [Poland]

    • Gupron Rahmatain

      See at “of_option_setup” function in functions.admin.php.

      if (!of_get_options())
      {
      of_save_options($options_machine->Defaults);
      }

      • daVinci

        Thank You! Grupon Rahmatain

  • Rupesh Shrestha

    Thank you for the great option framework. I am really feel easy to use it.
    I’ve made the “Social Networks” heading in SMOF but I am unable to add the images like in home, styling option etc.
    Can anyone help me to add images on user define headings??

  • Oske

    Hi, how i can change position on menu?
    I want display theme options link on main wordpress admin menu

Sorry, but commenting has been disabled.