Adding Theme Options in Genesis

If you’re customizing your site in a way that require site-wide options to be managed in the backend, it’s a good idea to use the Genesis Theme Settings page rather than create a separate backend page specifically for your feature. This keeps all theme-related settings in a single location.

I’m going to walk you through creating your own theme options for Genesis. I’ll be adding a Social Settings box that allows you to specify a Twitter and Facebook URL, to be used in the nav menu of the theme.

Set up Defaults

The default values are what the fields will be set to when a user clicks “Reset Settings”. I’m just going to use blank values, but you could use whatever you like.

Sanitization

One of the major improvements to Genesis in the 1.7 release is the addition of a Sanitizer class. Mark Jaquith, a lead developer of WordPress, was hired by StudioPress to conduct a security audit, and this was one of the results.

The Sanitizer class makes it easy to ensure only the specific types of data you want can be saved in your theme settings. This prevents someone from dropping malicious scripts into one of your theme settings. For more information, watch this Theme & Plugin Security presentation.

By default, Genesis comes with four sanitization filters: one_zero, no_html, safe_html, and requires_unfiltered_html. These should cover almost anything you need to do, but if you did want to add something to this list you could use the genesis_available_sanitizer_filters filter (see /lib/classes/sanitization.php).

We’re going to use the no_html filter.

Register Metabox

We’ll use the add_meta_box() function to add a metabox to the Theme Settings page. You can look in /lib/admin/theme-settings.php for more examples:

Create Metabox

Our add_meta_box() function basically says “Stick the metabox the the be_social_settings_box() function on the Theme Settings page.” Now we have to create that function.

For more examples of metaboxes, see /lib/admin/theme-settings.php.

Putting it all together

Since there’s a lot code, I recommend putting it in a single file. Inside my child theme I’ve created /lib/functions/social-settings.php, and this is the contents:

Bill Erickson

Bill Erickson is a freelance WordPress developer and a contributing developer to the Genesis framework. For the past 14 years he has worked with attorneys, publishers, corporations, and non-profits, building custom websites tailored to their needs and goals.

Ready to upgrade your website?

I build custom WordPress websites that look great and are easy to manage.

Let's Talk

Reader Interactions

