How to add a Widgetised area in a WordPress theme

Darling, I'm not in the mood to go dancing. Let's stay home and code widgets instead!

Darling, I'm not in the mood to go dancing. Let's stay home and code widgets instead!

Here’s a tutorial to show you how to add a widget to a theme template file.

Most themes these days come with built-in widget support, most commonly in the sidebar, but also sometimes in other parts of the theme such as the header, homepage or single post pages.

In this tutorial I show you how to add a widget area to single post pages, and how to use the new widget area to display an advert on every single post page.

Widget basics

There are only four things we need to know in order to set up our new widget area:

  1. Which theme template file we need to edit
  2. The code for a Widget area, which we will place in the relevant theme template file
  3. How to “register” a Widget area, usually in the theme’s functions.php, in order to tell WordPress that the widget area exists and therefore allow you to add widgets to this widget area in the Dashboard.
  4. Add some styling to the widget area so that it fits in with the look of our site.

Which template file?

If you familiar with WordPress you will know that different pages on your site are produced by different theme template files. Which template file is used to display different views of your site is taken care of by WordPress, behind the scenes, and follows the Template Hierarchy coded into the WordPress Core files.

In our example, we want to add the widget area to the single post page. Depending on your theme this will be either single.php or index.php. In our example, let’s assume it is index.php.

Adding Widget code to the theme file

Open up your index.php (take a backup first, just in case you need to put everything back to how it was) and decide where you want the new widget area to appear. Typically, your index.php file will be structured something like this (I’ve left out most of the code to keep things simple):

<?php get_header(); ?>

<div id="content">

	<div id="contentleft">
	
		<div class="postarea">
		
		<?php if (have_posts()) : while (have_posts()) : the_post(); ?>
			
			// Loop stuff goes here eg Title, Date, Content etc
			
					 			
			<!--
			<?php trackback_rdf(); ?>
			-->
			
			<?php endwhile; else: ?>
			
			<p><?php _e('Sorry, no posts matched your criteria.'); ?></p><?php endif; ?>
			
		</div><!-- End of postarea -->
			
		<div class="postcomments">
            
			<?php comments_template('',true); ?>
        
		</div>
		
	</div>
	
	<?php include(TEMPLATEPATH."/sidebar.php");?>
			
</div>

<?php get_footer(); ?>

Your index.php file may not have the same DIV id name’s, but the structure should be similar: a DIV containing the Loop, in this case the postarea div (lines 7-22), and a DIV containing the call to the comments template, in this case the postcomments DIV (lines 24-28).

We want to place our widget area between these two DIVs. That way, the widget content will display below the post content and above the comments section of the page.

First, let’s add a new DIV and give it a new class called “widget-post”. You can name this class whatever you like, but choose something that has some meaning so that it’s easier to remember its purpose. Here’s our added code in lines 24-28:

</div><!-- End of postarea -->

<div class="widget-post">

	// Our widget stuff will go here...

</div>
			
<div class="postcomments">
            
	<?php comments_template('',true); ?>
        
</div>

Now let’s add the code to display our new widget area. Here it is:

</div><!-- End of postarea -->

<div class="widget-post">

	<?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar('Post Widget') ) : ?>
	<?php endif; ?>

</div>
			
<div class="postcomments">
            
	<?php comments_template('',true); ?>
        
</div>

The new code we’ve added will pull in the widget content. In plain English, the code says – if widgets aren’t enabled in this theme or a widget area called “Post Widget” hasn’t been registered, do nothing. Therefore, if widgets are enabled and the widget area called “Post Widget” exists, the widget content will be displayed here. That’s it – no more work needed on the template file, and it’s time to add the “register” code in functions.php.

Registering the widget in functions.php

We now need to tell WordPress that it should enable a widget area called “Post Widget”. Open up your functions.php and look for a block of code something like this:

if ( function_exists('register_sidebars') ) {
	register_sidebar(array('name'=>'Sidebar 1',));
	register_sidebar(array('name'=>'Sidebar 2',));
	register_sidebar(array('name'=>'Sidebar 3',));
}

This is the section of code that tells WordPress to enable widget areas. All we need to do is add a new line to this block of code to register our new widget area. Like this:

if ( function_exists('register_sidebars') ) {
	register_sidebar(array('name'=>'Sidebar 1',));
	register_sidebar(array('name'=>'Sidebar 2',));
	register_sidebar(array('name'=>'Sidebar 3',));
	register_sidebar(array('name'=>'Post Widget',));
}

