I have just finished converting most (all?) of my posts from various blogs around the intertubes into WordPress. My previous blog on this domain was running Oxite. I created a theme called ‘Titus’ (yeah, I know) for Oxite that included a little jQuery ‘Slider’ plugin that I wrote. The control shows my last ‘n’ number of twitter posts, one at a time in a rotating fashion. I named it slider because I originally intended for the content to ‘slide’ up from the bottom continuously. Instead, I decided to fade them in/out. I was too lazy to rename it after I decided on my desired effect. After moving to wordpress, I was slightly upset that I was losing my hard work. However, this was a jQuery plugin so I didn’t see why this couldn’t just plug into my WordPress theme. I’m NOT a PHP developer, nor do I pretend to know how to do anything in WordPress. That said, I forged forward in my attempt to get this plugin working. You should see this plugin working right now on this site (unless you are reading this through RSS).

First let’s define the content of my plugin. I have a Javascript file containing my plugin, a CSS file containing the styling I’m using on the site, a little HTML markup to add my ‘placeholder’ for twitter feed, and of course the dependency on jQuery.

Installing jQuery into your Theme

First let’s tackle the jQuery item.  A current version of the WordPress distribution includes jQuery. The trick is to include jQuery in your site. After a little investigation I found that jQuery was already ‘registered’ in WordPress code, but does not, by default, render to the browser.  Somewhere in /wp-includes/script-loader.php you’ll find:

$scripts->add( 'jquery', '/wp-includes/js/jquery/jquery.js', false, '1.3.2');

This line registers the script we want in a dictionary with the key ‘jquery’. After digging further, I found a funcation called ‘wp_enqueue_script’ in /wp-includes/functions.wp-scripts.php.

/**
 * Enqueues script.
 *
 * Registers the script if src provided (does NOT overwrite) and enqueues.
 *
 * @since r16
 * @see WP_Script::add(), WP_Script::enqueue()
*/
function wp_enqueue_script( $handle, $src = false,
                            $deps = array(),
                            $ver = false,
                            $in_footer = false ) {
   global $wp_scripts;
   if ( !is_a($wp_scripts, 'WP_Scripts') )
      $wp_scripts = new WP_Scripts();
   if ( $src ) {
      $_handle = explode('?', $handle);
      $wp_scripts->add( $_handle[0], $src, $deps, $ver );
      if ( $in_footer )
         $wp_scripts->add_data( $_handle[0], 'group', 1 );
   }
   $wp_scripts->enqueue( $handle );
}

I put two-and-two together and with a little trial and error, I added the following line to /wp-content/themes/inove/header.php right before the call to wp_head():

<?php wp_enqueue_script('jquery'); ?>

This method gets the script location from the dictionary and renders a script tag with the location details.

Installing the slider jQuery Plugin

If the core did not register our script in the dictionary, we can provide the location details ourself with a second parameter. That is precisely what I needed to do to get the slider.js file added to the template. I added the following line just after the previous line I added in header.php.

<?php wp_enqueue_script('slider',
                      (get_bloginfo('template_url') . '/js/slider.js') ); ?>

The contents of this file are:

function($) {
   $.fn.twitterClient = $.fn.twitterClient = function(params) {
      var t = $.extend({}, $.fn.twitterClient.defaults, params);
      $(this).append('<ul id="twitter_update_list"><li></li></ul>');
      $.getScript("http://twitter.com/javascripts/blogger.js");
      $.getScript("http://twitter.com/statuses/user_timeline/"
                   + t.userName
                   + ".json?callback=twitterCallback2&count="
                   + t.tweetCount,
                   function() {
                      var list = $("ul#twitter_update_list");
                      stopTick(list);
                      list.items = $("li", list);
                      list.items.not(":eq(0)").hide().end();
                      list.currentitem = 0;
                      startTick(list);
                  }
      );
      startTick = function(list) {
         list.tick = setInterval(
            function() { tickFunction(list) },
            (t.delaySeconds * 1000)
         )};
      stopTick = function(list) {
         clearInterval(list.tick);
         };
      tickFunction = function(list) {
         if (list.pause) return;
         list.pause = true;
         $(list.items[list.currentitem]).fadeOut("slow",
            function() {
               $(this).hide();
               list.currentitem = ++list.currentitem % (list.items.size());
               $(list.items[list.currentitem]).fadeIn( "slow",
                  function() {
                     list.pause = false;
                  });
        });
     };
     this.each( function() {
                 if (this.nodeName.toLowerCase() != "ul") return;
                }).addClass(t.cssClass)
             return $("ul#twitter_update_list");
     };
     $.fn.twitterClient.defaults = {
         userName: null,
         tweetCount: 10,
         delaySeconds: 5,
         cssClass: "twitterClient"
     };
})(jQuery);

Next, I needed to add my styles for the twitter stream into my template. A method intuitively similar to that for scripts was found called ‘wp_enqueue_style’ that allowed me to register my CSS for rendering:

<?php wp_enqueue_style('slider',
                     (get_bloginfo('template_url') . '/js/slider.css') ); ?>

The contents of this file were:

/*ID:   slider  Elements: slider UL, slider LI, slider LI A */
#slider {
      position: relative; top: 5px;  width: 470px;  color: #bbbbbb;
}
#slider ul, #slider li{
   margin:0;  padding:0;  list-style:none;
}
#slider li {
   width:470px;  height:70px;  overflow:hidden;
}
#slider li a {
   text-decoration: none;
}

I saved the header file and closed it.

Add the jQuery plug-in Placeholder

All of our infrastructure is in place. Now I need to add a placeholder, and tell jQuery to call my plugin against the placeholder. Luckily, this style already has the ability to add content to the header region of the template. I simply went into WordPress addmen, and went to “Current Theme Options” under ‘Appearance’ and added the following to the “Banner” section:

<!-- Slider -->
 <div id="slider"><div id="twitterClient"></div></div>
 <script type="text/javascript">
  jQuery(document).ready(function($) {
    $("#twitterClient").twitterClient({
                        userName: "tobint",
                        tweetCount: 10,
                        delaySeconds: 5
                        });
    });
 </script>
<!-- /Slider -->

I also checked the boxes above to display this content for registered users, commenters, and visitors. I saved the file header options and viewed my site. Much to my glee, everything worked just great. My next steps are to turn this into a widget so others can just add this to any registered sidebar for a given theme.

Let me know if you have any questions.