====== Add an icon to the dashboard ======

===== Introduction =====

Sometimes, a plugin needs to display information relative to its operation directly in the dashboard. For instance, the daInstaller plugin adds an orange icon when updates are available. This page will explain you how to get to this result.

===== Adding a favorite icon =====

Dotclear 2.3 introdcued a new user interface that allowed users to define their own favorites. Here is how a plugin can add an icon to the list of available icons:

In the plugin ''_admin.php'' file:

<code php>
$core->addBehavior('adminDashboardFavs',array('myPluginBehaviors','dashboardFavs'));

class myPluginBehaviors
{
    public static function dashboardFavs($core,$favs)
    {
        $favs['myplugin'] = new ArrayObject(array(
            'myplugin',
            __('My Plugin'),
            'plugin.php?p=myplugin',
            'index.php?pf=myplugin/icon.png',
            'index.php?pf=myplugin/icon-big.png',
            'usage,contentadmin',
            null,
            null));
    }
}
</code>

The arguments to provide when calling the ''dashboardFavs()'' function are:

  * Favorite identifier (with no space, accent, …), must be unique
  * Favorite label
  * Favorite URL (can be almost anything)
  * Icon URL (16x16 pixels)
  * Icon URL (64x64 pixels)
  * Permissions (use **null** to deny everyone but superadmin, use **'*'** to allow everyone)
  * ID (optional) added in the favorites menu item (on the left)
  * class (optional) added in the favorites menu item (on the left)

A plugin can register as many favorites as needed. The icons used in Dotclear come from a package made specially for Dotclear, check [[http://dotclear.org/blog/post/2011/11/13/Dotclear-2.4|the Dotclear 2.4 announcement post]] for more information.

Moreover, the plugin can customize the information (title, small icon and big icon) of a favorite registered and displayed on the dashboard.

Here is how:

In the plugin''_admin.php'' file:

<code php>
$core->addBehavior('adminDashboardFavsIcon',array('myPluginBehaviors','dashboardFavsIcon'));

class myPluginBehaviors
{
    public static function dashboardFavsIcon($core,$name,$icon)
    {
        if ($name == 'myplugin')
        {
             $icon[0] = __('My plugin');
             $icon[1] = 'plugin.php?p=myplugin';
             $icon[2] = 'index.php?pf=myplugin/icon-big.png';
        }
    }
}
</code>

The arguments to provide when calling the ''dashboardFavsIcon()'' function are:

  * Favorite identifier (with no space, accent, …), same as the one used when registering
  * An array containing:
    * Favorite title
    * Favorite URL
    * The 64x64 pixels icon URL

The link name, the URL and the image can be modified according to the tests added in ''dashboardFavsIcon()''.


<note related>
The [[admin#download-the-example-plugin|adminExample]] plugin provide a code example.
</note>