The important points to note are:

  1. We’ve added the extra line below the existing lines, but before the closing curly bracket. This ensures that our changes do not mess up the widgets you’ve already set up in your sidebar, for example.
  2. We’ve used exactly the same name “Post Widget” that we used in the new code added in index.php above.

Another important point to remember is that the names of widget areas must be unique!

Adding widgets to the new widget area

Go to Dashboard>Appearance>Widgets and you should now see that your Post Widget appears in the righthand side of this screen. You can now drag a Text Widget to the Post Widget, and then add the code necessary to display your adverts within the Text Widget. For example, you can add Google Adsense code here, or affiliate code for a banner ad etc.

View your site and check that on single post pages you now see your adverts between the post content and the comments. If it doesn’t appear, re-check the above steps in case you’ve missed something. If using a newly set up Google Adsense, remember that it can take a short while for the Adsense to populate.

Styling the new widget area

You will probably need to adjust your CSS to get the new widget area to fit in with the look of your site. The most important thing to do first is to add something like this to your style.css to define a style for the new widget-post DIV class which is the container for the widget area:

.widget-post {
	background: #FFFFFF;
	margin: 0px;
	padding: 10px;
	width: 600px;
	}

This is just a starting point – adjust the width, background, padding and margin to suit you.

If you are using Google Adsense, your Google code will already include various styles based on the selections you made when setting up the Google Adsense. If you are posting your own HTML in the Text Widget you will probably have to add some styling to style.css to make the neceesary adjustments. If you are unfamiliar with CSS, check out the many great tutorials that are out there.

And finally…

As you can see, it isn’t too difficult to add a widget area to a theme file. This same method can be used elsewhere in your site to create other widget areas – just remember to name each one uniquely, and have fun!

