Widgets API

WP Framework comes packaged with a set of functions for the creation, retrieval and deletion of “widget areas.” Widget areas are simply widgetized sidebars that can be located anywhere in your theme. By the end of this guide, you’ll learn how to create new widget areas in several ways, display those widget areas, and remove them all using WP Framework’s Widgets API.

Creating Widget Areas

create_widget_area( 'aside' );

You only need to define the first parameter of create_widget_area() to register your widget area. The full list of available parameters are:

  1. $widget_area_id - The unique identifier by which the widget area will be called by.
  2. $widget_area_name- The name of the widget area (which is presumably the title which will be displayed).
  3. $hook - Hooks the widget area into a location that’s using do_action( $hook );
  4. $priority - Used to specify the order in which the widget area is executed (default: 10). Lower numbers correspond with earlier execution, and widget areas with the same priority are executed in the order in which they were recieved.
  5. $args - Accepts up to 4 arguments in an array format: before_widget|after_widget|before_title|after_title

To give the widget area a proper name in the widgets administration panel, fill out the second parameter:

create_widget_area( 'aside', 'Aside' );

Sometimes you may have action hooks located in your WordPress theme that you’d like the widget area to be assigned to. To do that, fill out the third and forth parameter:

create_widget_area( 'aside', 'Aside', 'framework_hook_before_html', 10 );

With the third parameter being the name of the action hook, and the forth being the priority in which the widget area would be displayed.

And finally, you may wish to configure the way widgets in your widget area are displayed. To modify that, simply assign the fifth parameter with an array containing one or more of the following:

$args = array(
	'before_widget' => '<div id="%1$s" class="widget %2$s">',
	'after_widget' 	=> '</div>',
	'before_title' 	=> '<h3 class="widget-title">',
	'after_title' 	=> '</h3>',
)

You can then add it to the function like so:

create_widget_area( 'aside', 'Aside', false, 0, $args );

Displaying the Widget Area

Now that you’ve created the widget area using the create_widget_area() function, it’s time to actually display the widget area in your theme. Open up any of your template files and add the following bit of code:

get_widget_area( 'aside' );

You only need to define the first parameter of get_widget_area() to display your widget area. The full list of available parameters are:

  1. $widget_area_id - The widget area id.
  2. $error - Displays an error message.

By default, get_widget_area() displays helpful error messages if the widget area doesn’t already have widgets registered to that area, or if the widget area doesn’t exists (meaning, you didn’t call create_widget_area()). To turn the error messages off, assign the second parameter to false:

get_widget_area( 'aside', false );

Another way of displaying widget areas is via action hooks. First, remember to fill out the third parameter in create_widget_area() when registering your widget area:

create_widget_area( 'aside', 'Aside', 'custom_action_hook', 10 );

Then, in your template file, call:

<?php do_action( 'custom_action_hook', 'aside' ); ?>

The first parameter is the name of the action hook, and the second parameter is the id of the widget area.

Removing Widget Areas

remove_widget_area( 'aside' );

remove_widget_area() takes up to three parameters:

  1. $widget_area_id - The unique identifier by which the widget area will be called by.
  2. $hook - The name of the action the widget area is hooked into.
  3. $priority - Used to specify the order in which the widget area is executed (default: 10). Lower numbers correspond with earlier execution, and widget areas with the same priority are executed in the order in which they were recieved.

The second and third parameters of remove_widget_area() are optional unless you registered your widget area to an action hook using create_widget_area().

That’s all there is to the Widgets API in WP Framework. If you have any questions or need help, stop by the forums!

Download WP Framework

Discuss WP Framework

Stop by the forums and get help with your customizations!

    It Seem There Is Something Wrong With BBLD Configuration, Please Check It.

WP Framework on Twitter!

Follow WP Framework and stay in the loop on WP Framework happenings!