Skip to main content

The Right Way to Override Theme Functions

I started building my first WordPress site last week and almost immediately starting customizing the theme. Rather than editing the default theme directly, however, I created a child theme, basing it off one of the many theme frameworks available for WordPress. Creating the child theme was painless, and there is plenty of information on how to do so.

Pretty soon though, I got to the point where tweaking CSS rules wasn’t going to cut it: I needed to go deeper. I needed to change some of the functions in the parent theme. But while there was plenty of information on creating child themes, information on overriding theme functions was nowhere to be found. The closest I came was this helpful post.

This is an odd disconnect. How could there be so much information on one part of a best practice (creating a child theme), but basically none on how to make that best practice really work?

I can’t answer that question. But I do have my own version of how to override theme functions in WordPress – The Right Way.

The Child is the Father of the Man

(Bonus points if you get the reference.)

Here’s the basic outline for what I think is the Right Way To Do It:

  1. Copy (in full) the function you want to override from the parent theme.
  2. Paste it into functions.php in the root of your child theme’s folder. If functions.php doesn’t exist, create it.
  3. Rename the function from parent_theme_function to child_theme_function.
  4. Deactivate the parent function.
  5. Activate the child function.

The first three steps are self-explanatory, so I’ll just cover the last two steps.

Deactivate the Parent Function

There are actually two steps here. First, create a one-line function that removes the parent function from its “phase”. Then, add that one-line function to WordPress’ bootstrap phase (‘init’), so that the parent function actually gets removed.

Confused? Don’t worry. Here’s an example of how you would remove the thematic_blogtitle() function from the Thematic theme. Code comin’!

// Remove the default Thematic blogtitle function
function remove_thematic_actions() {
    remove_action('thematic_header','thematic_blogtitle',3);
}
// Call 'remove_thematic_actions' (above) during WP initialization
add_action('init','remove_thematic_actions');

In this case, we are removing the parent theme function (thematic_blogtitle) from the thematic_header phase.

How do you know what the proper phase is? Look for a line like this in the parent function’s theme files:

add_action('phase','function', 'priority');

You can usually find this right after the function’s declaration. The line that adds thematic_blogtitle looks like this:

add_action('thematic_header','thematic_blogtitle',3);  

Note that you have to use the same priority that was used to add the function in the parent theme (in this case, 3) when you remove it. If no priority was used in the original add_action, you can skip it.

Activate Your Child Function

To replace thematic_blogtitle, we just need to tell WordPress to call our child theme function in the place where it used to call the parent theme function. So, if our new function were called fancy_theme_blogtitle, we would add the following to functions.php:

add_action('thematic_header','fancy_theme_blogtitle', 3);

Save functions.php and voila! The code from fancy_theme_blogtitle is run instead of the code from thematic_blogtitle, and we didn’t have to hack the parent theme. This is crucial, because if there is ever an update to Thematic, we can get all the upgradey goodness without having to worry about how it will affect our child theme. Excellent!

All Together Now

Putting all the code together:

// Removes thematic_blogtitle from the thematic_header phase
function remove_thematic_actions() {
    remove_action('thematic_header','thematic_blogtitle',3);
}
// Call 'remove_thematic_actions' during WP initialization
add_action('init','remove_thematic_actions');

// Add our custom function to the 'thematic_header' phase
add_action('thematic_header','fancy_theme_blogtitle', 3);

Know a Better Way?

As I stated previously, I’ve only been using WordPress for about a week. If you know a better way to do this, by all means, please let me know!

Awesome!!!

Thanks so much! I just ran into exactly this problem and was just about to give up and hack the Thematic functions up.

Your fix saved me some headaches. I’ll be trying it out now…

modify functions.php

I’m trying to separate the parent of the child theme, I try to modify functions.php (hybrid theme, and child theme), and doing it alone.
Hybrid theme is the parent, Critical theme is the child, i try to make one but with the characteristics of the child,
is this possible?

dsf

You can join the theme club for free or pay a minimal yearly fee to get help and in-depth tutorials on customizing your site.

Wow

