Skip to main content
Version: ⭐ 24.10

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 nameDescription
title*Title of your widget
author*Your name
emailYour email address
websiteURL of your project
description*Short description of your widget
version*Version of your widget. Increment this number whenever you publish a new version.
keywordsA few key words that describe your widget
screenshotScreenshot that shows the best side of your widget. Screenshot should be placed within your widget directory.
thumbnailLogo 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
autorefreshThis parameter is not implemented yet

Parameter attributes

* = Mandatory parameter

Tag attributesDescription
label*Label of the parameter
name*Name of the parameter that will be used for retrieving its value
defaultValue*Default Value of the parameter
requirePermissionValue 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 nameDescription
textRenders a text input element
booleanRenders a checkbox
dateRenders two text input elements. One for the start date, the other one for the end date.
listRenders a selectbox. The selectbox will be populated with the option tags, which must be defined within the preference tag.
rangeRenders a selectbox which will be populated with values depending on the min, max and step definitions.
compareRenders 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 %%
hostRenders a selectbox populated with a list of hosts.
hostgroupRenders a selectbox populated with a list of hostgroups.
hostTemplateRenders a selectbox populated with a list of host templates.
servicegroupRenders a selectbox populated with a list of servicegroups.
serviceTemplateRenders 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.