In the release notes for version 3.5.0 of Suffusion I mentioned that native tabbed sidebar support was added. Since I am quite proud of the technique I used to get this effect, I decided to write a tutorial on how to do it. But first I would like to pay homage to the following that helped me visualize the solution:

1. How To Create Tabs Using JQuery – This article by Justin Tadlock, the creator of the awesome Hybrid Theme, was something I used for version 2.0 of Suffusion, where I introduced the tabbed options panel of Suffusion.
2. Widget container HTML (and missing titles) – A thread on the WP forums started (and resolved) by DigitalNature, the creator of the Mystique and some other popular themes, regarding an issue with widgets that do not have titles

The Foundation

If you go through Justin’s tutorial you will get the basic gist of how to build a tabbed box. Basically you need to set up 3 things:

1. The HTML markup
2. The CSS
3. The JQuery for the actual tab effects

The HTML markup requires your page’s source code to look similar to this (like Justin’s example, the differences being in the way I named my classes):

<div id="sidebar" class="tabbed-sidebar">
	<!-- The tabs -->
	<ul class="sidebar-tabs">
	<li id="t1" class="sidebar-tab t1"><a class="sidebar-tab t1" title="Tab 1">Tab 1</a></li>
	<li id="t2" class="sidebar-tab t2"><a class="sidebar-tab t2" title="Tab 2">Tab 2</a></li>
	<li id="t3" class="sidebar-tab t3"><a class="sidebar-tab t3" title="Tab 3">Tab 3</a></li>
	<li id="t4" class="sidebar-tab t4"><a class="sidebar-tab t4" title="Tab 4">Tab 4</a></li>
	</ul>

	<!-- tab 1 -->
	<div class="sidebar-tab-content sidebar-tab-content-t1">
	<!-- Put what you want in here.  For the sake of this tutorial, we'll make a list.  -->
	<ul>
		<li>List item</li>
		<li>List item</li>
		<li>List item</li>
		<li>List item</li>
		<li>List item</li>
	</ul>
	</div>

	<!-- tab 2 -->
	<div class="sidebar-tab-content sidebar-tab-content-t2">
	<!-- Or, we could put a paragraph -->
		<p>This is a paragraph about the jQuery tabs tutorial.</p>
	</div>

	<!-- tab 3 -->
	<div class="sidebar-tab-content sidebar-tab-content-t3">
	<!-- Or, we could add a div -->
		<div>Something needs to go in here!</div>
	</div>

	<!-- tab 4 -->
	<div class="sidebar-tab-content sidebar-tab-content-t4">
	<!-- Why not put a few images in here? -->
		<p>
			<img src="image.gif" alt="Sample" />
			<img src="image.gif" alt="Sample" />
			<img src="image.gif" alt="Sample" />
		</p>
	</div>

</div><!-- tabbed-sidebar -->

Now for the JQuery code to run this:

$j = jQuery.noConflict(); 

$j('div.tabbed-sidebar ul.sidebar-tabs li:first').addClass('sidebar-tab-first');
$j('div.tabbed-sidebar div.sidebar-tab-content:first').addClass('sidebar-tab-content-first');
$j('div.tabbed-sidebar div.sidebar-tab-content').hide();
$j('div.sidebar-tab-content-first').show();
$j('div.tabbed-sidebar ul.sidebar-tabs li.sidebar-tab-first a').addClass('tab-current'); 

$j('div.tabbed-sidebar ul.sidebar-tabs li a').click(function(){
    var thisClass = this.className.substring(12, this.className.length);
    $j('div.tabbed-sidebar div.sidebar-tab-content').hide();
    $j('div.tabbed-sidebar div.sidebar-tab-content-' + thisClass).show();
    $j('div.tabbed-sidebar ul.sidebar-tabs li a').removeClass('tab-current');
    $j(this).addClass('tab-current');
});

The above code simply does the following:

1. Adds the classes “sidebar-tab-first” and “sidebar-tab-content-first” to the tab and content. We could have done this directly in our markup, but the reason for doing it in JQuery will soon become clear.
2. Hides all “content” divs, shows the first content div (with class sidebar-tab-content-first), then adds the “tab-current” class to the first tab (with class sidebar-tab-first)
3. Adds a click function to each tab, making it display the associated content by determining the class of the tab.

So Where is the Problem?

So far we have done something fairly simple for a person with basic JQuery knowledge. The problem lies in tying this with dynamic sidebars. Consider the fact that the definition of a sidebar requires the following parameters:

1. $before_widget
2. $after_widget
3. $before_title
4. $after_title