After burning a lot of time looking for a way to custom replace a footer display function without touching the update-prone php code of the parent theme, I thankfully found this page and gave its info a try in a WP 3.0 child theme. It worked beautifully! Thank you.

A small modification

This works great for some, but not all themes because in some cases the parent functions.php contains functions that kick in too quickly. For example if you were to try to replace twentyten_widgets_init() you would not be able to with the script above. That’s because the child functions.php is called before the parent functions.php, so even if you unhook the function it gets rehooked later on. To fix this change init to after_setup_theme in the remove action call like this:

// Call 'remove_thematic_actions' during WP initialization
add_action('after_setup_theme','remove_thematic_actions');

I found this tip at http://ottopress.com/2010/wordpress-protip-child-themes/

What if this was the code I wanted to override?

Hi,
In my theme the code below is what I would want to override in a child theme functions.php… Using your method… How would I do this? … (I’m no php ace :-(

// Sidebars:
if ( function_exists('register_sidebar') ) {
    register_sidebar(array(
        'name'=>'Left Sidebar',
        'before_widget' => '<div id="%1$s" class="widget %2$s"><div class="menutop">&nbsp;</div>',
        'after_widget' => '<div class="menubottom">&nbsp;&nbsp;</div></div>',
        'before_title' => '<div class="widget-title"><h3>',
        'after_title' => '</h3></div>',
    ));
    register_sidebar(array(
        'name'=>'Right Sidebar',
        'before_widget' => '<div id="%1$s" class="widget %2$s"><div class="menutop">&nbsp;</div>',
        'after_widget' => '<div class="menubottom">&nbsp;&nbsp;</div></div>',
        'before_title' => '<div class="widget-title"><h3>',
        'after_title' => '</h3></div>',
    ));
    register_sidebar(array(
        'name'=>'Left Inner Sidebar',
        'before_widget' => '<div id="%1$s" class="widget %2$s"><div class="menutop">&nbsp;</div>',
        'after_widget' => '<div class="menubottom">&nbsp;&nbsp;</div></div>',
        'before_title' => '<div class="widget-title"><h3>',
        'after_title' => '</h3></div>',
    ));
    register_sidebar(array(
        'name'=>'Right Inner Sidebar',
        'before_widget' => '<div id="%1$s" class="widget %2$s"><div class="menutop">&nbsp;</div>',
        'after_widget' => '<div class="menubottom">&nbsp;&nbsp;</div></div>',
        'before_title' => '<div class="widget-title"><h3>',
        'after_title' => '</h3></div>',
    ));

Hope you can help!
 Ken

Sorry!

The code tags didn’t seem to work…

Ken

unregister_sidebar()

Hi Ken,

I’m not sure whether you want to remove the sidebars or edit the before and after wrappers, but either way, I think you want to use unregister_sidebar().

For example, suppose you want to wrap titles in <h2>s in the Right Inner Sidebar instead of the current <h3>s. First, you would unregister the Right Inner Sidebar:

unregister_sidebar('Right Inner Sidebar');

Then, you would re-add the sidebar with your modifications:

register_sidebar(array(
    'name'=>'Right Inner Sidebar',
    'before_widget' => '<div id="%1$s" class="widget %2$s"><div class="menutop">&nbsp;</div>',
    'after_widget' => '<div class="menubottom">&nbsp;&nbsp;</div></div>',
    'before_title' => '<div class="widget-title"><h2>', /** Changed to <h2> **/
    'after_title' => '</h2></div>', /** Changed to <h2> **/
));

All of this would be done in functions.php in your child theme.

...

I only would like to thank you for the explaining but my reply seems to be at a wrong place… :-)

Override function by copying, if using function_exists() call

Some functions can be overridden simply by copying them into your functions.php of your child them, keeping the same name but making changes to the function. This works if the parent theme function is wrapped in “if function exists”.

twenty_ten_setup() is an example

  • To override twentyten_setup() in a child theme, add your own twentyten_setup to your child theme’s functions.php file.

if ( ! function_exists( 'twentyten_setup' ) ):

I found this at:
http://ideapress.googlecode.com/svn-history/r9/trunk/functions.php

where it states:
When using a child theme (see http://codex.wordpress.org/Theme_Development and http://codex.wordpress.org/Child_Themes), you can override certain functions (those wrapped in a function_exists() call) by defining them first in your child theme’s functions.php file. The child theme’s functions.php file is included before the parent theme’s file, so the child theme functions would be used.

This is incentive to always use function_exists() when writing functions for themes.

Also look for childtheme_override_

Hi Daniel,

Excellent tip. If you’re using twentyten as a base theme, I would certainly recommend using that method to override base theme functions.

Thematic handles the situation a little differently: instead of checking to see if the function has already been defined, Thematic looks for a specially named override function. Override functions in Thematic take the following format:

function childtheme_override_name_of_function_to_override()

Note that the name of the override function literally begins with childtheme_override. That’s not a placeholder as it would be in Drupal. To restate:

  • If your child theme is named graviton, then the name of the override function begins with childtheme_override.
  • If your child them is named nanobot, then the name of the override function still begins with childtheme_override.

Kind of lame, but hey. It’s a system.

Overriding functions

Nice and succinct - thank you. Just what I needed to know

so helpful

thaks for this post!

thaks for this post!

thaks for this post!

Most helpful

Exactly what I needed to know. Using hooks is a great technique, but there is a lack of “how-to” explanations. Thanks!

THANKYOU!!THANKYOU!!THANKYOU!

THANKYOU!!THANKYOU!!THANKYOU!!THANKYOU!!THANKYOU!!THANKYOU!!THANKYOU!!THANKYOU!!THANKYOU!!

In my child theme, I want to

In my child theme, I want to override this so I do this in the child theme’s functions.php file:

function childtheme_entry_title() {
.. my custom code here ..
echo apply_filters( ‘childtheme_entry_title’, $title );
}
add_action( ‘hybrid_before_entry’, ‘childtheme_entry_title’ );

Now, I get 2 entry titles on my posts - 1 from the Hybrid functions and 1 from my child theme functions.

How do I override the hybrid_entry_title() function with my childtheme_entry_title and still use the hybrid_before_entry hook?

Thanks in advance, PHP gurus.

Problem

I’m having the problem that when I add an override function in thematic, ie:

function childtheme_override_blogtitle() {
echo ’

override of blog title

’;
}
 add_filter(‘thematic_header’,’childtheme_override_blogtitle’);

the blog-title div is not added in the location that the standard blog-title div is; rather, it is appended at the end of the header. this doesn’t actually make much sense that this is happening to me at all… ideas?

figured it out!

i needed to set the priority in my add action call, ie:

function childtheme_override_blogtitle() {
echo ’

override of blog title

’;
}
 add_filter(‘thematic_header’,’childtheme_override_blogtitle’,3);

i had to add the 3!! not sure why. any ideaS?

Works perfectly with the Yoko Theme

I’m creating a child theme for the Yoko Theme and your code worked for me perfectly. Thanks so much!

thanks for this, i installed

thanks for this, i installed twentyeleven a year back and gave up as nobody explained the purpose of child themes and why they were useful if going to add and remove functions.

so now i know the main reason for a child theme is for adding functions and removing functions safely without editing the parent theme.

Then again, is there any difference to simply copying over an entire theme to a new folder and just editing that theme?

whats the best advantage with a child theme?

Hey there, I needed to add

Hey there,

I needed to add this to my child functions.php file. I am not sure how to make this not call from the parent functions.php file.

function oxygen_commentform_args( $args ) {
$args = array(
‘fields’ => apply_filters( ‘comment_form_default_fields’, $fields ),
‘comment_field’ => ’

’,
‘must_log_in’ => ’

’ . sprintf( __( ‘You must be logged in to post a comment.’, $domain ), wp_login_url( get_permalink() ) ) . ’

’,
‘logged_in_as’ => ’

’ . sprintf( __( ‘Logged in as %2$s.’, $domain ), admin_url( ‘profile.php’ ), esc_attr( $user_identity ) ) . ’ ’ . __( ‘Log out →’, $domain ) . ’

’,
‘comment_notes_before’ => ”,
‘comment_notes_after’ => ”,
‘id_form’ => ‘commentform’,
‘id_submit’ => ‘submit’,
‘title_reply’ => __( ‘Troll us…’, $domain ),
‘title_reply_to’ => __( ‘Leave a Reply to %s’, $domain ),
‘cancel_reply_link’ => __( ‘Click here to cancel reply.’, $domain ),
‘label_submit’ => __( ‘Post Comment →’, $domain ),
 );

return $args;

 }

How to override a function in functions.php that is not wrapped?

When using a WordPress child theme can anyone explain how to override a function that is contained in the parent them but not wrapped with in an if ( ! function_exists ? In this scenario, we don’t want to modify the parent theme’s functions.php since it could become overwritten by a theme update.

Thanks! This Worked Great

Thanks for this write-up on removing the parent functions from executing. Exactly what I needed to remove a couple meta tags that were causing errors in the W3C validator (seems like some people like to freak out because the validator shows a few inconsequential errors - sigh / rant over).

Anyways, very useful write up! Thanks again!

Thanks!

Many thanks for sharing this information!
I’ve applied it for a child theme of Trim (elegant themes) and worked perfectly.

changing header in Twenty Eleven

I’ve had all kinds of problems after creating a child theme for 2011 when I tried to put a new image in the header. I read elsewhere about how to use functions.php to do this, and applied it, but got the message

fatal error: Cannot redeclare twentyeleven_excerpt_length() (previously declared in /home/idahoo5/public_html/wp-content/themes/twentyeleven-child/functions.php:335) in /home/idahoo5/public_html/wp-content/themes/twentyeleven/functions.php on line 337

I deleted the child and am preparing to start over.

Can I use your step by step method at the beginning of your article to change the header?

thanks for an informative article.

Joe

PHP help for noob please

OK So I need some help, I have tried to understand but being a PHP noob, I an getting nowhere fast. I have the following code in my PARENT functions.php file, and I need to override 1 small piece

// Slider options
$slider_options = $this->getPostOptions('slider');

    // Items
    $content = $slider_options->addGroup('content', __('Content', 'website'), '', 'normal');
        $content->addOption('group', 'items', array(), __('Slider items', 'website'), '', array('multiple' => true, 'strict' => false));

    // Additional banner 1
    for ($i = 1; $i <= 2; $i++) {
        $group = $slider_options->addGroup('banner_'.$i, sprintf(__('Additional banner %s', 'website'), $i), __("It's displayed only if the &quot;slider + two banners&quot; type is used.", 'website'), 'normal');
            $group->addOption('text', 'caption', '', __('Caption', 'website'));
            $group->addOption('group', 'color', 'white', __('Caption color', 'website'), '', array('options' => array(
                'white' => __('White', 'website'),
                'black' => __('Black', 'website')
            )));
            $group->addOption('image', 'image', '', __('Image', 'website'));
            $group->addOption('codeline', 'link', '', __('Link', 'website'));
    }


The only thing I need to change is on this line

// Additional banner 1
for ($i = 1; $i <= 2; $i++) {

I need to overide the “2” and make it a “3”. I want to do this in a child theme, so my client can keep the core updated without killing the additional banner this adds, but when I try my website just wont load, no error or anything. If i delete the function.php out of the child theme, it loads fine, so there is something in my child functions.php killing the whole site.

At the risk of being laughed at, my child theme php is below. I know it have it majorly wrong, so help would be appreciated.


<?php
/**
* @package WordPress
* @subpackage Website_Theme
* @since Website 1.0
*/

// —————————————————————————–

function remove_addOption() {
remove_filter( ‘Slider items’, ‘website’ );
 }

// —————————————————————————–

// ———————————————————————

// Slider options
$slider_options = $this->getPostOptions(‘slider’);

// Items
$content = $slider_options->addGroup(‘content’, __(‘Content’, ‘website’), ”, ‘normal’);
$content->addOption(‘group’, ‘items’, array(), __(‘Slider items’, ‘website’), ”, array(‘multiple’ => true, ‘strict’ => false));

// Additional banner 1
for ($i = 1; $i <= 3; $i++) {
 }

// —————————————————————————–

add_action( ‘after_setup_theme’, ‘remove_addOption’ );

?>

Any help would be greatly appreciated.

Great tutorial. Thanks.

Great tutorial. Thanks. Didn’t work the first time round for me with Twenty Twelve theme, but a tiny tweak and it works great!

You are awesome!

Dude, you are fucking awesome!

I’d been dealing with this same problem for 24 hours now, I was about to give up, then luckily I found this post and it saved my day!

Like you, I can’t believe there isn’t better documentation on how to override parent functions.

Your system rocks!

Julián HR

how to use filters in themantic

you tut is good and use full please can you tell me how to use filters in thematic theme, i want to edit my thematic child themes of my site.

Child Theme - Change Home Button to "Blog"

Hi,

I am trying to change the Home button from TwentyEleven to read “Blog”.

I have set up a child theme but I am really new at php and not having much luck.

I have the following so far in functions.php file

<?php

if ( ! function_exists( ‘twentyeleven_page_menu_args’) ):

function twentyeleven_page_menu_args( $args ) {
$args[‘show_home’] = false;
return $args; }

?>

Any help would be greatly appreciated as I am going nuts.

Cheers

Diamond

Cormac McCarthy Quote

The child is the father of the man” comes from the first page of Cormac McCarthy’s Blood Meridian, the best novel I have ever read.

Modify files from wp-includes

For some reasons i’ved changed the nav-menu-template.php.
My problem is when new updates are comming up for wordpress because it could change my modifications.
So the only thing for me to do is to add the function in my child theme. But i can’t.
I managed to change different function from the parent (Twenty eleven theme) but couldn’t do the same for
function in wp-includes.
Any ideas?

thx

this worked 1st time for me!

this worked 1st time for me! Thanks a lot!

Thanks for this part of code.

Thanks for this part of code. this is exactly what I needed

Parent-theme functions.php f

Parent-theme functions.php


function twentytwelve_setup() {

set_post_thumbnail_size( 624, 9999 ); // Unlimited height, soft crop

}
add_action( ‘after_setup_theme’, ‘twentytwelve_setup’ );

Child-theme functions.php


function mds2013_setup() {

set_post_thumbnail_size( 980, 9999 ); // featured-image width equals site width 

}
add_action( ‘after_setup_theme’, ‘mds2013_setup’ );

So far i THINK i have everything right.

Here’s where i’m stuck.


function remove_twentytwelve_actions() {

remove_action('what_goes_here?', 'and_possibly_here?');

}
add_action ( ‘init’, ‘remove_twentytwelve_actions’ );

Am i removing ‘after_setup_theme’ and ‘twentytwelve_setup’ OR am i removing ‘set_post_thumbnail_size( 980, 9999 )’ ? or all of them in a specific order? I’m sure it’s an easy solution but it’s the only thing I haven’t understood clearly from the tutorials i’ve read and thus can’t progress with my work.

Thankyou.

Extremely Helpful

This should be part of the codex. I’ve always just gone in and torn apart the themes I used, but this time I wanted to do it right. I’m using a complicated theme with a lot of include files, so it wasn’t clear to me how to override individual functions. You saved me a ton of time.

What if...

That's a good one, thanks for sharing. But I was wondering what if the parent function is not associated with any phase? For example, it is simply called in the template...

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Post new comment

The content of this field is kept private and will not be shown publicly.
  • You can use Markdown syntax to format and style the text. Also see Markdown Extra for tables, footnotes, and more.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Allowed HTML tags: <a> <em> <strong> <cite> <img> <code> <ul> <ol> <li> <dl> <dt> <dd> <pre> <h1> <h2> <h3> <h4> <h5> <h6>
  • Lines and paragraphs break automatically.
  • Adds typographic refinements.

More information about formatting options