Create Custom Option Panels with WordPress 2.9

Create Custom Option Panels with WordPress 2.9

WordPress is a powerful engine in itself, but sometimes themes need options that fall outside the core dashboard. The good news is that putting these changes into motion is not as complex as it once was. This is where custom option panels come in.

In this tutorial we’ll use a custom options panel to insert analytic tracking codes. This will be done using the recent WordPress 2.9 updates to options. The same fundamentals can be carried over to a number of other custom field applications in you own themes.

Option Panel Fundamentals

Custom Option Panels
Custom option panels are a way of expanding options for a specific theme. The big idea allows non-developers to maintain a high level of control over a theme. The average blogger shouldn’t have to spend time learning WordPress tags and PHP fundamentals in order to make simple changes like design elements or content sources. One panel might be responsible for social media accounts like Twitter or Flickr, while another might be for background images.

We’ve covered WordPress option panels before in our “How to Add an Announcement Box to Your WordPress Theme” tutorial. Since then, advances in the template tags and documentation have made basic options much easier to make. Less headache is a great thing.

The Goal

Our custom options panel will allow a blog administrator to paste in tracking codes (e.g. Google Analytics) which will be added into the theme’s code automatically. This will make updating (or appending) the tracking code easy to do without leaving the administrative dashboard.

The resulting panel

This tutorial combines and simplifies several of the articles found in the WordPress Codex. If you get stuck or would like to see about additional options that do not appear here, I’ve linked to the source articles at the end of this post.

Creating the Files

Create a new folder called “functions” inside the root of your theme folder. This folder is where the code will live, and keeps it neatly separated from the standard functions. Within that folder, create a new PHP file called “admin-menu.php”. This file will contain all functions related to option panel creation and management.

In order to have WordPress recognize this new folder, we’ll need to reference it from within the functions.php file. Open it up and paste in the following block to add our new file to the mix:

Need to check a MySQL database value directly at any point? WordPress saves all custom fields and options into the wp_options table by default. If the values are written correctly, you should see the results there.

Build the Options Panel

The options panel will be built and called using four functions. Three of this functions will be within the admin-menu.php file created in the last step. I’ve broken them down in order of appearance (copy in accordingly). Please keep in mind that you can change the function names used as long as all other references are updated too.

Function omr_create_menu

This function is responsible for creating a new dashboard menu item in the sidebar via the add_menu_page hook. The hook specifies the title for the page (Build Internet) as well as which function should construct the option panel (omr_settings_page). After the first hook is initiated, the register_settings function will be called.

Function register_mysettings

The register_setting function is responsible for declaring a new setting, and arranging it into groups as needed. We’ll be using it here in minimal capacity. For larger control panels, grouping would become a more important way of keeping organized.

Function omr_settings_page

This function is where the form and structure of the options panel is declared. The WordPress dashboard has a series of default CSS styles assigned to elements, and this form will be automatically formatted upon creation.

Notice that the “omr-settings-group” is declared before any inputs appear. This makes sure that the field(s) we specified in the last step are loaded. Once loaded, the get_option function loads in the current value from the database. This will keep the theme from overwriting the database values with blank fields every time an edit is made.

The submit button’s value is set to <?php _e('Save Changes') ?>, which will commit changes to the database. No extra work required!

Accessing the Stored Value

Once you’ve saved a custom option to the database, you’ll still need to access it for output in the theme. This is done using the get_option function available in WordPress. Open up your theme’s footer.php file and we’ll demonstrate by placing the analytics code. Copy the following in immediately above the closing <body> tag:

If everything is working properly, you should see the value of the option output in the live version.

Exploring Possibilities

Inserting analytic codes is obviously one of the less exciting uses of option panels. Similar methods can be used for announcements, “Image of the Day”, or a number of other innovative ways. Have any good ideas or suggestions for further uses? Share them (and any troubles) in the comments below. If anyone needs a downloadable version, please let me know and I’ll put one together. A modified set of files is available for download below. It was built off of the principles found in this tutorial.

Related WordPress Codex Entries

  1. Creating Options Pages
  2. Adding Administration Menus

Posted Friday, January 8th, 2010 · Back to Top

SPONSOR

Add Comment

