Adding a Widget Area to WordPress Theme

Posted in Tutorials

Tweet This Share on Facebook Bookmark on Delicious Digg this Submit to Reddit

In this tutorial, we will add a new widget area to the default WordPress TwentyThirteen theme.   Before we make any changes to this theme, we had cloned TwentyThirteen into a new theme called TwentyCustom. See how in this tutorial.  And then activate the TwentyCustom theme.

Now we will add our widget area to the TwentyCustom theme.

1.  In Dashboard ->Appearance -> Widgets, see that the theme currently has two widget areas: The Main Widget area and the Secondary Widget area….

current widget areas

current widget areas

that corresponds to these locations in our theme …

location of widget areas

location of widget areas

2.  Let’s add a new widget area at location shown in blue above — the right side of the header.

3.  We put some code (marked in red below) in header.php of our theme folder TwentyCustom to make room for our new widget area …

widget area code in template

widget area code in template

We bounded our existing header in a div floated left at 60% width.  We inlined the CSS styles for the purpose of this tutorial.  But you should refactor those styles out to your style.css file.

Then we created a second div floated left at width 40%.  This div shall be our header widget area.  To test how it shows up, we applied a blue border and put in dummy text “This is our new widget area”.

Finally, we wrapped these two divs in an container div with class “clear” because we see that class clear in style.css uses the micro clearfix technique to clear floats.

4. Applying these changes, we see our widget area is nicely placed …

widget area placed

widget area placed

5. Next we have to register our widget so that admins can configure it in the dashboard.  We use the hook APIs which goes into the functions.php file of our theme folder.  At the bottom of our functions.php, we write this …

code to register widget

code to register widget

How did we know to write this?   Because that was how the theme TwentyThirteen registered its Main and Secondary widget area.  Just search “register_sidebar” in your functions.php and you see similar code.

But what it means is …

The “add_action” line is the taking advantage of WordPress’s widgets_init hook.   “widgets_init” is a WordPress hook.  When that event happens (which will happen when wordpress start initializing widgets), WordPress is going to call our function which we arbitrarily named “header1_widgets_init”.  But by convention, we usually have the suffix of the function match the hook.  That’s why the function name ends with “widgets_init”.

Then we define our function header1_widgets_init.  It basically just calls the WordPress function register_sidebar.  “sidebar” is what it calls “widgets area”.   register_sidebar takes array of key-value pairs, where you fill in the values.  For name, we gave it the value “Header Widget Area One”.  And we gave “header-1” as the id.

6. The function register_sidebar enables our widget area to show up in the dashboard.  Go to dashboard now and you can see it …

widget area in dashbard

widget area in dashbard

Note that the description that we passed into register_sidebar shows up as well.

7. While we are here, drag a search widget into there and give it the title “Find Something”.

add widget to widget area

add widget to widget area

8. But it won’t show up on our site yet until we alter our theme header.php file code to be like …

dynamic_sidebar

dynamic_sidebar

We wrapped an if-statement around the second floated div (which we have removed the debugging blue border).   If the header sidebar is active (as determined by is_active_sidebar()), only then we display the second div.   Contained within the second div is our header widget area.

We replaced the dummy text dummy text “This is our new widget area”  with the call to the WordPress function dynamic_sidebar().  Thgis function will output all the necessary code for your widget area.  You just have to pass it the widget area id, which we had specified as “header-1” when we registered our sidebar.

8.  Now when you refresh the site, we see the search widget shown…

widget output code

widget output code

Inspecting the code, we see that our widget is wrapped in a pair of “aside” tags.  This is because of the values that we gave it for before_widget and after_widget when we register_sidebar.

Note that h3 tags that wraps our widget title is from the before_title and after_title values passed into register_sidebar.

The class attributes in these tags are what we gave it.  Except there is a “%1$s” and a “%2$s” in the values for before_widget and after_widget.  These are sprintf placeholder arguments so that WordPress can pass the widget id and widget type into the tags.