These are parameters that apply to the creation of individual widgets, not the overall sidebar. If you notice our HTML markup in the previous section, we have created separate sections with all the tabs isolated from the content. But this is not possible for widget definition!! In other words, the widgets print one after the other, so each tab (i.e. the title of a widget) is grouped with the body of the widget, followed by the tab for the next widget and its body, etc. In WP-speak, the widgets typically print $before_widget, then $before_title, then the title, then $after_title, then the content and finally $after_widget. Or course there is nothing preventing a widget author from going bonkers and messing up the order, or not using one of the tags above etc. But that is the widget author’s problem. Assuming that the widgets are coded in a standard fashion, the code doesn’t quite render in a way conducive to tabbed sidebars.

The Fix

The fix is intuitive and is wholly borrowed from the WP forum post I lined to in the above. First we register the sidebar with parameters as follows:

1. before_widget: ‘<li id="%1$s" class="sidebar-tab %2$s"><a class="sidebar-tab">’
2. after_widget: ‘</div></li>’
3. before_title: ” (a blank)
4. after_title: ‘</a><div class="sidebar-tab-content">’

Note the following:

1. We are creating the content as a “div” object within the “li” object.
2. We are unable to assign the widget class (“%2$s”) or the widget id (“%1$s”) to the “a” element.

Now we will pull a trick using JQuery. We will modify the JQuery code thus:

$j = jQuery.noConflict();

$j('.sidebar-tab .sidebar-tab-content').each(function() {
    var parentId = this.parentNode.id;
    var parentClass = this.parentNode.className;
    parentClass = parentClass.substring(12);
    $j(this).addClass('sidebar-tab-content-' + parentId);
    $j(this).addClass(parentClass);
    $j(this).appendTo(this.parentNode.parentNode.parentNode);
}); 

$j('.tabbed-sidebar ul.sidebar-tabs a').each(function() {
    var parentId = this.parentNode.id;
    $j(this).addClass(parentId);
});

$j('div.tabbed-sidebar ul.sidebar-tabs li:first').addClass('sidebar-tab-first');
$j('div.tabbed-sidebar div.sidebar-tab-content:first').addClass('sidebar-tab-content-first');
$j('div.tabbed-sidebar div.sidebar-tab-content').hide();
$j('div.sidebar-tab-content-first').show();
$j('div.tabbed-sidebar ul.sidebar-tabs li.sidebar-tab-first a').addClass('tab-current'); 

$j('div.tabbed-sidebar ul.sidebar-tabs li a').click(function(){
    $j(this).removeClass('tab-current');
    var thisClass = this.className.substring(12, this.className.length);
    var parentId = this.parentNode.parentNode.parentNode.id;
    $j('#' + parentId + '.tabbed-sidebar div.sidebar-tab-content').hide();
    $j('#' + parentId + '.tabbed-sidebar div.sidebar-tab-content-' + thisClass).show();
    $j('#' + parentId + '.tabbed-sidebar ul.sidebar-tabs li a').removeClass('tab-current');
    $j(this).addClass('tab-current');
});

What we did is this:

1. After the page was loaded, we moved the “sidebar-tab-content” objects out of the “li” objects and appended those to the “sidebar-tabs” list as a whole. We did this by smart use of the JQuery “appendTo” function to add every tab’s content to its grandparent.
2. Did all the necessary class additions that we couldn’t in our widget setup, again by fetching it from the parent / grandparent and using the “addClass” function.
3. Added other necessities like the classes for the first tab etc.

That’s basically it. The JavaScript neatly rearranges our code into something conducive for tabbing, then applies the tabbing effects.

Is Everything Hunky-Dory?

Maybe. Let’s first see what advantages it gives us:

1. You are not constrained by a rigid framework. Most of your widgets will seamlessly tie in with this sidebar.
2. With a little extra effort you can make every sidebar behave this way without repeating this code. You just have to be smart with the sidebar ids and use them while doing the hide/show.

Now let’s first examine cases where the tabbing will not work:

1. If your widget has no title, obviously there is no handle for the content in the tab-bar and the result is not pretty. This is not a shortcoming of the code – it is more like a user error. Imagine looking for a document without a title.
2. If a widget author has not followed standard WP guidelines and has ignored the $before_title and $after_title tags and decided to specify his own, that too will cause issues, because the JQuery is relying on certain classes to be named in a certain manner. As I mentioned in the previous section, this is really bad coding on the part of the widget author.

Lastly let’s see what the pitfalls are:

1. If your page is not using JQuery currently, adding this capability will require it to do so. That might slow your page down.
2. If you have a lot of content on your page and if your images are heavy, the JQuery code will be the last to load. While your page is loading the users will see a haphazard layout of the sidebar and once the script is executed at the end of the page load the layout will click in place.

