Photo by 900hp
One of my favorite “under-the-hood” features of WordPress and Genesis is the ability to override almost any kind of option/meta: site options, post meta, user meta, term meta….
Make sure you are careful with these filters though. Themes and plugins will expect certain options/meta to be returned when they call a core function, and if you’re not careful you could break them. Make sure you only return your changes in the very specific instances in which you want them.
Here’s a few common use cases:
- Change the admin email on certain pages (site option)
- Change the default layout of the homepage (site option)
- Force a layout on the homepage (post meta)
- Turn the Genesis Author Box on automatically for author archives (user meta)
- Specify a default title for term archives (term meta)
Site options are anything stored in the wp_options database, and you typically access them using the
WordPress provides a filter for these options, called
pre_option_($key) (see wp-includes/option.php, line 36 in WP 3.4.1).
Example 1: Change the admin email on certain pages
As a simple example, let’s say you had an email link in your footer, and you wanted to modify the ‘admin_email’ option on blog posts to use the blog post’s author email (I probably wouldn’t use this approach, but it shows you how to use the filter).
Genesis has a lot of options, but instead of storing them all as individual entries in the database, it stores them as a single serialized array. This is great for performance, but it makes using the above filter difficult. So Genesis provides a filter for Genesis options and any other options that use the Genesis Settings API.
Example 2: Change the default layout of the homepage
You can set the site-wide default layout in Genesis > Theme Settings, which sets the Genesis option ‘site_layout’. But on the homepage you might want to have a different default layout. We’ll set this using the
genesis_pre_get_option_($key) filter (see lib/functions/options, line 57 in Genesis 1.8.2).
Since this is such a popular use, Genesis has already made functions that return all the built-in layouts, and you can see a list of them at the end of this post. We can replace the code above with this:
Please note that both the above code snippets are to be placed in front-page.php or home.php — whichever template file is responsible for your homepage.
WordPress provides a filter called
get_post_metadata (see wp-includes/meta.php, line 274 in WP 3.4.1) for modifying post meta.
Example 3: Force a layout on the homepage
The Genesis function that determines the page layout first checks the post’s meta field ‘_genesis_layout’, and if none is specified it uses the sitewide default (which is what we overwrote in the previous example). The code below overrides the post meta, so the user can’t change the layout on this page:
Again, this code is running in front-page.php or home.php — whatever is responsible for your homepage. Since the filter passes the $post_id, we could also run this in functions.php like so:
We’re now making sure the $meta_key matches the one we want AND we’re making sure $post_id is the page set to the front page in General > Reading. If you wanted this on your blog page instead, you could check $post_id against
get_option( 'page_for_posts' ).
WordPress provides a filter called
get_the_author_($key) (see wp-includes/author-template.php, line 112 in WP 3.4.1) for modifying author meta. You can use this to override any of the author meta from WP Core, and also any author meta added by themes and plugins.
Example 4: Turn the Genesis Author Box on automatically for author archives
If you have the Genesis theme installed and go to Users > Your Profile, there’s a checkbox that lets you specify if an author box should show up on your author profile and/or at the bottom of all your posts. These update the user meta fields genesis_author_box_archive and genesis_author_box_single, respectively.
This code will make genesis_author_box_archive always return true, so the author box it automatically shows up on all author archive pages:
You’ll notice I’m using a function called
__return_true(), but that I didn’t create that function. This is one of the WordPress core helper functions. See the end of this post for a list of more helper functions.
WordPress doesn’t have term meta, which is one of the few things it is lacking as a CMS. Genesis needed term meta for all its SEO and layout options, so it created term meta using the options table.
Genesis also added a filter,
genesis_term_meta_($key) (see lib/functions/options.php, line 228 in Genesis 1.8.2), used for modifying this meta.
Example 5: Specify a default title for term archives
On my photography blog, I have a taxonomy called “people” that I use for tagging people in photos. For taxonomy archives, Genesis has term meta for an Archive Headline and Description. I wanted to display a headline at the top of all the term archive pages, but didn’t want to manually create them.
Here’s a simple function I wrote that first checks to see if a headline has been provided, and if it hasn’t it uses “Photos of [person’s name]”.
- WP: pre_option_($key) in wp-includes/option.php, line 36
- WP: get_the_author_($key) in wp-includes/author-template.php, line 112
- WP: get_post_metadata in wp-includes/meta.php, line 274
- Genesis: genesis_pre_get_option_($key) in lib/functions/options.php, line 57
- Genesis: genesis_term_meta_($key) in lib/functions/options.php, line 228
__return_true()– returns the Boolean state of true
__return_false()– returns the Boolean state of false
__return_zero()– returns a value of zero (0)
__return_empty_array()– returns an empty array, as in array()
__return_null()– returns null (or void)
__genesis_return_full_width_content()– returns ‘full-width-content’
__genesis_return_content_sidebar()– returns ‘content-sidebar’
__genesis_return_sidebar_content()– returns ‘sidebar-content’
__genesis_return_content_sidebar_sidebar()– returns ‘content-sidebar-sidebar’
__genesis_return_sidebar_content_sidebar()– returns ‘sidebar-content-sidebar’
__genesis_return_sidebar_sidebar_content()– returns ‘sidebar-sidebar-content’