71 Comments 41 Mentions

  1. Eric B. Author Editor

    Excellent tutorial! Adding an options page is a very useful thing to do for WordPress.

    ·

  2. KayRoseDesign Author Editor

    Great article, really good explanation on the basics here :)

    ·

  3. Henry Author Editor

    Awesome post. We need more of these tuts. Seriously. Thanks
    -Henry

    ·

  4. Andre Nitz Author Editor

    That was great! Thank you very much for this article.

    Greetings from germany, André

    ·

  5. imagingdesk Author Editor

    good start in 2010 year

    ·

  6. krike Author Editor

    Great tutorial :D bookmarked it

    ·

  7. Aaron Author Editor

    Pods (http://pods.uproot.us/) is a great GUI plugin alternative to this. Not sure if this is better/worse or whatever but just an alternative.

    ·

  8. Dumm Author Editor

    thanks for the codes. regards

    ·

  9. dede Author Editor

    the great article!
    thanks. regards

    ·

  10. Kishore Mylavarapu Author Editor

    Excellent article on wordpress.Thank you very much for this tutorial.

    ·

  11. Dave Author Editor

    Nice article guys. Yours is one of the few RSS feeds I look forward to each week!

    I keep meaning to try an options panel when I’m building themes but never seem to get round to it. Maybe this time…

    ·

  12. Enk. Author Editor

    Awesome !
    Just wanted that.. thanks a ton ! :)

    ·

  13. TutsBot Author Editor

    Great !

    Thanks Zach :) , I liked it !

    ·

  14. Luke Author Editor

    Very few well written posts out there on creating options panels, thanks for this!

    ·

  15. Eko Setiawan Author Editor

    Thanks..for this tutorial, We’re looking for tutorials create custom options panel for our next free wordpress template.

    ·

  16. Zach Dunn Author Editor

    Thanks for the feedback everyone. Custom panels wasn’t a topic I’d seen covered gracefully before. This was an attempt to make the respective Codex entries into something a little more usable.

    ·

  17. MacBoy Author Editor

    This is a good set of steps. Nice teaching!

    Perhaps you should also remind the readers on the best and secure methods of obtaining user inputs. Things such an nonce, cross-site scripting (xss), etc.

    With such excellent tutorials, its important to also teach us the secure methods. After all, you’ve already got our attention!

    Thanks again.

    — MacBoy

    ·

    • Zach Dunn Author Editor

      @Macboy

      You’re absolutely right, but the context of this form makes security less of an issue. This options panel is only available to the blog’s administrator, so while cross scripting might be a concern, there is already a filter between the average person and the form. At least that was my thinking.

      ·

  18. Henry Author Editor

    Can’t get the icon to show up in the add_menu_page ? Is there a requirement of what type of file or size it has to be?

    ·

  19. Kai Köpke Author Editor

    nice tutorial. those custom option panels offer a lot of new possibilities…

    ·

  20. Tutorijali HDonWEB Author Editor

    Great tutorial, bookmarked

    ·

  21. Henry Author Editor

    Can you provide a download file for this tutorial please.

    ·

  22. Keith Author Editor

    Nice job on this one. Thanks for sharing

    ·

  23. Jon Author Editor

    Doesn’t seem to work, as soon as I add the code to functions.php it returns a headers error.

    The rest works, but due to the headers issue each item you try to edit functions or add something to the box it breaks.

    ·

    • Zach Dunn Author Editor

      @Jon

      I’ll upload my working version later in the day so you can reference against your own. I know from past experience that odd things (e.g. a blank line at the end of the file) can throw errors.

      ·

  24. Henry Author Editor

    How would you go about making a select menu for several stylesheets? Any ideas?

    ·

    • Jodie Author Editor

      The paragon of unrdestandnig these issues is right here!

      ·

  25. Jon Author Editor

    Thanks Zach that would be awesome :)

    ·

  26. Zach Dunn Author Editor

    @Jon

    I’ve updated the post to include the downloadable files. Hopefully it offers some insight into your problem.

    ·

  27. Jon Author Editor

    Thanks Zach, I’m having the same issue with functions.php, the error returned is:

    Warning: Cannot modify header information – headers already sent by (output started at /***/functions.php:3) in /****/theme-editor.php on line 75

    Its on a fresh install and I have tried in 3 or 4 templates, one of which is the default template.

    Thanks :)

    ·

  28. Martin Rusteberg Author Editor

    nice post in getting the codex more accessible.
    in the future, maybe you can share a tut where you explain how your ‘submission’ panel works…

    ·

  29. Juri Author Editor

    Great tutorial, this will definitely come in handy on a website I’m creating for a client. Do you know of any way of removing administration menus i.e. plugins, users, settings, etc. I want to keep this dashboard as simple as possible for my client.

    ·

  30. denbagus Author Editor

    thank you for this tutorial.. make me easy to create custom option panel

    ·

  31. Darren Author Editor

    Wonder if it would be possible to view your google analytics from your dashboard, or even your buy sell ads account, that would be sweet

    ·

  32. Konstantin Author Editor

    The next step to an semi-clean options page would be to use the settings API to create the option tables. This is where add_settings_sections(), add_settings_fields(), do_settings_sections() and do_settings_fields() come in. :)

    ·

  33. web design kent Author Editor

    Very useful read! Thanks!

    ·

  34. Ed Author Editor

    Nice one!

    I hope a more extensive tutorial is on it’s way covering this topic, WordPress options pages is a topic that hasn’t been covered well on the various WP development blogs.

    This is a nice start! :)

    ·

  35. Gilbert Author Editor

    Nice tut. I created a framework for this (very similar to what your doing here) called the “WordPress Theme Framework”. People can check it out at http://wtf.dev7studios.com.

    ·

  36. Gaston Suarez Duek Author Editor

    Thx! its very useful but I’m having a problem after I click “Save Changes”, it takes me to a blank page in options.php and it doesn’t came back to the admin panel. Any suggestion?

    ·

    • Sven Author Editor

      It’s been a while but in case it’s useful to anyone:
      I had he same problem (blank page after submit). After 30 minutes I realized that it was just a couple spaces at the end of the php-code in admin-menu.php that fucked it up.

      ·

  37. lee hipkiss Author Editor

    thanks for this great tutorial, it is just what i needed (first theme design and i want it to be good)

    i have a problem that is related to your guide (and im pretty confident you know what your are talking about)

    i have been able to implement some options using register_settings fine. but all of these so far have been text fields.

    i want to have an option to select a basic layout for the theme. i would do this by providing multiple stylesheets.

    the way i want to display these is in a drop down menu option.

    once i have the option i know how to call it in the header so thats not a problem.

    i want the dropdown menu to display all css files in /theme/styles/ folder and then when one is selected save that option.

    here is my half written code:

    My theme options

    Google Webmaster Code
    <input type="text" name="gw_code"
    value="” />

    Google Analytics Code
    <input type="text" name="ga_code"
    value="” />

    Other Codes to go into your website head section
    <input type="text" name="head_code"
    value="” />

    Other Codes to go into your website footer section
    <input type="text" name="footer_code"
    value="” />

    <input type="submit" class="button-primary"
    value="” />

    Design and Layout Settings

    Select a basic layout
    Choose a layout from the options provided:
    <input type="form-select" name="layout_select"
    value="” />

    <input type="submit" class="button-primary"
    value="” />

    <?php }

    sorry for the long comment, could you help me?

    ·

  38. kilinkis Author Editor

    1st of all thx a lot 4 this tut, it did really help me.
    now, ive gone a lil bit further, and created a page where users have to input some data. so if the form its not submited, the script will show the form or of it is it will do the magic. now, on the form view, i have a table to show previously entered data, with EDIT|DELETE buttons. here is my problem, those buttons and its link. i try to send the ID of the record i want to edit/delete but im having problems with the URL. example: http://localhost/wordpress/wp-admin/admin.php?page=var/www/wordpress/wp-content/themes/glassical/mycode/buques.php?borrar=18 will exit with a permission error. what can i do? thx a lot, i searched a lot and had no luck.

    ·

  39. kilinkis Author Editor

    solved! i had a lotta trouble with that URL, now it looks something like ….admin.php?page=mycode/buques.php&borrar=18

    ·

  40. shireen Author Editor

    Hi,
    Refarding your tutorial , where to place the option.php file and what piece of code it contains?
    Seconldy , i want to make a CMS type thing like Manage country that will have add, edit, delete, listing , paging, searching … how can i make it?

    Alot of thanks in advance

    ·

  41. bhagu Author Editor

    Great! so excited to use it on my blog, which is under development.

    ·

  42. Joe Author Editor

    Great tutorial, just what I was looking for – thanks!

    I just have one question. If I wanted to have more than one box, how would I do this?

    On line 17, I have put this:

    register_setting( ‘fareham-settings-group’, ‘fareham_featured_video’, ‘fareham_top_banner’ );

    Howeevr, as soon as I click save, I end up with both boxes removing all text.

    ·

  43. Joe Author Editor

    Typical, as soon as I ask, I figure it out.

    register_setting( ‘fareham-settings-group’, ‘fareham_featured_video’ );
    register_setting( ‘fareham-settings-group’, ‘fareham_top_banner’ );
    }

    ·

  44. Gláuber Kélvin Author Editor

    Muito bom esse tutorial. (Brasil)

    ·

  45. Joe Author Editor

    I’ve been trying to figure out how to create a submenu using this code, but have had no luck.

    Any ideas?

    ·

  46. Chrimu Author Editor

    Like Gaston, I also get a blank options.php page after I click on “Save Changes”. Please help :(

    ·

  47. lirik Author Editor

    great tutorial.. thanks for sharing.

    ·

  48. happybolt Author Editor

    How to add button ” Reset “?
    Prompt please.

    ·

  49. kilinkis Author Editor

    hi! here i am again, now my problem is that the options ive created, are only for admins and i want them to be used by authors too. any ideas?

    ·

  50. Bhq Author Editor

    Hi, this is a great tutorial.
    I was just wondering, does anyone know how to have a TinyMCE editor in the option form.

    Thank you.

    ·

  51. lorem Author Editor

    Where to place favicon.ico ?

    ·

  52. Alyen Author Editor

    Nice tutorial !!!!

    Thank you.

    ·

  53. HCL Author Editor

    With such excellent tutorials, its important to also teach us the secure methods. After all, you’ve already got our attention!

    Thanks again.

    ·

  54. charles marsh Author Editor

    Great tut, helped me a lot today! thanks very much…

    ·

  55. Nicotine Author Editor

    you can say that alternative medicine is cheaper too and usually comes from natural sources .*~

    ·

  56. Raj Author Editor

    Hi,

    Thanks for this. This is superb. Can we add more option for the css file? A select box. Something like a array that collects names of all css file in a particular folder and displays in to select box to choose?

    Thanks,
    –Raj

    ·

  57. gavin Author Editor

    Thanks man! Great writeup. Liked it mucho… Very thorough

    ·

  58. David Author Editor

    Thanks for this post I think this is exactly what I need but I have one quick question.

    if i wanted to add a help page with a video tut to the backend would this be the best way to do it. Im working on a member site where people can submit posts but I would like to have a help page with a video that shows them how to write posts. I would also like to limit that page to contributers, although not necessary. Can you offer any advice on this?

    ·

  59. Craig Author Editor

    Thanks for this tutorial, but how can this work for Editors?? The menu shows, but upon saving it displays ‘Cheating uh? as the Editor does not have access to the options.php page which the menu item is posting to. Please help!!

    ·

  60. akik Author Editor

    Very Helpful Tutorial. Thanks For Sharing…

    ·

  61. Nat Author Editor

    Nice.

    ·

  62. Moriah Teravainen Author Editor

    What i do not understood is actually how you are not actually much more well-liked than you might be right now. You’re very intelligent. You realize therefore significantly relating to this subject, produced me personally consider it from numerous varied angles. Its like men and women aren’t fascinated unless it’s one thing to do with Lady gaga! Your own stuffs nice. Always maintain it up!

    ·

  63. Reabbledlerve Author Editor

    [url=http://bestgamemobile.ru/]скачать игру[/url]
    [url=http://bisph.ru/]игры для телефона[/url]
    [url=http://newsfon.ru/]3d бродилки для nokia[/url]
    [url=http://javapost.ru/mobilegames/]jar игры[/url]
    [url=http://phonegood.ru]купить телефон[/url]
    [url=http://phonescenter.ru/]купить нокиа[/url]

    ·

  64. teak garden furniture Author Editor

    Create Custom Option Panels with WordPress 2.9 | Build Internet I was suggested this blog by my cousin. I’m not sure whether this post is written by him as no one else know such detailed about my trouble. You’re wonderful! Thanks! your article about Create Custom Option Panels with WordPress 2.9 | Build InternetBest Regards Cindy

    ·

  65. web filtering Author Editor

    I think my websites in wordpress needs this plugin.thanks for sharin the info.

    ·

  66. sawung Author Editor

    awesome ,really great tutorial. thank’s

    ·

  67. Online Recruitment Tool Author Editor

    Great tut! Im almost there but when I save my options they’re then rendered blank. Im using v3.5 could that be my problem?

    ·

 

Build Internet by One Mighty Roar. Since 2008.