Comments

  1. Thanks for the useful guide, never use filters always using hooks as i do not have to done major customization.
    Thanks a ton, will try to ad more things using this tut.

  2. Thank Bill for this quick walk through, It’s not an easy thing to find good articles about adding or customizing theme options for Genesis even in the official support forum!

  3. This article helps us in an area that is really important to us – customising our Genesis installs to make them even quicker and simpler to produce in record times.

    i have one question though – what sort of protection do the options you create have when Genesis versions change when you update the parent theme in the future?

    • Since all of the customizations are done in your child theme, they are perfectly save from an upgrade. The only thing that could cause problems is if Genesis drastically changes how the settings are registered, but I don’t see that happening. They add the filters and hooks so that you can extend the theme settings without worrying about an upgrade.

      In the past the only way to customize it was to unhook the Genesis function that registered all the theme settings and create your own. The problem here is your settings page is now “frozen” at the version you originally built it on, since any new metaboxes added to Genesis won’t be included in your function. Now that they have a hook inside the function that registers Genesis metaboxes, this isn’t a problem.

  4. This is excellent and totally opens my eyes to lots of new possibilities, so glad SP added this and that you told us about it.

    Personally for social media button I usually create a “social media menu” using WP 3.0 menus with custom links inserted, link classes assigned to each item and then apply images with CSS. I like this method in part because it keeps the drag and drop functionality of rearranging the icons at will.

    As for the Genesis Theme Settings menu however I have a request to the universe… would someone with far superior skills then me… please considering making the Genesis Theme Settings page meta boxes flexible the way the WP dashboard is? I personally hate the new single column layout, and the fact that it’s fixed width… it ought to be flexible and stretchy/fluid just like the Dashboard.

    • I agree, if you’re just adding the social icons to the menu just add them directly to the menu and use a class to set the image. For this project the links we had social icons in the menu, a sidebar widget, and the footer, but to keep the example simple I just did the menu (and to show off the great filter wp_nav_menu_{menu-name}_items to customize a specific menu).

  5. Heya Bill! You’re tutorials and code examples for Genesis themes are fantastic! You’ve helped me think about creating custom child themes in a whole new way that has sped up my development time considerably. Thanks so much for that!

    Have a question about this tutorial, though. I’m curious how you would modify this to add a child theme settings page rather than adding the settings to the Genesis –> Theme Settings since that’s the preference for the folks at StudioPress when it comes to creating new settings.

    • Wow, I’ve never seen that link before. In that case I’d recommend you just copy how Genesis does it in /lib/admin/theme-settings.php, but for your own page.

      • Register your defaults
      • Register the actual settings field (store all your settings in one field)
      • Sanitize your settings
      • Create a subpage to Genesis with a do_meta_boxes() hook
      • Create your metaboxes

      I’ll revisit the tutorial or create a new one specifically about this.

  6. Bill, I love that every time I’m looking for a thing I need to do with Genesis, there you are with the answer… thanks!

  7. Putting this into practice now. And learning from your code int he core functions plugin and then the child theme – and trying to put it all into practice. One thing has me confused – I’ve added custom meta boxes to a file in child theme and called the file from the genesis setup hook in the child functions file, but the defaults aren’t working? And in looking for answers, I’m running into the CMB plugin you co-wrote, we do NOT need that with the genesis options right? It looks like I’ve written most ofthe code into the admin file, so I want to confirm that I dont need that core function plugin with the genesis theme options page?

    Thanks for any tips you can give me!

    • The CMB code is only for post-specific metaboxes (postmeta). This code is for site-wide metaboxes. So no, it isn’t required.

      The defaults will only work the first time the option is loaded. It basically says, if there’s no value in the database for this option, put the default value in there. Once you save the page (if you didn’t have defaults) then the option will now exist in the database as empty. So even if you specify a default, it won’t work.

      Try dropping your theme in a brand new WordPress website and see if it loads.

  8. Nice tutorial, Bill!

    Just a comment – but you should add the new settings directly to the $defaults array, not as a sub-array, eg like this:
    $defaults['new_setting'] = 'some text';
    $defaults['another_setting'] = 'some other text';
    etc

  9. Hi Bill,
    Thanks for this useful tutorial. I am relatively new to Genesis framework. So this will come handy.

  10. Great tutorial! One question. I have it set up so I have a field that would accept a shortcode. Then i want what is output in that to show up in a function used to show a slider on a template. Is that possible?

    Thanks

  11. It is not available in genesis 2.0.1. I am trying to add social icons in author box area as well but code is not being executed help ..!!

  12. Hi Bill Thanks for this!

    At first, I tried copying your code and save it to a file named social-settings.php and uploaded it to my child theme /lib/functions/ folder. However when I tried it, it doesnt work so I included the social-settings.php in my child theme’s function.php by inserting “include ‘lib/functions/social-settings.php’;” and it worked. Anyway just in case someone will have trouble as what I experienced so just sharing what I did..again thanks for the code!!! I’m using Genesis 2.0x btw.

    Cheers!

  13. Yes this is a first important things to do just after installing theme for better customization
    it plays awesome role in SEO of blog … i like genesis because it is very user friendly to handle all the way .
    thanks for the grate info .

  14. Great post Bill. This has changed the way we manage our sites. Tip for anyone managing writers and mass amounts of content — use this to construct “Company Name”, “Phone Number”, “Mobile Number”, etc. fields, construct shortcodes and have your writers use those shortcodes in their copy. I found this post because I got tired of correcting company names to the correct dba’s…correcting phone numbers to the correct syntax. This is great for consistency.
    —————————————-
    I’m having an issue with adding a Genesis Theme settings box like this for a script and am hoping someone else has had a similar issue that they’ve been able to work through.

    I need the textarea input similar to the header_scripts and footer_scripts, as I want to use this to store the Google Tag Manager & Conversion Tracking codes and output those in my theme. I’m using requires_unfiltered_html to sanitize the data. This works like a charm with the simple single line text field. But when I replace it with the textarea syntax located in geneses/lib/admin/theme-settings.php (used for header/footer scripts), things start getting wacky. Do those ‘genesis_scripts’ have dependencies I’m not accounting for or is my method wrong?

    https://gist.github.com/jonrivers/eb486bad7e3bc1c83a40

    Any insights are greatly appreciated.

  15. Bill, your tutorials and seminars are always the most clear and concise stuff out there. Thanks for getting me one more step down the road in using Genesis!

  16. Hi Bill!

    Thanks for this tutorial and all the other awesome tips and tricks for Genesis and WordPress. You are one of my go to sources when I need help putting something together, and I wanted to give you this shoutout. I’m getting much better with my coding, but I am still better at dissecting someone else’s code than creating it myself. But every time I do, I learn so much, and I am really starting to understand how it all works!

    Your above code rocks! You used it for two simple social links. I used it to create something I’ve been wanting to do for a while, and you made it easy. I took your code and added on to it, to create a company details box, with all the company info for a business (name, address, phone, email, logo, google maps, etc.) to use in my custon functions file to output the business information in the footer with schema markup.

    Gone are the days of doing repetitive tasks. Now on the next client site I build, all I have to do is upload two files to the themes directory, fill out the form, and voila, a fully functional footer with business information with schema markup, links, and copyright.

    Plus now I actually understand how the api and php work. Read about it, didn’t really get, did it and now I got it.

    Thanks again and I hope my creativity will inspire others to fork this code to make something awesome too.

    Doug

  17. Hi Bill,

    Thank you for awesome tutorials! This one however doesn’t seem to be working on recent Genesis Framework version. There are no errors, but the options don’t show up in theme settings menu.
    Any updates? 🙂

    Thanks,
    Luca

  18. Hi,

    I have a question. I am creating a child theme for genesis which will add new theme options say cthemeoption1. When I activate child theme – I can see & save cthemeoption1 with some value say value1. When I switch back to parent genesis framework obiviously cthemeoption1 is not present. Now if I again switch back to child theme what cthemeoption1 should contain ? It should have default value or value which was set earlier ?

    • I believe it will have the value set earlier. The data should be stored in the database, so once changing themes it will still be in there. Then when activating the child theme again, you’ll see the data so you’ll use that rather than the default.

  19. Works like a charm! One question here. Can I use these values using shortcode like [twitter_url] etc. in a post, page and widgets?

  20. Hi Bill! Thank you so much for this. I’ve already used it on a few child themes I’ve built with Genesis and it works perfectly 🙂

    One question: on the last child theme I built, sometimes when saving, ALL the custom fields to revert to their default values. This seems to happen randomly and I can’t figure out what’s causing it.

    I am pretty much doing exactly the same you did here (which has worked perfectly on several other child themes), just using many (20 or 30) custom fields instead of 2.

    • I’m sorry but I’m not sure what would cause that issue, especially if it’s random (not always).

      Maybe one of your fields is passing data in an unexpected way that’s corrupting the whole $_POST object so nothing gets saved correctly.

  21. Hi Bill! im still using this code and im wondering, how can i add the new option in customizer? Genesis automatically did that on default genesis setting, but not the custom option that this code created

    • Genesis doesn’t automatically add settings to the customizer. Genesis separately create the customizer functionality, and you’ll need to as well for your custom theme settings.

      I recommend waiting for the next release of Genesis, which should be out soon. There’s a simple filter for adding new and modifying existing customizer settings: genesis_customizer_theme_settings_config

Leave A Reply