larryaronson.com

A lot of the WordPress customization I do happens inside of sidebar text widgets. You can put any HTML inside a text widget including in-line JavaScript and CSS styles. Unfortunately, that doesn’t apply to widget titles. WordPress strips all markup from widget titles. Also, not all themes add a unique id attribute for each separate widget. Here’s how I added custom styling to a sidebar widget title using jQuery’s ability to select individual HTML document elements based on their content.

Most everything described in this post can be done using only WordPress’ built-in template editor available to admin level users.

One client wanted to display a Twitter stream in a sidebar widget showing all tweets mentioning his company. His designer provided this nice graphic to use as the background to the widget’s title:

with the text to appear in white, shifted over enough to give the bird some room to fly. In the Widgets manager (under the Appearance menu,) I added a new text widget to the the sidebar and gave it the title: “Our Company on Twitter.” I left the body of the text widget empty for now and saved it.

I reloaded the site’s front page and inspected the source code to see how this particular theme marked up the title with HTML. It was in a level three heading (h3,) enclosed inside of a division with id="sidebar". With no unique identifier for the widget, I couldn’t simply code a CSS rule, such as:

#sidebar h3 {
  color: white;
  background: url(images/twitter_widget_background.png) no-repeat;
}

as that would put the twitter background behind all sidebar titles and headings.

jQuery to the rescue. It has a method for adding a CSS class to an HTML element and can select document elements by searching their content. jQuery is not loaded by default in WordPress but many themes load it automatically at initialization. See the WordPress Codex page on enqueing scripts for information on safely loading jQuery from various sources.

Using an FTP program, I uploaded the image to the images directory inside of the theme directory. If you don’t have FTP, you can use the file manager in your hosting account’s control panel. Alternatively, you can upload a graphic to your Media Library using WordPress’s media manager and then use the full URL in the CSS below.  The CSS class is needed to establish the background element. It goes in the stylesheet template (style.css ) which can be edited using the Appearance Editor.

#sidebar h3.twitter {
  color: white;
  background: url(images/Twitter_widget_background.png) no-repeat;
  height: 36px;
  padding-left: 60px;
 }

Some simple jQuery is added to the header template (header.php.) It can go anywhere after the script tag for the jQuery library.

<script type="text/javascript">
   jQuery(document).ready(function() {
     jQuery("#sidebar h3:contains('Our Company on Twitter')").addClass('twitter');
   });
</script>

When the document is ready and all elements have been defined, the above code will attach the CSS class, twitter, to any level three heading in the sidebar that contains the string: “Our Company on Twitter”.

The Twitter search feed comes directly from Twitter’s goodies page. One of the goodies is an interactive wizard that will generate the code to copy-paste into the sidebar text widget’s content.

You can do more than just change how the title looks. Want to make a widget title link to something? In the same way that a CSS class can be given an element based on its content, the element’s behavior can be changed. Working with the code above, a click handler can be added to the selected widget title.

<script type="text/javascript">
  jQuery(document).ready(function() {
    twitterWidget = jQuery("#sidebar h3:contains('Our Company on Twitter')");
    twitterWidget.addClass('twitter');
    twitterWidget.click( function () {
      document.location = 'http://twitter.com/OurCompany';
    });
  });
</script>

Adding the following CSS style rules to the theme’s stylesheet will make the title look and act more like a link:

#sidebar h3.twitter:hover {
  color: blue;
  text-decoration: underline;
  cursor: pointer;
}

Resources:

• jQuery documentation
• CSS background images

Tags: jQuery addClass, sidebar widget, Twitter, twitter tools