====== Widget creation ======

===== Introduction =====

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.

===== Plugin conception =====

==== Definition ====

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

<code php>
<?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'
);
?>
</code>

==== Widget creation and administration ====

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

<code php>
<?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'));
	}
}
?>
</code>

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.

<note important>
Beware not to reuse the ID of an existing widget. It is still possible to do it if you clearly want to replace an existing widget.
</note>

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:

<code php>
<?php
if (!defined('DC_CONTEXT_ADMIN')) { return; }

require dirname(__FILE__).'/_widgets.php';
?>
</code>

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.

==== Widget display ====

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

<code php>
<?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>';
	}
}
?>
</code>
<note>
Inclusion of **_widgets.php** in **_public.php** allows the widget to be included directly in the template files through the <tpl:Widget> tag. This feature is available since Dotclear 2.1.
</note>

===== Advanced widget parameters =====

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

==== Adding options ====

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

<code php>
<?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));
	}
}
?>
</code>

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.

<note>
The **setting()** method of the widget takes an additional parameter containing the data when it is a **combo** option.
</note>

==== Use of options in the admin side ====

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

<code php>
<?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>';
	}
}
?>
</code>

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!