Widgetizing a WordPress Theme

Widgetizing a WordPress Template

One of the aspects that makes WordPress such a popular personal publishing platform, and an increasingly competent CMS, is the ease with which it can be customized. The ability to customize your WordPress theme to display a widget in a new area of your site requires an understanding of what a widgetized area is, how you go about creating new ones and what your theme’s templates need in order to properly display them. This simple tutorial is going to focus in on that core feature of WordPress’ customizability, is based on some of the recent work done on the CUNY GCDI child theme and is dedicated to the Digital Fellow Hillary Miller.

Preliminaries

If you’ve done anything with your WordPress installation beyond activating a theme and writing a few posts then you’ve most likely interfaced with more than one widgetized area. Widgets are almost always provided by a plugin and are activated, configured and placed in a specific page location through the Appearance → Widgets admin page.

Widgets Admin

A widget is usually a small collection of code that has been designed to perform one specific task. WordPress provides default widgets for common situations such as displaying a search box, recent posts or comments and listing categories and tags. Once you’ve outgrown the basic features provided by the builtin widgets you can move on to literally thousands of 3rd party plugins available from the WordPress plugin directory. There you can find a plugin to provide almost any functionality you could possibly need. Everything from adding a slideshow to your sidebar to turning your entire site into an e-commerce powerhouse.

Location, Location, Location

It’s all well and good to understand where a widget comes from and how to drag it to a specific page location on the Widgets Admin page; but what are you supposed to do when you want to display a widget in a location other than those provided by your current theme? This is where widgetizing your theme’s template files comes into play. The widgets that are available to you are displayed on the Widgets Admin page in the “Available Widgets” section. These widgets come from the WordPress core, possibly from your custom theme and most likely from the 3rd party plugins you’ve installed and activated. The areas of a page in which you can place these widgets run down the right hand side of the Widgets Admin and are created by your theme. Basic themes will usually define some common widgetized areas such as in a sidebar or maybe the footer area. More advanced or often premium themes can define a great multitude of available locations and can range from the header, down the sidebar, into the footer and often in the page or post content areas themselves.

A recent request to enable the display of rotating tweets between content areas on the homepage of the GCDI site dealt directly with the ability to render these tweets between the slider and main content sections of the site’s homepage. The current theme, and the the child we’re using for customization, did not support this functionality out of the box (the Widgets Admin screenshot above shows a few of the available widget areas). So we were forced to create our own customized solution, which is where the real fun in developing a WordPress site lies.

GCDI Homepage

What was needed was a new widgetized area on the Widgets Admin page that corresponded to the theme location in which we wanted the tweets to be displayed. While this may sound difficult at first, in reality it is a simple two step process.

Step 1

Your first step is to tell WordPress that you want a new widgetized area. This is accomplished through the use of a WordPress function named register_sidebar(). This function accepts an array of arguments that defines how it works and looks both on the front and back ends of your site. Because this is a customization to your theme that is intended only for your use, this function is placed in the child theme’s functions.php file. As an example, here is the code necessary to create a new widgetized area using the WordPress default settings:

register_sidebar(array(
    'name' => __( 'Sidebar name', 'theme_text_domain' ),
    'id' => 'unique-sidebar-id',
    'description' => '',
    'class' => '',
    'before_widget' => '<li id="%1$s" class="widget %2$s">',
    'after_widget' => '</li>',
    'before_title' => '<h2 class="widgettitle">',
    'after_title' => '</h2>'
 ));

The register sidebar link in the previous paragraph will explain all those options in far greater detail than is needed here. For the purposes of this tutorial it’s only important to understand that you can call this function from anywhere in your theme’s function.php file as long as it’s after the opening <?php and closing ?> php tags. If you literally copied the above code and pasted into your theme’s functions.php you would see a new box on the right hand side of the Widgets Admin page with the title Sidebar name. As simple and cool as this is, we really haven’t accomplished anything to brag about. This is because whatever widget(s) you drag into the newly created box will not be displayed anywhere on your site. This brings us to step two.

Step 2

