How to build the sidebar.php file in WordPress

Sidebar.php is the next template file we will learn in our Let’s Build A WordPress Theme From Scratch tutorial series. As I am sure you have guessed from the name of the file, it handles the code that displays the content of your sidebar. Sidebars have been a common structural element in websites for years. Really anything can go in a sidebar but I prefer to “widgetize” my sidebars so that the user/client can dynamically include/change what displays. Widgets come standard with any WordPress install and give you the ability to drag and drop mini-plugins into your website and have certain things happen: like maybe a contact form or a dynamic list of categories. These can also be extended by searching the plugins section of WordPress to find more. When you build a WordPress theme you should always think about what type of functions you might want or need and go out and research plugins that might accomplish your needs. Once you have all of the widgets you want…you need to have a “widgetized” area ready to drag those widgets into so they display on your website. We are going to talk about how sidebars work in WordPress and how we can create these widget areas so they can be used throughout your build.

This is the sixth article in the Let’s Build A WordPress Theme From Scratch Series.

How To Build A WordPress Theme With A Dynamic Sidebar

There are three main steps that have to be taken in order to create a sidebar:

  1. Create the sidebar.php files you might need in your root folder.
  2. Register/Create the sidebar in the functions.php file.
  3. Assign your registered sidebar to the template files where you want the dynamic sidebar content to appear.
Create Sidebar.php

The first thing you need to do is create a new php file in your root folder called sidebar.php. It is best to think of the sidebar.php file as just another part of your html structure. What this means is that typically you have a slightly larger area for content that might be floated left and then a smaller area of content that is floated right. Typically in WordPress we want our dynamic sidebar content to be displayed on multiple pages so we create one template file for each dynamic sidebar we want. So on any page you want to have a sidebar you would simply write out the html of the floated left content we discussed above and then we would call the sidebar.php file using the WordPress function get_sidebar();. This function would then call the sidebar.php file which would contain all of the html for the floated right content area.

To make sense of this we really need to look at some code and I think it would be best if we reference some of the other template files we have discussed in this series and use code that you have seen before. The below code is from my article on Let’s Build A WordPress Theme From Scratch – Page.php

<?php get_header(); ?>

<div class="page-content-title-wrapper">
    <div class="wrap_1280">
        <h2 class="page-content-title"><?php the_title(); ?></h2>
    <div class="clearfix"></div>
    </div><!-- END WRAP_1280 -->

<div class="wrap_1280">
    <div class="main-content">
        <div class="left-page-content col-lg-8 col-md-8 col-sm-8 col-xs-8">
            <div class="page-content">
                <?php if (have_posts()) : while (have_posts()) : the_post(); ?>
                    <?php the_content(); ?> 

                <?php endwhile; ?>
                <?php else: ?>
                    <p>No content has been posted to this page.</p>
                <?php endif; ?>
            </div><!-- END PAGE-CONTENT -->
        </div><!-- END LEFT-PAGE-CONTENT -->
        <?php get_sidebar('page'); ?>

    </div><!-- END MAIN-CONTENT -->
</div><!-- END WRAP_1280 -->

<div class="clearfix"></div>

<?php get_footer(); ?>

You can see that I have a div with a class of ‘left-page-content’ as well as a few column classes from Twitter Bootstrap. If you aren’t familiar with Bootstrap, this class tells the browser that this column is 8 out of 12 columns across the page. Then right after that div closes I include the get_sidebar(‘page’); function that pulls over the sidebar-page.php template file. In the sidebar-page.php file I have the below code:

<div class="right-content col-lg-4 col-md-4 col-sm-4 col-xs-12">
    <div class="sidebar">
        <?php if (!function_exists('dynamic_sidebar') || !dynamic_sidebar('page_sidebar')): endif; ?>

