Wordpress

How to Widgetize Your WordPress Theme in 2 Steps

Working on a new theme for the next Digging into WordPress book update, I found myself really getting into the whole “widgetizing” thing. Widgets enable non-technical users to customize your theme according to their specific layout needs, and with so many different widgets available, the possibilities are endless. You may have thought about widgets as something you do in the sidebar, but there is no reason to stop there. You can widgetize just about every part of your theme. In this post, we’ll show you how to do widgetize your theme in two easy steps. Once we get the basics down, we’ll dig into some sweet tips and tricks.

Widgetize Your WordPress Theme: Step 1

Make a fist and howl at the monitor. Then place this code into your active theme’s functions.php file:

if (function_exists('register_sidebar')) {

	register_sidebar(array(
		'name' => 'Widgetized Area',
		'id'   => 'widgetized-area',
		'description'   => 'This is a widgetized area.',
		'before_widget' => '<div id="%1$s">',
		'after_widget'  => '</div>',
		'before_title'  => '<h4>',
		'after_title'   => '</h4>'
	));

}

This is all that is needed for the first step. Once this widgetizing code is placed in your functions.php file, proceed to Step 2. The remainder of this section is explanation.

This code checks to make sure that the current version of WordPress supports widgets, and then declares an array of values that will be used to create the widgetized area in your theme. Here are the different values:

  • name – the name of the widgetized area as displayed in the WP Admin
  • id – a unique identifier for your widgetized area
  • description – description of the widgetized area
  • before_widget – the markup generated before any user-added widgets
  • after_widget – the markup generated after any user-added widgets
  • before_title – the markup generated before the title of any user-added widgets
  • after_title – the markup generated after the title of any user-added widgets

So, given these parameters, our widgetizing code would result in the following output, say, if the built-in Search widget were added to our widgetized area:

<div id="search-3">
	<h4>Search</h4>
	<form role="search" method="get" id="searchform" action="http://localhost/283/" >
		<div>
			<label for="s">Search for:</label>
			<input type="text" value="" name="s" id="s" />
			<input type="submit" id="searchsubmit" value="Search" />
		</div>
	</form>
</div>

Note the markup created for the opening <div>, which gets its attribute information based on the wild-card matching specified in our widgetizing array. To see this more clearly, examine the following side-by-side comparison of the sprintf directives and the resulting (X)HTML source code:

'before_widget' => '<div id="%1$s">',
<div id="search-3">

Hopefully the relationship is clear. This is a powerful way to ensure that all widgets have a similar class names and unique IDs, which are important for easy CSS styles.

Let’s continue with Step 2..

Widgetize Your WordPress Theme: Step 2

Finally, add the following code to the location in your theme’s template file(s) where you would like the widgetized area to appear:

<div id="widgetized-area">

	<?php if (function_exists('dynamic_sidebar') && dynamic_sidebar('widgetized-area')) : else : ?>

	<div>
		<p><strong>Widgetized Area</strong></p>
		<p>This panel is active and ready for you to add some widgets via the WP Admin</p>
	</div>

	<?php endif; ?>

</div>

With both steps complete, your theme should now feature a widgetized area in the location of your choosing. Nothing else needs to be done at this point. If you get it, then get to it and continue developing your theme. For more information and some juicy tips and tricks, continue reading.

Let’s examine the code used in this second step. Everything located between the if/endif statements will be output to the browser when no widgets have been activated. This is a good place to inform the user that the area is widgetized and may be customized via the Widgets area in the WordPress Admin. I also include a “pre-widget” class to help style the pre-widget area. With multiple widgetized areas on a page, having a class name to hang styles on is super nice.

Also, note that we are using the id specified in the widgetizing array (refer to Step 1) as the parameter value for the specific dynamic_sidebar() check in the third line.

Multiple widgetized areas

So we now have a nice, widgetized sidebar. But why stop there? Implementing additional widgetized areas is as simple as replicating the code in Step 1 and Step 2. For example, let’s say we wanted to widgetize the header, sidebar, and footer areas of our theme. We would be put this in our functions.php file:

