Dotclear widgets are very simple little pieces of code used to display miscellaneous information in the blog sidebars.

We are going to see how to create a simple widget.

As usual, we start by creating a directory within the plugins directory and we create a _define.php file:

<?php
if (!defined('DC_RC_PATH')) { return; }
 
$this->registerModule(
	/* Name */			"My first widget",
	/* Description*/		"This is my first widget",
	/* Author */			"Peter McAlloway",
	/* Version */			'1.0',
	/* Permissions */		'admin'
);
?>

Once this is done, we are going to create a special file named _widgets.php containing the following code:

<?php
if (!defined('DC_RC_PATH')) { return; }
 
$core->addBehavior('initWidgets',
	array('myWidgetBehaviors','initWidgets'));
 
class myWidgetBehaviors
{
	public static function initWidgets($w)
	{
		$w->create('MyWidget',__('My first widget'),
			array('publicMyWidget','myWidget'));
	}
}
?>

This first piece of code is very simple. The first line calls the initWidgets behavior and indicates to call the initWidgets static method from the myWidgetBehaviors class. This class is defined just after and the method simply creates the widget.

The initWidgets function gets the object containing the widgets as an argument. The only line of this method launches the widget creation.

The create method from the object passed in argument takes the following parameters:

• The widget ID
• The widget name
• A valid callback to display the widget in the public part of the blog

Put it another way, here we say: create a widget identified by MyWidget, called My first widget and calling the static method myWidget from the publicMyWidget class.

We are now going to make this widget available in the admin part of the blog. To do so, edit the _admin.php file and add the following lines:

<?php
if (!defined('DC_CONTEXT_ADMIN')) { return; }
 
require dirname(__FILE__).'/_widgets.php';
?>

After that, you will see your widget in the list of available widgets. But we are still missing a very important element: what the widget does on the public part of the blog.

We create a _public.php file and we put the following lines:

<?php
if (!defined('DC_RC_PATH')) { return; }
 
require dirname(__FILE__).'/_widgets.php';
 
class publicMyWidget
{
	public static function myWidget($w)
	{
		return '<p><strong>Hello World!</strong></p>';
	}
}
?>

The widget we just created does not do much for the moment and it would be good to add a few options or parameters.

We open _widgets.php and we modify the code so it looks like this:

<?php
if (!defined('DC_RC_PATH')) { return; }
 
$core->addBehavior('initWidgets',
	array('myWidgetBehaviors','initWidgets'));
 
class myWidgetBehaviors
{
	public static function initWidgets($w)
	{
		$w->create('MyWidget',__('My first widget'),
			array('publicMyWidget','myWidget'));
 
		$w->MyWidget->setting('title',__('Title:'),
			'default value','text');
 
		$w->MyWidget->setting('checked',__('checkbox'),
			true,'check');
 
		$w->MyWidget->setting('text',__('Text:'),
			'','textarea');
 
		$w->MyWidget->setting('option',__('Options:'),
			null,'combo',array('opt1' => 1, 'opt2' => 2));
	}
}
?>

As you can see, there are 4 new lines in the code. Each of them add a different option to the MyWidget widget. To add an option to a widget we call the $w→MyWidget→setting() method, where MyWidget is the widget ID. These 4 lines do the following:

• We add a title option called "Title:" having "default value" as the default value and typed text (simple text field).
• We add a checked option called "checkbox", checked by default and typed check (checkbox).
• We add a text option called "Text:" with no default value and typed textarea (longer text field).
• We add an option option called "Options:" with no default value and typed combo (combo list).

These are all the possible option types that can be used for a widget.

Now we have a customizable widget, we can modify the _public.php file to match this:

<?php
if (!defined('DC_RC_PATH')) { return; }
 
require dirname(__FILE__).'/_widgets.php';
 
class publicMyWidget
{
	public static function myWidget($w)
	{
		return '<p><strong>Title: '.$w->title.'</strong></p>';
	}
}
?>

As you can see, to retrieve a widget option value, you just have to call $w→identifier_option. In our case, we could call $w→checked, $w→text, $w→option.

You now know (almost) everything. Happy coding!