Twenty Eleven and the Pluggable functions

In the early releases of the WordPress twenty eleven theme, the ‘twenty_eleven_content_nav’ function was not pluggable, so we raised a WordPress trac ticket and politely asked the developers to make the function pluggable for the WordPress child theme developers.

This was a minor tweak to the theme and we forgot all about it until we were reading another website post on adding PageNavi to a twenty eleven Child Theme, we thought we could now re-visit the solution using the updated pluggable function.


What are Pluggable Functions?

With the massive uptake on using child themes, the WordPress guru’s needed a way for developers to over-ride some of the twenty eleven parent theme functions, to do this they added two lines of code one before and one after to some of the theme function.

As an example if in our parent theme we had a function called ‘my_pluggable_function’  the code might look like this, notice the first line, in plain talk is says, if not ( ! = not ) the  function_exists ‘my_pluggable_function’ then load the parent function.

if ( ! function_exists( 'my_pluggable_function' ) ) :
function my_pluggable_function() {
    echo ‘This is my pluggable function!’;
}
endif;

Before pluggable functions we had to create a new function with a different name and edit all the calls to the old function, that could mean quite a few files had to be moved to the child theme and edited, but with the Pluggable function we can just check in the parent theme’s files to see if the function is pluggable, as in our example it is pluggable,  so how do we stop the parent themes function from being loaded.

In our child theme’s functions.php we just copy the code block from the parent, make our changes in the copied function, notice that we do not change the name, and the function is not inside any ‘after theme setup’ function.

if ( ! function_exists( 'my_pluggable_function' ) ) :
function my_pluggable_function() {
   echo ‘This is my pluggable function in the child theme!’;
}
endif;

What happens at runtime is WordPress will load the child themes functions first, when it finds a function with the same name in the parent code, the code call that looks to see if the function_exists(‘function_name’) if this returns a true, then the parent function is skipped!

Pagination

We are using the page navigation to show how we can use the pluggable functions, in a real scenario, at the moment we only get a normal text link, with no way of navigating lots of posts, that is where the pagination plugins come in handy.

By using a pluggable function we can change the navigation output and style website wide, on the home page, archive, category, search, in fact any page that displays a post list!

We have created a fully working twenty eleven child theme based on this post for you to download and investigate the code!

Twenty Eleven Paginate

Lets us now add pagination support, using wp-pagenavi and wp-paginate plugin support to our twenty eleven child theme, we just copy the code block ‘twenty_eleven_content_nav’ from the twenty eleven theme, to our child themes functions.php.

Child Theme’s Functions.php

if ( ! function_exists( 'twentyeleven_content_nav' ) ) :
/**  * Display navigation to next/previous pages when applicable  */
function twentyeleven_content_nav( $nav_id ) {
   global $wp_query;
   if ( $wp_query->max_num_pages > 1 ) : ?>
      <nav id="<?php echo $nav_id; ?>">
         <h3 class="assistive-text"><?php _e( 'Post navigation', 'twentyeleven' ); ?></h3>
         <div class="nav-previous"><?php next_posts_link( __( '<span>&larr;</span> Older posts', 'twentyeleven' ) ); ?></div>
         <div class="nav-next"><?php previous_posts_link( __( 'Newer posts <span>&rarr;</span>', 'twentyeleven' ) ); ?></div>
      </nav><!-- #nav-above -->
   <?php endif;
}
endif; // twentyeleven_content_nav

Then we add a couple of extra lines of code to call a new function that returns the plugin output, first we look for the function wp_pagenavi if we find this we can load pagenavi and exit, we fall through to the function wp_pageinate and then the default output.

if ( ! function_exists( 'twentyeleven_content_nav' ) ) :
/**  * Display new navigation to next/previous pages when applicable  */
function twentyeleven_content_nav( $nav_id ) {
   global $wp_query;
if ( $wp_query->max_num_pages > 1 ) : ?>
       <?php
       /**
       Call our new function to see if any pagination plugins are active
       If one of the plugins is active then exit this function
       If none of the plugins are active use the default styles
       */
      if( dr_custom_navigation( $nav_id ) ) return;
      ?>
      <nav id="<?php echo $nav_id; ?>">
         <h3 class="assistive-text"><?php _e( 'Post navigation', 'twentyeleven' ); ?></h3>
         <div class="nav-previous"><?php next_posts_link( __( '<span>&larr;</span> Older posts', 'twentyeleven' ) ); ?></div>
         <div class="nav-next"><?php previous_posts_link( __( 'Newer posts <span>&rarr;</span>', 'twentyeleven' ) ); ?></div>
      </nav><!-- #nav-above -->
   <?php endif;
}
endif; // twentyeleven_content_nav

dr_custom_navigation

As we can see we only added a line call to a new function, we have our code in a new function to make our changes easy to track, also notice that we have changed the <nav id= to <nav class=. this is so we could add our own styles to the classes in the child themes style.css.

function dr_custom_navigation( $nav_id ) {
   /* Is the Pagenavi plugin active ? */
   if( function_exists('wp_pagenavi') ) : ?>
      <nav class="<?php echo $nav_id; ?>">
         <?php wp_pagenavi(); ?>
      </nav>
      <?php return true; //Get out of here!
   endif;
   /* Is the Paginate plugin active ? */
   if( function_exists('wp_paginate') ) : ?>
      <nav class="<?php echo $nav_id; ?>">
         <?php wp_paginate(); ?>
      </nav>
      <?php return true; //Get out of here!
   endif;
   return false;
}

WP Paginate

WP PageNavi

There we are a little introduction to pluggable functions, and support for two of the top pagination plugins.

Notices

We do require your feedback to improve our themes and tutorials, please leave your comments good or bad.

Code disclaimer information

If this document contains programming examples, www.DigitalRaindrops.net grants you a nonexclusive copyright license to use all programming code from which you can generate similar functions tailored to your own specific needs.

All sample code is provided by http://DigitalRaindrops.net for learning illustrative purposes only.

These examples have not been thoroughly tested under all conditions. www.DigitalRaindrops.net, therefore, cannot guarantee or imply reliability, serviceability, or function of these examples.

All programs contained herein are provided to you “AS IS” without any warranties of any kind. The implied warranties of non-infringement, merchantability and fitness for a particular purpose are expressly disclaimed.

Membership

Registration and Membership is no longer required for downloading files or interacting with Digital Raindrops, posting a comment or topic in the forum does use Captcha to reduce spammers.

This website is a tool to support and promote WordPress and Artisteer theme development, please support, share and give credit for any benefits you gain from the tutorials on this website.

Add WP Pagenavi Twenty Eleven Child Theme

While answering a topic on the WordPress Support forum lead us to look at the Twenty Eleven function ‘twentyeleven_content_nav( $nav_id )’ in the functions.php file.

A lot of the functions in the parent theme can be replaced with functions in the child theme, we will see comments like  /*  To override this link in a child theme */, but this function does not have this option, we have raised a ticket with WordPress Trac and hope it will be included at a later date.

Continue reading