That’s about it. If anyone has a better approach do let me know.

One of Suffusion’s neat little features is the Custom Styles option. Based on some feedback that I had received from some users, in release 3.4.2 I provided a way to bundle custom PHP with your installation.

In this post I will walk you through the following scenarios explaining how you can use this functionality:

1. Adding your own meta tags.
2. Creating your own short codes.
3. Passing extra parameters to queries for fetching posts.

Here is how you begin:

1. Create a PHP file called, say, custom-code.php. Put this file somewhere under your “wp-content” folder, but not under the “suffusion” folder. If you put it in the “suffusion” folder it will get overwritten upon an upgrade!
2. Go to Suffusion Theme Options → Blog Features → Custom Includes → Custom PHP. Put in the file name with the path, as instructed.
3. Now for some serious business. Open the file you created in an editor. You could use any editor that you want (but not a Word Processor!!), like Notepad or Vim or Emacs or EditPlus or Textpad. Your choice depends on your individual preferences and your Operating System. I personally use Vim for editing minor things because of my Unix-based background, and a full-blown IDE like PhpStorm or Aptana Studio or Eclipse for the heavy-duty stuff.
   Now build the shell for the file as follows:

   <?php
   /**
    * Custom includes
    */
   ?>

   Make sure that you have no white-spaces or new lines or text before the “<?php” or after the “?>”. This is critical. If you have spaces there, you will get nasty PHP errors that will require you to replace file/folder contents using FTP.

Now let us address each of our scenarios.

Scenario 1: Adding your own meta tags

This is something I have addressed on the support forum. Let’s say you want to create your own meta tags with name “my-custom-tag” and value “my-custom-tag-value”. Here is what your code looks like:

<?php
/**
 * Custom includes
 */
//The hook for publishing the document header is suffusion_document_header.
//This tells the code to add an extra action to suffusion_document_header:
add_action('suffusion_document_header', 'suffusion_include_custom_meta_tags');

function suffusion_include_custom_meta_tags() {
    echo "<meta name="\"my-custom-tag\"" content="\"my-custom-tag-value\"" />\n";
}
?>

That’s it. You can add as many “echo” statements as you want in the “suffusion_include_custom_meta_tags” function.

Scenario 2: Creating your own Short Codes

The ability to use your own short codes with Suffusion speeds up things several notches. The following code is from one of my previous posts, and it demonstrates how to add a short code that will execute any PHP function. You can add it within the “<?php” and “?>” tags:

function sc_php_function($attr) {
    $function = $attr['function'];
    $params = $attr['params'];
    $params = explode("||", $params);

    if (is_callable($function)) {
        $ret = call_user_func_array($function, $params);
    }

    return $ret;
}

add_shortcode('php-function', 'sc_php_function');

This will create a short code called “php-function” which is like RDX – it will let you execute any PHP function from within a post or a page.

The short code above is dangerous if you have a multi-user blog, or if you are using a plugin that enables short codes in the comments section, because it will let anyone execute any PHP function on your site – it is a significant security risk, so use it with utmost care!

Scenario 3: Passing extra parameters to queries for fetching posts

I recently introduced a hook called “suffusion_query_posts”. This hook is executed before your posts are parsed (aka The Loop), so you can use this to modify what you want to display. It is present on different templates, like Author, Category, Date, Index, Page of Posts, Search and Tag. Let’s say you want to exclude posts belonging to the category with id 15. Here is what you add in the PHP code in the file:

add_action('suffusion_query_posts', 'suffusion_query_enhancer');
function suffusion_query_enhancer() {
    global $wp_query, $query_string;
    $query_string .= "&cat=-15";
}

You could think of a lot of other scenarios where you could use the custom PHP inclusion. Note that like its more popular cousin, the Custom Styles, this too is upgrade-proof. It also adds to Suffusion the feel of a theme framework. If you are looking to add some functionality and you don’t see a hook for it, do post your query on the support forum.

Having a lot of features also makes people request for more features to be added to Suffusion. In this post I will call out a few WordPress plugins that are extremely useful and can help you in a major way set up a Suffusion-powered blog.

1. Page Links To, Redirection
   ”Page Links To” and “Redirection” are two plugins for the same purpose – creating pages that redirect elsewhere. On the surface this appears like no big deal, but once you scratch the surface you realize the power that this kind of a feature offers you. For starters, you can create new pages that point to just about anything: external links, specific posts, categories, tags – you name it. Combine this with the fact that you can define parent pages for pages, and you will have a neat hierarchical structure created with minimum fuss. Take this hierarchical structure and make a navigation menu out of it – it is that simple to create a truly custom navigation menu.
   I have used “Redirection” myself and found that it works pretty well, however some of the theme’s users have reported problems with it. I have, since then, started recommending the “Page Links To” plugin.