Comments

  1. Hey Studiograsshopper,

    This is the best tutorial i found on the net. You have explained it in detail and easy to follow.
    I searched for a long time and went through so many forums where so many people confused me a lot.
    Finally, after reading your tutorial “I MADE IT”.

    But…
    Just need a little help about the new side bar below the content (ie., header).

    I created the new side bar as per your instructions and it came out beautiful.
    My themes header h2 is a black block. But i have customized it with an image, you can see it in the images below i have attached.

    Let me list my 2 problems:
    http://shopedition.com/wp-content/uploads/2009/07/heading-as-Dot.bmp
    http://shopedition.com/wp-content/uploads/2009/07/heading-as-Dot-and-Black-Bold.bmp

    As you can see,
    in image 1: i removed the header title for the widget but i get a Black Dot towards the left.
    in image 2: i added the header title, but i get the Black Dot as well as the Black h2 Header.

    All i want to know is,
    1. how to get the widget header with the image i have customized (red image)
    2. how to get rid of the black dot on the left side of the widget.

    Thank you very much for providing this very useful article.

  2. Thanks for this, I suspected that it would be easy to do, but never worked it out myself! Until now I have been added advert code etc. to the template files, and making do with “similar posts” etc. being in the side bars. But now we can put what we like anywhere. Great.

    Thinking that this could be extended to headers – i.e. a “header image” widget to easily allow the theme of the site to change. Would be useful if you are in the business of selling WordPress theme shells.

  3. Hey there,

    This is an excellent tutorial, thanks.

    I have however come up with a wordpress plugin which lets you define a new “sidebar” and then add this to post/page content through the use of a shortcut rather than having to add code to template files. If you’re interested the Widgets on Pages plugin can be downloaded from WordPress.org

  4. Great Tutorial !

    It help me understand how “bloody” complex this is ! Lets say you have a widget in word press e.g. “member login” widget and you want to add it to your theme.

    What you need is a basic understanding of the following:
    U Need to understand CSS
    U Need to understand PHP
    U Need to understand WP structures/files
    U Need to understand how to call a Widget i.e the PHP call
    U Need to understand your Theme structures, which might actually hide from you the PHP index thro some exotic framework – mine does 😉

    Then using wordpress
    1) Cumbersome: You need to navigate in an out of wordpress “editors” to find the right stuff and use say another tool to actually tweak in real time what the CSS changes look like.

    2) Finding the right CSS declarations to tweak in the the widget codes since you don’t like the appearance e.g., colors or the format for example so you have to find in the widget code in word press since most widgets don’t generally come with a separate CSS file to modify.- Mmmm

    3) Need to edit the right files to place the right PHP code insertion – Mmmm

    LOL

  5. ILoveCole says:

    Thanks! 😉 Great tutorial!!

  6. Kevin Thomson says:

    wow – now that’s what I call a crystal clear tutorial. For a while i’ve assumed this is an arcane skill best left to super geeks and now I see that it is quite straight forward. Now i’m off to add a new widget area to one of my sites 🙂

  7. Brandon says:

    Wow…I’m speechless on how easy that was to comprehend. I even learned a few things i didn’t know that are basic!

    Thanks for the tutorial, I’ll be sure to throw the link around.

  8. Hi Ade!

    I have to ask you, I am using Genesis for the first time and although it is rather different from other WP themes, I think I am hooked. But I have ONE big problem I actually can’t seem to get the home page widgets to work. What the h..k am I doing wrong here. Can you help me out on this?
    website http://www.time-ads.net

    I will buy you a virtual beer/ glass of wine if you can solve this for me.
    /Robert

    BTW tell me about your login (is it a forum).
    Do you have a newsletter signup?

    /Robert

  9. Thank you very much!

    Even after reading WordPress documentation, i was struggling with adding custom sidebar to my theme.
    Your article helped me a lot, and i finally was able to do that.

  10. Thanks for the very informative tutorial. It helped me develop my custom template the way I wanted!

  11. Audra Marie says:

    Thank you! I got my widget area created easily with your instructions. 🙂

  12. Thanx for your excellent tutorial. I’ve some problems with the backend’s visualization: the new sideber hide the widget that I put in and now I can’t remove it. How can I resolve the problem? Please let me know.
    Best Regards
    Nicola

  13. What do you do if

    1 if ( function_exists(‘register_sidebars’) ) {
    2 register_sidebar(array(‘name’=>’Sidebar 1’,));
    3 register_sidebar(array(‘name’=>’Sidebar 2’,));
    4 register_sidebar(array(‘name’=>’Sidebar 3’,));
    5 }

    is not in your themes functions.php?

    Can you just add it in?

    • The example is just that – an example. No need to add this code if your theme doesn’t have these sidebars. All you need deal with is registering your new sidebar.

      Hope that clarifies.

  14. thanks a lot .. really helped meee 😀

  15. Nice and simple! Have been looking, but others are not as well explained.
    Thanks for this great post.

  16. mandy schreiner says:

    Hi, I have the same question. My functions file has not much in it. I created the child theme as you said. That worked great. I appreciate the tutorial.

    I added the line of code here and did not see it show up in my widgets area. I put this in the header.php of my site. I named them the same (just used same name as your example because i am just trying to learn this). Any ideas? This code under /// Get Core – is the only code in my entire functions file?

    // GET CORE ///////////

    if(file_exists(TEMPLATEPATH.’/_core/init_core.php’)){
    define(‘CORE’, TEMPLATEPATH . “/_core”);
    define(‘CORENAME’, “_core”);
    register_sidebar(array(‘name’=>’Post Widget’,));
    }else{
    define(‘CORE’, TEMPLATEPATH . “/core”);
    define(‘CORENAME’, “core”);
    }
    include(CORE . “/init_core.php”);

    ?>

  17. Peznemizzle says:

    ur the man!!!
    I was going ?=**&% nuts! Im a absolute beginner and so excited because everything is starting out so easy with wp. And then the first really, really cool stuff was to use the plugins and then… why couldn’t I just take a cool theme and add a plugin on the front page to it!?! try and error for hrs and then I finally found your explanation!
    This would cost like at least 40% on Appsumo.

    !!
    But I have one thing to add. I tried to adapt your explanation on the theme “thememagic”.
    And I had an “index.php” AND a “frontpage.php”. And it worked just after having put the commants into the “frontpage.php”
    damn tricky stuff!!
    thanks dude!

    • Cool! Glad it was useful.

      Checkout the WordPress Template Hierarchy which explains the priority given to each template (eg fronntpage.php) when loading a site page. The frontpage.php template takes precedence over index.php, hence you were correct to put the code in this template.

      🙂

  18. Thank you! This was a great tutorial. Needed some code to be editable by my client and widgetizing the area fit the bill. Had the section up, running and styled in 20 minutes flat.

  19. fully working 100%. great thanks 🙂

Leave a Reply to Todd Halfpenny Cancel reply

XHTML: You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

*


three − 2 =