if (function_exists('register_sidebar')) {

	register_sidebar(array(
		'name' => 'Header',
		'id'   => 'header',
		'description'   => 'This is the widgetized header.',
		'before_widget' => '<div id="%1$s">',
		'after_widget'  => '</div>',
		'before_title'  => '<h4>',
		'after_title'   => '</h4>'
	));
	register_sidebar(array(
		'name' => 'Sidebar',
		'id'   => 'sidebar',
		'description'   => 'This is the widgetized sidebar.',
		'before_widget' => '<div id="%1$s">',
		'after_widget'  => '</div>',
		'before_title'  => '<h4>',
		'after_title'   => '</h4>'
	));
	register_sidebar(array(
		'name' => 'Footer',
		'id'   => 'footer',
		'description'   => 'This is the widgetized footer.',
		'before_widget' => '<div id="%1$s">',
		'after_widget'  => '</div>',
		'before_title'  => '<h4>',
		'after_title'   => '</h4>'
	));

}

..and then we would place the following code chunks into their respective locations within our theme template files:

<div id="widgetized-header">

	<?php if (function_exists('dynamic_sidebar') && dynamic_sidebar('header')) : else : ?>

	<div>
		<p><strong>Widgetized Header</strong></p>
		<p>This panel is active and ready for you to add some widgets via the WP Admin</p>
	</div>

	<?php endif; ?>

</div>
<div id="widgetized-sidebar">

	<?php if (function_exists('dynamic_sidebar') && dynamic_sidebar('sidebar')) : else : ?>

	<div>
		<p><strong>Widgetized Sidebar</strong></p>
		<p>This panel is active and ready for you to add some widgets via the WP Admin</p>
	</div>

	<?php endif; ?>

</div>
<div id="widgetized-footer">

	<?php if (function_exists('dynamic_sidebar') && dynamic_sidebar('footer')) : else : ?>

	<div>
		<p><strong>Widgetized Footer</strong></p>
		<p>This panel is active and ready for you to add some widgets via the WP Admin</p>
	</div>

	<?php endif; ?>

</div>

That’s all there is to it. Of course, you’ll probably want to tweak the details to suit your specific needs, but these two steps are all you need to widgetize your WordPress theme. Now let’s wrap things up with some juicy widgetizing tricks..

Some Juicy Widgetizing Tricks

Here are some sweet little tips for widgetizing your theme:

Streamline & organize custom widgets

The first thing that I do after widgetizing a new theme is to include a separate “widgets.php” that contains all of the custom widgets. A simple line of code is all that is required to acheive this functionality:

if ($wp_version >= 2.8) require_once(TEMPLATEPATH.'/widgets.php');

Place that code into your functions.php file and place all of your widgets into a file called widgets.php. Once in place, this method will ensure that your widgets are loaded and available for all supportive versions of WordPress. This is a great way to keep your theme files nice and organized.

Replace WordPress’ default widgets

Many of the default WordPress widgets leave something to be desired. Fortunately, it’s super-easy to override any of the default widgets with your own creations. For example, here is one way to replace the default Search Widget with your own version:

<?php function custom_search_widget() { ?>

<form action="http://localhost/283/index.php" method="get">
	<div>
		<label for="s">Site Search</label>
		<input id="s" name="s" alt="Search" type="text" />
	</div>
</form>

<?php } if (function_exists('register_sidebar_widget'))

register_sidebar_widget(__('Search'), 'custom_search_widget'); ?>

Hide unused widget areas

An empty widgetized area of your theme can look strange, especially when CSS styles are applied to the container element. To prevent this from happening, we can wrap each of our widgetized areas with the following code:

<?php if (function_exists('is_sidebar_active') && is_sidebar_active('sidebar')) { ?>

<!-- code from Step 2 or whatever you want -->

<?php } ?>

With this conditional code, widgetized areas will only be displayed if they contain at least one active widget. Nice 🙂 Also note that this conditional technique works for displaying things other than widgets.

More..?

Hopefully this easy two-step widgetizing guide will be useful for you during your next round of theme development. As always, if you know of any other sweet widgetizing tricks, please share them in the comments!

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s