2. Widget Logic
   One frequently asked question on the support forums is regarding having different sidebar contents for different pages. The answer to all such questions is the rather intuitive Widget Logic plugin. Widget Logic lets you control each widget’s presence in a page or post or view, so you can very easily achieve the kind of sidebars you are looking for.
3. Exec-PHP
   The Exec-PHP plugin lets you run snippets of PHP code wherever you want. So you are no longer restricted to writing HTML / JavaScript code in widgets – you can use PHP as well.
4. My Page Order, My Link Order, My Category Order
   Suffusion natively supports these plugins. As their names suggest, My Page Order lets you define a custom order for your pages, My Category Order lets you define a custom order for your categories and My Link Order lets you define a custom order for your links. The plugins offer drag-and-drop interfaces, so changing the sequence is really easy. The order you set is automatically pulled up in the navigation menus of Suffusion.

Any more that you would like to pitch in?

One frequently asked question, that has been regularly misconstrued as a Suffusion bug, is this:

I get a notification saying "There is a new version of Suffusion available. View version x.y.z Details automatic upgrade unavailable for this theme." Why is this not available? Can you please fix this?

First off, this is not a bug with Suffusion, as I stated in a previous post. If you notice carefully, you will see that all your themes that have upgrades available show up with the same message. Anyway, the fix for this is rather simple. At first I used to recommend doing a manual upgrade of the theme. A manual upgrade would involve FTP’ing the new folder to the theme’s location. However, thanks to Satyadeep and Buck, there is a much simpler approach. Just do this:

1. Log on to your WP administration panel
2. Go to Appearance –> Add New Themes
3. Search for “suffusion” (or whichever theme you want to upgrade)
4. From the results that you get, pick the one you want and click “Install”
5. If you read the text in the popup, you will see that it says “Install Update”. Click on that and you are done!

What this sequence does is it updates your theme without you having to do it manually. Mind you, this feature was not available prior to 2.9.0, so if you are on an older version of WP this will not work. In older versions WP would have complained that you already have a folder called “suffusion”, so you wouldn’t be able to update the theme using this channel.

Hope this answers a lot of your questions regarding automatic upgrades.

Update: With release 3.4.2, the option group below is no longer called “Custom CSS, JavaScript & RSS”, but it is called “Custom Includes”

I decided to take a pause from my breakneck development and highlight one of the best, and most understated features of Suffusion – Custom Styles. The inspiration for this article is one of the most frequently asked questions that I get:

When I clicked on “Upgrade” I got a message saying that all my changes will be overwritten if I upgrade. Is this true? I don’t want to lose hours of work that I put in to customize my site.

The answer to this question really lies in qualifying “hours of work”. If you have spent the hours modifying the CSS and PHP files in Suffusion, then you are out of luck. You will indeed lose hours, which is a shame because all your CSS changes are absolutely unnecessary.

Seasoned users of Suffusion are probably aware that you can customize your installation of Suffusion almost as you please and not lose any settings when you upgrade. This post is directed towards users who aren’t sure about how to do this. The concept is really, blindingly simple. But before that you need a couple of tools:

1. A nice standards-compliant browser, preferably Firefox or Chrome. Though there are other standards-compliant browsers, I would recommend these because of the wealth of extensions.
2. At least one of these Firefox extensions, if you are using Firefox: Firebug or Web Developer. Both tools are awesome, though I have a slight preference for Firebug because it seems more concise. If you are using Chrome, you are good to go because Chrome offers an inbuilt feature called “Inspect Element”, which you can see upon doing a right-click on any page element. For people with difficulties switching to the better browsers and still stuck with IE, IE has an extension called DebugBar.

You also need to have rudimentary CSS knowledge, which in the days of Internet excesses, can be readily obtained at W3 Schools. And for some serious CSS stuff, there is a set of CSS tutorials at 456 Berea Street that is just phenomenal. Armed with the tools and knowledge, here is what you need to know:

You don’t need to edit ANY CSS file to change the look and feel in Suffusion.

Yup. Instead, do this. Navigate to Suffusion Theme Options –> Blog Features –> Custom CSS, JavaScript & RSS.

There you will see an option called “Custom Styles”.

