sidebar and widgets
Sidebar – is an area that take place on the left or on the right from main area. Usually on sidebar placed blog common or quick access elements. This elements called widgets.
Common examples: authors, tags, categories, etc.
In the world of WordPress widget is a plugin subtype. That is activation/deactivation of widgets realized thru the control panel of plug-ins.
Status control of widgets managed in the Design/Widgets panel. There you can add/remove widgets from/to sidebar and change their parameters.
1. How to add new widget
Since widget is plug-in it is behavior like common plug-in in WordPress. In other words it is php-script which placed in directory/subdirectories “/wp-content/plugins”. For correct information representation widget(plug-in) should has header like above:
/*
Plugin Name: Simple Wordpress Sidebar Widget
Plugin URI: http://open.helion-prime.com/Simple-Wordpress-Sidebar-Widget
Description: Simple wordpress sidebar widget.
Version: 1.0
Author: Helion-Prime Solutions Ltd.
Author URI: http://helion-prime.com/
*/
‘Plugin Name’ field described symbolic plug-in name in the system.
‘Plugin URI ‘ contains link to plug-in description.
‘description’ description.
‘version’ version
‘Author’ author name
‘Author URI’ uniform resource identifier
In the upshot in order to add new widget to the system we should:
create file “simple-sidebar-widget.php”
add to file described header
copy file to directory “/wp-content/plugins”
Then in the plug-in control panel we have new plug-in with our name:
‘Simple Wordpress Sidebar Widget’
simple-sidebar-widget.php
<?php
/*
Plugin Name: Simple Sidebar Widget
Plugin URI: http://open.helion-prime.com/Simple-Wordpress-Sidebar-Widget
Description: Simple wordpress sidebar widget.
Version: 1.0
Author: Helion-Prime Solutions Ltd.
Author URI: http://helion-prime.com/
*/
?>
2. Plug-in registration
In the first step we have added simplest plug-in (but not widget yet)
In order to transform it to the widget, we should register it.
Code for sidebar registration:
function simple_sidebar_widget_content_gen($args) {
}
function simple_sidebar_widget_register() {
if (!function_exists('register_sidebar_widget')) {
return;
}
register_sidebar_widget(__('Simple Sidebar Widget ', 'simple-sidebar-widget'),
'simple_sidebar_widget_content_gen');
}
add_action('init', 'simple_sidebar_widget_register');
To work widget should contain at least 2 functions:
*initialization (here simple_sidebar_widget_register)
*content generation (here simple_sidebar_widget_content_gen)
To get control in the our code we should create hook on some event. We have 2 events to select from. In our case I have selected ‘init event’ (raised when system loaded and initialized).
Hook created with help of add_action function, as parameter to it passed ‘name of event’ (init) and name of handler function (simple_sidebar_widget_register).
If event raised function simple_sidebar_widget_register receive control and perform following actions:
*check possibility to create widget with help of accessibility of widget registration function – function_exists(’register_sidebar_widget’).
* if required function is accessible it register widget
As you see register_sidebar_widget function receive 2 parameters:
first contain localized name of widget in the widget control panel.
second link to functionality of content-generator (’simple_sidebar_widget_content_gen’).
Now we have full-fledged widget that can be viewed in the widget control panel, it can be added to sidebar (don’t forget to activate it in the plug-in control panel).
3. Representation
If you add our widget to the sidebar it will not show anything. To find any result :) you should add function of content generation in the following way:
function simple_sidebar_widget_content_gen($args) {
extract($args);
$title = __('Simple Sidebar Widget ', 'simple-sidebar-widget');
$widget_content = __('This is simple sidebar widget', 'simple-sidebar-widget');
echo $before_widget ;
echo $before_title . $title . $after_title;
echo '<p>'.$widget_content .'</p>';
echo $after_widget;
}
First thing that we do is from array of arguments of function that extract variables we create set of variables.
Mainly it is special variables that should be used. Then we create content of widget: in fixed order we output values of special(which contain basic widget markup) and defined variables.
Now we can see our widget on sidebar.
4. Widget setup
If you want to have possibility to setup widget you should change code to the following:
function simple_sidebar_widget_control_gen($widget_content, $show_content) {
?>
<p>
<label for="widget-content"><?php _e('Content:', 'simple-sidebar-widget'); ?>
<input class="widefat"
id="widget-content" name="widget-content"
type="text" value="<?php echo attribute_escape($widget_content); ?>"
/>
</label>
</p>
<p>
<label for="show-content">
<input class="checkbox" type="checkbox"
id="show-content" name="show-content"
<?php echo $show_content ? 'checked="checked"' : ''; ?>
/>
<?php _e('Show content.', 'simple-sidebar-widget'); ?>
</label>
</p>
<input type="hidden"
id="simple-sidebar-widget-submit" name="simple-sidebar-widget-submit"
value="1"/>
<?php
}
function simple_sidebar_widget_control() {
$options = $newoptions = get_option('simple_sidebar_widget');
if ($_POST['simple-sidebar-widget-submit']) {
$newoptions['widget-content'] = strip_tags(stripslashes($_POST['widget-content']));
$newoptions['show-content'] = isset($_POST['show-content']);
}
if ($options != $newoptions) {
$options = $newoptions;
update_option(’simple_sidebar_widget’, $options);
}
simple_sidebar_widget_control_gen(
$options['widget-content'], $options['show-content']);
}
function simple_sidebar_widget_content_gen($args) {
extract($args);
$title = __(’Simple Sidebar Widget ‘, ’simple-sidebar-widget’);
$options = get_option(’simple_sidebar_widget’);
$show_content = $options['show-content'] ? true : false;
$widget_content =empty($options['widget-content']) ?
__(’This is simple sidebar widget’, ’simple-sidebar-widget’) :
$options['widget-content'];
echo $before_widget ;
echo $before_title . $title . $after_title;
if ($show_content) {
echo ‘<p>’.$widget_content .’</p>’;
}
echo $after_widget;
}
function simple_sidebar_widget_register() {
if (!function_exists(’register_sidebar_widget’)) {
return;
}
register_sidebar_widget(__(’Simple Sidebar Widget ‘, ’simple-sidebar-widget’),
’simple_sidebar_widget_content_gen’);
register_widget_control(__(’Simple Sidebar Widget ‘, ’simple-sidebar-widget’),
’simple_sidebar_widget_control’);
}
What changed in our code:
In function ’simple_sidebar_widget_register’ one invocation added (’register_widget_control’), it register function which catch widget configuration change event (’simple_sidebar_widget_control’).
In the generator of widget content additional code added that receives current configuration of widget get_option(’simple_sidebar_widget’).
Here parameter ’simple_sidebar_widget’ is identifier of parameters set that used in our widget.
Then into variables $show_content and $widget_content extracted current values of parameters.
As I already noted for event processing of configuration changes we should add appropriate event-handler function (’simple_sidebar_widget_control’). In this function we extract parameters from request and analyze changes, also this function create content of configuration form (this functionality moved to ’simple_sidebar_widget_control_gen’).
After we added above code in the parameters of widget we have 2 fields.
One field contains content that should be outputted.
Second field is a switch which allow/forbid output of content.
In closing I want to note that widgets work only with themes that support sidebar.
Described methodology work for WordPress >=2.5, although it is almost the same for previous versions.
related links:
plug-in development - http://codex.wordpress.org/Writing_a_Plugin
list of actions - http://codex.wordpress.org/Plugin_API/Action_Reference
localization: http://codex.wordpress.org/Translating_WordPress
