Code / how to

Tags: , ,

October 4, 2009 0

Widgets are a great way to let people include something cool a bunch of times in their site. The problem is, widget areas are almost always predefined in themes, and usually confined to sidebar areas. So here’s how to make any html element into a widget container.

What exactly does this mean? It means that after we’re done, you will have something on the right of your appearance->widgets screen like:

"Groups Sidebar" is not a default Buddypress widget

"Groups Sidebar" is not a default widget

There’s nothing special about code that runs inside a widget.

A widget is similar to any other piece of template code, except that widget output is defined by the return value of a special function and class. When you put your custom code into the specified parts of this function, WordPress will treat that code as something that can be run and displayed in a specific widget area, depending on where you drag your widget in /wp-admin/widgets.php.

Usually you want to define a widget area in your theme file. Lets say we want to add a widget area to the groups directory page (/directories/groups/index.php) in Buddypress. First find a place where you want to put your widget area div. For my example, I’m going to make a new div in /directories/groups/index.php. You can make a new one like I’m doing, or use an existing element in the template. I’ll put my new element right about here:

  1.         <div id="sidebar" class="directory-sidebar">
  2.                    
  3.                 <?php do_action( ‘bp_before_directory_groups_search’ ) ?>       
  4.  
  5.                 <div id="groups-directory-search" class="directory-widget">
  6.                        
  7.                         <h3><?php _e( ‘Find Groups’, ‘buddypress’ ) ?></h3>
  8.  
  9.                         <?php bp_directory_groups_search_form() ?>
  10.  
  11.                         <?php do_action( ‘bp_directory_groups_search’ ) ?>
  12.                                
  13.                 </div>
  14.  
  15.                 <?php do_action( ‘bp_after_directory_groups_search’ ) ?>       
  16.        
  17.         <div id="groups-sidebar"><!– my new widget area will be element –>

This will make the area below the group search box widget friendly. Add the following lines of code underneath, like this:

  1.        
  2.         <div id="groups-sidebar"><!– my new widget area starts here –>
  3.  
  4.                         <?php if ( !function_exists(‘dynamic_sidebar’)
  5.                     || !dynamic_sidebar(‘groups-sidebar’) ) : ?>

see http://codex.wordpress.org/WordPress_Widgets_Api/dynamic_sidebar

Basically this is saying “if nothing has called dynamic sidebar on the element with id ‘groups-sidebar,’ execute the code that comes after this. This is how you add default sidebar content to display when users have not added any widgets

There is one more step to defining a widget area. You might want to do this in a simple plugin:

  1. add_action(‘init’, ‘custom_sidebar’);
  2.  
  3. function custom_sidebar() {
  4.     $args = array(
  5.         ‘name’          => sprintf(__(‘Sidebar %d’), $i ),
  6.         ‘id’            => ‘sidebar-$i’,
  7.         ‘before_widget’ => ‘<li id=\”%1$s\” class=\”widget %2$s\”>’,
  8.         ‘after_widget’  => ‘</li>’,
  9.         ‘before_title’  => ‘<h2 class=\”widgettitle\”>’,
  10.         ‘after_title’   => ‘</h2>’ );
  11.  
  12.     register_sidebar($args);
  13. }

source: http://codex.wordpress.org/Function_Reference/register_sidebar

You can modify these tags, but WordPress suggests that you leave the sprintf stuff alone for the sake of consistency.

Your widget area should now show up in wp-admin/widgets.php

It should display a properly formatted widget where ever you have it located. I found this process especially useful while editing Buddypress, because it seems like the groups and members pages should really be made widget friendly.

I suggest you read the documentation in http://codex.wordpress.org/WordPress_Widgets_Api for more information – this is basically how I learned to do this.

Leave a Reply