Now we can see that the div with the class of right-content fills the other 4 columns that are left out of the 12 and we now have two content areas floated side by side. I am sure you are saying to yourself “Wait a minute Wayne, I thought we were talking about sidebar.php not sidebar-page.php!?!?!”. Well we still are, but with a small variation. Much like some of the other template files I have discussed, some have naming conventions that WordPress understands. So let’s say we want to have a sidebar on our home page that has a CTA (CALL TO ACTION) and a contact form. Then we want to have every PAGE have a sidebar that still has that same CTA but now we have a listing of recent blog posts you have written to drive people into your blog articles. Then when they get into the blog area, there is a sidebar that no longer has your CTA but has all of the different categories attached to your blog articles and maybe even a cool little tag cloud. What we would do is create three separate sidebar.php files. The home page would be assigned sidebar.php which would be referenced/pulled using the get_sidebar(); function. Then we would create a file called sidebar-page.php and reference/pull this file using get_sidebar(‘page’) where we are passing in a parameter of page which is the slug or the word after sidebar and the dash in your file name. For the blog, we would create a file called sidebar-blog.php and then reference/pull it using get_sidebar(‘blog’). Hopefully you can begin to see the pattern. This accomplished the first step I listed above.

Register Your New Sidebar

Next, we need to register our sidebar areas in the functions.php file. I know we haven’t discussed the functions.php file yet but I will have a VERY in-depth tutorial on it later. Let’s tread lightly right now and just create the functions.php file if you haven’t already and just make sure that it starts with an opening php call like this:

...then content...

Inside the php call where I wrote ‘then content’ copy and paste the below code:

if (function_exists('register_sidebar')) {
	'name' => '',
	'id'   => '',
	'description'   => '',
	'before_widget' => '',
	'after_widget'  => '',
	'before_title'  => '',	
	'after_title'   => ''

Now that you have it pasted into your functions.php file we need to start entering in some of the information needed. First we need to give our sidebar a name. Between the single quotes of the name area above you can call it whatever you want. If you go to your dashboard and click on the Appearance tab, and then choose Widgets, you will see all of the available widgets to the left and then an area to the right where your widget areas appear. Whatever you name this sidebar area will appear as the title of the widget area on this page. (see image below)

The Widget / Custom Sidebar Area in WordPress

Next we fill in the id which is very important when we move to the final step of adding the function that will call this sidebar in our template files. I typically use words like sidebar for the sidebar.php file, page_sidebar for the sidebar-page.php, and blog_sidebar for the sidebar-blog.php file. Either use and underscore or a dash instead of spacing out the words. The description will display under the widget area title and will tell clients/users what they are suppose to add to the widget area or where the widgets would display if they add any. The last four options let you assign things to appear before and after the widget and before and after the title of the widget. Typically most widgets have a field that you can fill out for a title and you would use the before_title and after_title to put in html H-tags like an h1 or an h2 that would wrap around this title. Same goes for the before_widget and after_widget, but in this case you would add a div with a class you want to use or some other html that you will then use to style the contents of the widget. In the before you would add things like <div class=””> or <h1> and then in the after you would close those elements like </div> or </h1>.

You can create as many of these sidebar areas as you want by simply copying and pasting the above code and filling in the information for each.

Adding The Sidebar Area To Your Theme

I have copied the code from above that we added into the sidebar-page.php file so that we can talk about the last step in our process. Right under the div with the class of sidebar is a function. This function is what tells your theme that the sidebar you just created needs to appear here on your website. So wherever you add this in your theme it will generate the content you add from your widgets. Notice in the second part of the code you see dynamic_sidebar and then inside the parameters we pass in the id of the sidebar we created in the previous step. To be clear, if you go back to the dashboard -> Appearance -> Widgets and then drag a widget into the Page Sidebar it will appear in any theme template file you have added this code.

<div class="right-content col-lg-4 col-md-4 col-sm-4 col-xs-12">
    <div class="sidebar">
        <?php if (!function_exists('dynamic_sidebar') || !dynamic_sidebar('page_sidebar')): endif; ?>


Using sidebars when you build a WordPress theme can be a very helpful tool throughout your build, especially if you want your client to be able to choose and dynamically customize content in different areas of your theme. Plan the sidebars out before you start to build so that you can maximize how they perform. What I mean by that is that your sidebar is usually the area that will contain links or other CTAs to drive traffic around your website. The longer someone stays on your website and the more pages they click around on the more Google says “Hey, people really like this website…I need to rank them higher!”. I know there was a lot covered in this article and I tried to make it as clear as I could but if you have any questions just shoot me an email and I will help clarify.

Team Treehouse – Learn PHP for WordPress

If you are serious about learning to develop custom themes in WordPress, I highly recommend you join Team Treehouse. They have a full video course on everything WordPress development, including a course on specifically writing PHP for WordPress.