In this tutorial, I am going to teach how to correctly add child theme options with the Genesis Framework.
Theme options are quite popular because they add perceived value to themes and allow users to customize the themes without having to touch any code. We will be adding these child theme options to the Genesis Framework following the standards provided in this article on StudioPress’ website.
If you want to go ahead and download the source files, click this link here to download them.
Setting Up Our Directory Structure
The first thing we need to do is setup our directory and file structure. Make sure that your child theme already has a
functions.php file as we will be using them later on in this tutorial. While in the root of your child theme, create a folder called
lib. Within the
lib folder, create another folder called
admin. And finally, within the
admin folder create a file called
childthemename-theme-settings.php. Simply replace
childthemename with your custom child theme’s name.
Next, go to your child theme’s
functions.php file and place this code right below the
require_once( TEMPLATEPATH . '/lib/init.php' ); line:
require_once( CHILD_DIR . '/lib/admin/childthemename-theme-settings.php' );
Remember to replace
childthemename with your custom child theme name!
Now that you have your structure in place, let’s begin building out our child theme options in our new file.
Setting Up the File Structure and Defining Constants
Let’s begin by setting up the file structure and defining any constants that we will use throughout our settings page (in this tutorial we will use just one constant). Copy and paste the following code into your
In order to follow best coding standards, we should make sure that we comment everything. In the commented section, simply change anywhere you see CT Settings to your custom child theme name. You should also change the author and copyright lines to reflect your own work.
Next we need to define our settings constant. Defining constants is beneficial because if we for some reason decide to change the name of our setting, we only have to change one line instead of searching through the entire document and changing every reference. Copy and paste the following code below your commented block:
define( 'CTSETTINGS_SETTINGS_FIELD', 'ct-settings' );
This will define a constant to use for our settings field. Once again, change
ct-settings to your custom child theme’s name. Now that we have defined our settings field, we can easily grab options using Genesis’
genesis_get_option( 'childthemename_custom_option', CTSETTINGS_SETTINGS_FIELD );
Setting Up Default Options
Let’s go ahead and register our default options for our child theme settings. We always want to store our options in an array in order to optimize performance. Always remember to prefix your options with your child theme’s name! Copy and paste the following code into your
Once again, remember to change out
ctsettings to your child theme’s custom name. In this block of code, we are building out a function that will be used to register and store our child theme settings in the database. Our settings in this tutorial will be used to add Facebook Like, Tweet and Google+ buttons to our posts. On return, we have a filter setup so that default options can be added or removed using the
ctsettings_default_theme_options filter. Now we are -almost- ready to register our settings and store our defaults in WordPress, but before we do this, we need to make sure that these options are properly sanitized using Genesis’ new sanitization class and filters.
Sanitizing Our Options
We always want our options to be secure, and in accordance to a security audit for Genesis, a new sanitization class was birthed that allows us to easily sanitize and secure our options for use. There are currently 4 sanitizing filters that can be utilized:
requires_unfiltered_html. For this tutorial, we will only be using the
one_zero filter for our checkboxes. Copy and paste the following code in your
We are added our options to be sanitized into the
genesis_settings_sanitizer_init action hook. The
genesis_add_option_filter takes 3 parameters:
$filter option is the specific one we would like to use, which I listed previously. The
$option parameter is for the settings field used in the sanitizer, which in this case is the one we defined at the beginning of our file,
CTSETTINGS_SETTINGS_FIELD. The third parameter
$suboption is an array of options that are tied to our settings field. Thus we have the code above! Now we can finally register and store our default options.
Registering, Storing and Restoring Our Default Settings
Copy and paste the following code below your previously pasted code in your
We hook this function into the
admin_init hook. This function registers our settings and adds them into the database. We also add the reset option functionality into this function as well. We test if the reset button has been successfully submitted, and if so, we update our option field back to the defaults and refresh the page so that the defaults are present again (using the
genesis_admin_redirect function). Remember to change
CTSETTINGS_SETTINGS_FIELD to the constant you defined at the beginning of the file.
Adding Admin Notices for Updated Settings
Our last piece of overhead is to add in our admin notices when our settings are updated. This is the last piece of code needed before we actually begin to build out our page. After this, you will have laid the entire framework for your child theme options. Copy and paste the following code into your file:
This function hooks into the
admin_notices hook and alerts your users when they have either updated or reset their settings. This is a pretty straightforward function so I won’t go into great detail explaining it. Basically we check to make sure we are on the correct page, and if so, we then display messages based on the button the user has selected to update the child theme options. Now let’s go and build out our page!
Creating Your Child Theme Options Page
Finally we are ready to create our child theme’s options page. Copy and paste the following code into your file:
By hooking into the
admin_menu action hook, we are able to create our child theme options page. This page is created as a sub-menu page of the parent Genesis, as specified by the child theme standards document on StudioPress’ website. We setup a global variable called
$_ctsettings_settings_pagehook so that we load our styles, scripts, metaboxes and forms only on our page. The last parameter of the
add_submenu_page function is the callback function that will hold our form that displays and submits user inputted options.
Also in the function we are hooking into the
load-$hookname action hook, which runs specified callback functions on the specific pagehook. For this tutorial, I have commented out the
ctsettings_settings_styles action because we will not be using custom styles. If you wanted to add a custom stylesheet, you would uncomment that line and enqueue your admin stylesheet. Now we need to populate those callback functions that we just added to the action hooks.
Enqueuing Our Scripts
First we will populate the
ctsettings_settings_scripts function. Copy and paste the following code into your file:
This function simply enqueues the necessary scripts needed to make our page function like the Genesis theme option page functions. No more explanation necessary. 🙂
Adding Our Metaboxes to Our Child Theme Options Page
Next we need to populate our
ctsettings_settings_boxes function. Copy and paste the following code into your file:
This function adds our metabox into the system. Once again, we access the global variable
$_ctsettings_settings_pagehook to ensure that we are doing this only on our child theme’s options page. In this tutorial, the add_meta_box function is taking 5 parameters:
$context. We now need to populate our callback function
ctsettings_social_metabox so that we can see our new metabox.
Creating and Displaying Our Metabox
Copy and paste this code into your file:
Phew, this is a giant chunk of code, but don’t be afraid. All we are doing is setting up our input fields to display our options. What is important is that you make sure that the constant
CTSETTINGS_SETTINGS_FIELD matches the constant you set at the beginning of the file and the each individual option (such as
ctsettings_google_link) matches the default options you set at the beginning of the file. Now, let’s make our screen one column to mimic how Genesis has its theme options and get our metabox displayed!
Setting the Screen to One Column and Displaying Our Options
Copy and paste the following function into your file. It will set the screen column to 1 for our options page:
Now let’s display our form and metaboxes, shall we? Copy and paste the following code into your file:
Finally, we are able to actually display our form. We use the
settings_fields function to output our security nonces and forms. We also add our submit/reset buttons to the top of the page. We use the
do_meta_boxes function to fire and execute our metaboxes. Finally, we add some jQuery to make sure that our metaboxes toggle and move like they should. Now you can go into your Dashboard, refresh the page and check out your new child them options page!
Now your users can select if they want to have any of these social sharing options displayed on their posts. Now we can create the functions that will conditionally add these social sharing options.
Adding in the Functionality to Your Child Theme’s functions.php File
For this tutorial, we are going to hook into the
genesis_before_post_content action hook to add our social buttons. There are a wealth of other hooks that you can access, but we will use this one for this tutorial. Copy and paste the following code into your child theme’s
All this code is doing is checking to see if our option has been checked. If it has been checked, it display s the appropriate social sharing button. This bit of code also includes div classes so that you can these as needed.
And there you have it folks! You have no successfully and securely added child theme options to the Genesis Framework! Now go have some fun, tell all your friends and don’t forget to ask me questions if you have them. 🙂
Once again, here are the source files. Click on this link to download them now!