How to write a widget

Centreon offers a custom view system which allows the user to view one or more widgets on the same page: Home > Custom views.

You may have specific needs that are not yet covered by our widget catalog and this tutorial will explain to you how to write your first widget for Centreon.

Should I make a widget or a module?

If you are wondering if you should be making a module or a widget, then ask yourself if your project is meant to contain many menus, or is it rather a plain page that is going to display little information?

Of course, you could make a widget that would only work with a certain module.

Directory structure

Widgets work pretty much like Modules. They must be placed in the following directory:

centreon/www/widgets/name-of-your-widget\/

Your widget must contain one mandatory file named configs.xml at its root.

Configuration file

This is the XML configuration file of our Dummy widget:

<configs>
    <title>Dummy</title>
    <author>Centreon</author>
    <email>contact@centreon.com</email>
    <website>http://www.centreon.com</website>
    <description>Dummy widget</description>
    <version>1.0.3</version>
    <keywords>dummy, widget, centreon</keywords>
    <screenshot></screenshot>
    <thumbnail>./widgets/dummy/resources/logoCentreon.png</thumbnail>
    <url>./widgets/dummy/index.php</url>
    <autoRefresh></autoRefresh>
    <preferences>
        <preference label="text preference" name="text preference" defaultValue="default value" type="text"/>
        <preference label="boolean preference" name="boolean preference" defaultValue="1" type="boolean"/>
        <preference label="date" name="date" defaultValue="" type="date"/>
        <preference label="host preference" name="host preference" defaultValue="" type="host"/>
        <preference label="list preference" name="list preference" defaultValue="none" type="list">
            <option value="all" label="all"/>
            <option value="none" label="none"/>
        </preference>
        <preference label="range preference" name="range preference" defaultValue="5" type="range" min="0" max="50" step="5"/>
        <preference label="host search" name="host search" defaultValue="notlike _Module_%" type="compare"/>
    </preferences>
</configs>

Now, let's see what these tags refer to.

Basic tags

* = Mandatory tag

Tag name	Description
title*	Title of your widget
author*	Your name
email	Your email address
website	URL of your project
description*	Short description of your widget
version*	Version of your widget. Increment this number whenever you publish a new version.
keywords	A few key words that describe your widget
screenshot	Screenshot that shows the best side of your widget. Screenshot should be placed within your widget directory.
thumbnail	Logo of your project. Best size is 100px x 25px. Thumbnail should be placed within your widget directory.
url*	Path of the main page of your widget
autorefresh	This parameter is not implemented yet

Parameter attributes

* = Mandatory parameter

Tag attributes	Description
label*	Label of the parameter
name*	Name of the parameter that will be used for retrieving its value
defaultValue*	Default Value of the parameter
requirePermission	Value can be "1" or "0". When set to 1, this parameter will not be shown to unauthorized users.
type*	Parameter type, must be one of the following: text,boolean,date,list,range,compare,host,hostgroup, hostTemplate,servicegroup,serviceTemplate
min*	For range type only. It refers to the minimum value of the range parameter
max*	For range type only. It refers to the maximum value of the range parameter
step*	For range type only. It refers to the step value of the range parameter

Parameter type

Tag name	Description
text	Renders a text input element
boolean	Renders a checkbox
date	Renders two text input elements. One for the start date, the other one for the end date.
list	Renders a selectbox. The selectbox will be populated with the option tags, which must be defined within the preference tag.
range	Renders a selectbox which will be populated with values depending on the min, max and step definitions.
compare	Renders a selectbox and a text input. Selectbox will contain SQL operands such as:
	> : greater than
	< : less than
	>= : greater or equal
	<= : less or equal
	= : equal
	!= : not equal
	LIKE : can be used with the wildcard %%
	NOT LIKE : can be used with the wildcard %%
host	Renders a selectbox populated with a list of hosts.
hostgroup	Renders a selectbox populated with a list of hostgroups.
hostTemplate	Renders a selectbox populated with a list of host templates.
servicegroup	Renders a selectbox populated with a list of servicegroups.
serviceTemplate	Renders a selectbox populated with a list of service templates.

The preference window would look like this as a result:

.. image:: /_static/images/extending/pref_dummy_widget.png :align: center

Code

All languages are separated in different files, one file for each language. The file "configs.xml" calls the PHP file and the PHP file calls the HTML file, etc.

We use Smarty, which is a template engine for PHP (http://smarty.net).

To use Smarty you need to proceed as follows:

require_once $centreon_path . 'GPL_LIB/Smarty/libs/Smarty.class.php';

1.configuration of smarty:

$path = $centreon_path . "www/widgets/Dummy/src/";
$template = new Smarty();
$template = initSmartyTplForPopup($path, $template, "./", $centreon_path);

2.creating a PHP template to be use in HTML:

$template->assign('widgetId', $widgetId);
$template->assign('autoRefresh', $autoRefresh);
$template->assign('data', $data);

3.affectation of html's file to execute:

$template->display('dummy.ihtml');

This line asks PHP to call the dummy.ihtml smarty template to display the results:

$template->display('dummy.ihtml');

To query the databases (centreon for the configuration and centstorage for the real time data), you must initialize the PHP object as described below (using pearDB):

try {
    global $pearDB;

    $db_centreon = new CentreonDB("centreon");
    $db = new CentreonDB("centstorage");
    $pearDB = $db_centreon;

    $widgetObj = new CentreonWidget($centreon, $db_centreon);
    $preferences = $widgetObj->getWidgetPreferences($widgetId);
    $autoRefresh = 0;
    if (isset($preferences['refresh_interval'])) {
        $autoRefresh = $preferences['refresh_interval'];
    }
} catch (Exception $e) {
    echo $e->getMessage() . "<br/>";
    exit;
}

Then query the database using the class methods.