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.

4 thoughts on “Twenty Eleven and the Pluggable functions

  1. I’m not ignoring the updated post link–I already downloaded the first version and don’t know if I should remove it first if I want to download the other one. I am just trying to improve accessibility because I have been getting assistive text errors on my blog. In the process I found out I need a child theme to work with pagenavi. The child theme changed the appearance of my site and I’ve been trying to fix it ever since. I’m afraid this is over my head. Do I remove the first child theme first?

  2. This is by far the best explanation on how to get pagination to work for twenty eleven child themes. I installed WP PageNavi, WP PageNavi Style, applied your changes to functions.php and style.css, and it worked right off the bat. Quick and easy. Thanks!

Leave a Reply

Connections

Connect with Us
Follow Digital Raindrops on Twitter Join Digital Raindrops on Facebook
Share

Related Posts

Posted in Twenty Eleven

pluggable-image2_thumb.png

In April 2011 we wrote a post on pluggable functions, since then we have been looking at other functions like post classes, which we used in the first release of our photo blogging theme. While loitering over on the WordPress … Continue reading

Read More