That is where you can put in all your CSS tweaks. This block is called last when Suffusion is being loaded, so if you want to override any of the theme’s styles your best bet is to put in the styles here. Of course, you might have a plugin that does its own fancy things and overwrites Suffusion’s styles, and if that is the case then you will need to badger the plugin’s author for information about changing a style definition. But for everything else, this little option will suffice.

Let me walk you through this with a little example. To start with, I have enabled the “Top Navigation Bar” on this page. Here is how it looks by default:

This doesn’t go very well with the overall transparent look of this site, so I will make the background of the top navigation bar transparent. Without editing any of my theme’s stylesheets. First I will make use of Firebug. Installing Firebug adds an item to the context menu – “Inspect Element”. So I can right click on the navigation bar and inspect it:

Here is what Firebug shows me:

So the element is called “#nav-top”. Now I do some CSS magic in the Custom Styles:

#nav-top {
        background: transparent;
        border: none;
}

This makes the background transparent and removes the border:

Much better, but I want some rounded corners for the first and last items. But what do I need to modify? Again, Firebug comes to the rescue. I right-click on “Themes” and inspect the element:

OK, so inside #nav-top there is a div with class “col-control”, inside which there is an unordered list (ul) with class “sf-menu”, which obviously has a list item (li) with the links to the pages in the menu. This is a lot of information, but luckily we don’t need to know so much. The good thing about CSS is that the rules and structures are cascading, so I don’t need to call the interim levels if I can avoid it. This is what I add to my custom styles:

#nav-top ul.sf-menu li,
#nav-top ul.sf-menu li > a,
#nav-top ul.sf-menu li > a:hover {
        border-bottom-left-radius: 5px;
        -moz-border-radius-bottomleft: 5px;
        -webkit-border-bottom-left-radius: 5px;
        -khtml-border-bottom-left-radius: 5px;
}

#nav-top ul.sf-menu li,
#nav-top ul.sf-menu li > a,
#nav-top ul.sf-menu li > a:hover {
        border-bottom-right-radius: 5px;
        -moz-border-radius-bottomright: 5px;
        -webkit-border-bottom-right-radius: 5px;
        -khtml-border-bottom-right-radius: 5px;
}

This works, but a bit too well, unfortunately, rounding off all the corners:

Here the articles from Berea Street come really handy. All I need to do is define the bottom left corner for the first list element and the bottom right corner for the last CSS element:

#nav-top ul.sf-menu li:first-child,
#nav-top ul.sf-menu li:first-child > a,
#nav-top ul.sf-menu li:first-child > a:hover {
        border-bottom-left-radius: 5px;
        -moz-border-radius-bottomleft: 5px;
        -webkit-border-bottom-left-radius: 5px;
        -khtml-border-bottom-left-radius: 5px;
}

#nav-top ul.sf-menu li:last-child,
#nav-top ul.sf-menu li:last-child > a,
#nav-top ul.sf-menu li:last-child > a:hover {
        border-bottom-right-radius: 5px;
        -moz-border-radius-bottomright: 5px;
        -webkit-border-bottom-right-radius: 5px;
        -khtml-border-bottom-right-radius: 5px;
}

This looks much better, excerpt for one minor quirk – the first elements in all lists have rounded corners:

So we need to tell the code to only pick the first and last children of the top level list. Again, this is done easily using the “>” selector in CSS (refer the Berea Street link above):

#nav-top ul.sf-menu > li:first-child,
#nav-top ul.sf-menu > li:first-child > a,
#nav-top ul.sf-menu > li:first-child > a:hover {
        border-bottom-left-radius: 5px;
        -moz-border-radius-bottomleft: 5px;
        -webkit-border-bottom-left-radius: 5px;
        -khtml-border-bottom-left-radius: 5px;
}

#nav-top ul.sf-menu > li:last-child,
#nav-top ul.sf-menu > li:last-child > a,
#nav-top ul.sf-menu > li:last-child > a:hover {
        border-bottom-right-radius: 5px;
        -moz-border-radius-bottomright: 5px;
        -webkit-border-bottom-right-radius: 5px;
        -khtml-border-bottom-right-radius: 5px;
}

In the above we are telling the code to only apply the rules to the immediate children of the top level list, not nested children. The result is indeed pleasing:

No unwanted rounded corners are seen above. Now let’s say we want to add some finishing touches by increasing the space between the top level items. Again, using Firebug and basic CSS:

#nav-top ul.sf-menu > li {
        margin-right: 5px;
}

That completes the exercise and I now have the look I set out to achieve:

The good thing is that all my changes are stored in the database and not as files. So even if I upgrade my theme I am covered.

One of Suffusion’s active contributors in the support forum, Connie put together a very descriptive article on the same topic, but using Web Developer as the extension.