Once we have a newly widgetized location created by the code in functions.php we need to tell our WordPress theme where we’d like to see the widgets that are added to that area in the admin. This is accomplished through the use of one more function: dynamic_sidebar(). Just like register_widget() this function accepts only one argument, however, in the case of dynamic_sidebar() that argument is the ID or name of the widgetized area you created by calling register_sidebar() in your functions.php.

The naming of these functions can be a little confusing when you’re not literally adding a newly widgetized area to an existing “sidebar.” The names are holdovers from a time in WordPress’ evolution when widgets were relegated to the literal sidebar areas of your theme. As WordPress grew so did the need and desire for dynamic widgetized areas to exist in other locations of theme layouts. So it’s important to remember that while you can widgetize any area of your theme, as far as WordPress is concerned, in the code that area is referred to as a “sidebar.” Hopefully the core development team will generalize the names of these functions in the future to make them a little more descriptive, but they are so widely used across all themes that I assume this could cause more confusion than clarity for both new and existing theme developers alike.

Staying with the example code above, we can now display the contents of this widgetized area anywhere we’d like in our theme by calling dynamic_sidebar() in the template that corresponds to the location you’ve decided upon like this:


<?php dynamic_sidebar( 'Sidebar name' ); ?>

...or this...

<?php dynamic_sidebar( 'unique-sidebar-id' ); ?>

Choosing the proper location in your theme’s template files is more of an art than science and takes a little practice and trial and error coding. In the case of the GCDI homepage we wanted the tweets to be displayed between the homepage’s slider and whatever content is rendered right below it. After investigating which different templates can be loaded during the rendering of the homepage it was decided that the call to dynamic_sidebar() to display the Twitter plugin widget being used should be added to a template named featured.php (this template was responsible for displaying the slider and nothing else). The GCDI theme (and child) incorporates a more dynamic process while rendering the homepage than a lot of other themes. The theme offers a multitude of custom options that allow the site’s admin to alter the layout and rendering of different sections based on the desired homepage content. So we were left with two options:

  1. call dynamic_sidebar() in the featured.php template
  2. call dynamic_sidebar() from every template that could be rendered on the homepage

Developing for any platform will always benefit from adhering to the KISS (Keep It Simple Stupid) principle. Rather than overriding all possible templates in our custom child theme we decided to display our widgetized area immediately after the code that renders the homepage slider in the featured.php template. The obvious benefit of this decision is that we could quickly and easily add this new functionality while retaining the option of adding the new widgetized area to other templates on an as needed basis.

Conclusion

The combination of declaring a new sidebar with register_sidebar() in functions.php and then displaying it with dynamic_sidebar() in the desired template is all that’s required to widgetize a new location in your theme. Once you have a basic understanding of where a widgetized area comes from and how to display its contents within a template the coding becomes trivial. Like all customizations the limits to its functionality and usability are hindered only by your imagination. I hope this short tutorial has opened your eyes to the ease with which you can add a new widgetized area to your themes; the links below offer additional information and more advanced configurations for those interested in continuing their education into the dynamic widgetization of a WordPress theme.

References

  1. Digging Into WordPress: How to Widgetize Your WordPress Theme in 2 Steps
  2. WP Codex: Widgetizing Themes
  3. WP Codex | register_sidebar()
  4. WP Codex | dynamic_sidebar()

2 thoughts on “Widgetizing a WordPress Template

  1. Jen Jack Gieseking

    This is superbly helpful and well written! I would love to thank you personally too but I see your site doesn’t list which Fellow wrote which post. Maybe displaying the author’s name is another edit to a child theme that you could make and post about…? 😉

    Thanks again!
    Jack

    Reply
    1. Profile photo of Dominic GiglioDominic Giglio Post author

      Thanks Jack.

      Right now, all posts are written by me (Dominic), but I would love it if other Digital Fellows wanted to contribute their own articles. Even though this is currently only a single author tutorial blog, that doesn’t mean that I don’t need to display the name of the author. If your theme doesn’t support this feature out-of-the-box then it is definitely a job for a child theme. I think that would make a great tutorial. I’ve added it to my list of pending tutorials, so stay tuned for that soon.

      Reply

Leave a Reply

Your email address will not be published. Required fields are marked *