Genesis Explained Widgetize Functions

The last post in the Genesis Explained series was about the options functions and demonstrated some very important functions for retrieving custom fields and theme options from the database. This article is all about the genesis/lib/functions/widgetize.php file. There is really only one function you will be using in the theme, but there is some other good stuff you can learn from this file.

Here is a list of all the functions in the file.

• genesis_register_sidebar: Registers new sidebars
• genesis_register_default_widget_areas: part of an action hook, registers the default sidebars
• genesis_register_footer_widget_areas: part of an action hook, registers the footer sidebars

Before we dive into that, though, I want to talk about some terms.

Sidebar

A sidebar is the WordPress term for any part of the theme that widgets can be added to. This was generally relegated to “sidebars” so that is why this term is used, but more and more advanced themes make use of all parts of the theme for sidebars. They may appear in the header, the content, the sidebars, or the footer. Often people call these widgets, but that isn’t accurate and can lead to confusion. Call them either sidebars or widgeted areas.

A sidebar has several important parts. The sidebar name, ID, before and after widget, and before and after widget title. We’ll talk about these in more details later.

Widget

Widgets go into sidebars. Widgets are registered in WordPress using a special class extender and have two main parts. The back end and the front end. On the back end you can drag widgets into sidebars. You can also set any widget settings once they are in the sidebar. If a widget can’t find it’s home it goes to the inactive widgets. This happens when the ID changes. Again I’ll talk about this more later. The front end is what actually appears on the site.

genesis_register_sidebar($args)

This function has a single arg, but it is an array value. There are defaults built in

$defaults = (array) apply_filters( 'genesis_register_sidebar_defaults', array(
		'before_widget' => '<div id="%1$s" class="widget %2$s"><div class="widget-wrap">',
		'after_widget'  => "</div></div>\n",
		'before_title'  => '<h4 class="widgettitle">',
		'after_title'   => "</h4>\n"
	) );

As you can see, there is a filter “genesis_register_sidebar_defaults” that lets you change any of those defaults. That is very handy if you want a different title or widget wrap. Once the defaults are parsed with the arguments that are passed a new sidebar is registered with register_sidebar(). Of course you could just use that function, but look how much more efficient the Genesis function is.

//WordPress Function
register_sidebar( array(
    'name' => 'My Sidebar', 
    'id' => 'my-sidebar',
    'before_widget' => '<div id="%1$s" class="widget %2$s"><div class="widget-wrap">',
    'after_widget'  => "</div></div>\n",
    'before_title'  => '<h4 class="widgettitle">',
    'after_title'   => "</h4>\n"
    ) );

//Genesis Function
genesis_register_sidebar( array (
    'name' => 'My Sidebar', 
    'id' => 'my-sidebar',
    ) );

Each of these will create identical sidebars, but you need much less information with the genesis function. The only requirements are the name and id. If you want you can even skip the ID, but I don’t recommend it. If you have a properly formed ID then your widgets will stay at home where they belong. Otherwise, if there is a change in the order of the sidebars, then your widgets will move to other sidebars or into the inactive widgets.

An ID should be lowercase and have no spaces. If you want to use a space, then put a “-” in there. This is important because the ID is used as an html ID, so you need to conform to html standards. Plus if you have spaces WordPress can lose track of your widgets.

Of course, if you want to create a special sidebar with a different widget wrap and title wrap you can change the defaults.

You can remove any of the default sidebars by unregistered them. This is done with the unregister_sidebar() function. Just put this in your functions.php file to get rid of the secondary sidebar

unregister_sidebar( 'sidebar-alt' );

Of course this still leaves the layout options in place. to get rid of them you need to remove layout options. I’ll be talking about this next time when we cover the layout.php file. Till then, don’t forget to subscribe to the feed and follow me on twitter. (‘d make a link but I want you to click on the header link. It’s using a cool hacked version of the new Twitter follow button. Give it a try.)

Also, while you are here help guide the next series, which will be about making a new child theme, by putting things you want to see in a child theme in the Wish List.