Creating Dashboard Widgets

Getting Started

Creating widgets is simple. First, create the html code for the widget, save it to a file named widget_name.widget.php, and put it into the /usr/local/www/widgets/widgets directory on the firewall.

Do not include any <body>, <html>, or $pgtitle definitions, etc. Only include basic HTML code for what needs to be displayed. Examine the current widget source code for examples.

The file must be named in the my_name.widget.php format. No spaces are allowed in the filename. The name the GUI displays is the name of the file. For example the Traffic Graphs widget file is named traffic_graphs.widget.php.

And that’s it! The dashboard handles the rest of the widget behavior (e.g. buttons, border, dragging, sequence, etc.) automatically.

To include custom code into the widget upon rendering:

PHP:

Create a file named widget_name.inc and place the .inc file in the /usr/local/www/widgets/include directory.

JavaScript:

Create a file named widget_name.js and place the .js file in the /usr/local/www/widgets/javascript directory.

Saving Data

Saving configuration data for a widget requires more work and is beyond the scope of this document. Look at the source code for existing widgets which have settings and follow their example, including:

  • The form for the settings and all related fields, save button, etc.

  • Input validation

  • Storing settings by writing the configuration

  • Redirect the user back to the dashboard

Customizing the Title and Linking to page

By default the name of the widget file is what is shown on the Widget in the dashboard. This title can be changed and also have a link to another page inserted.

To configure the widget to use a certain name other than the name of the file, create an .inc file with the same base name as the widget and place that file into the /usr/local/www/widgets/include directory.

For example if a widget is named abc.widget.php, the include file must be abc.inc.

In this .inc file use the following code:

<?php //set variable for custom title
$abc_title = "A B C custom";
$abc_title_link = "abc.php";
?>

Use the widget name in the variable names as shown in the example.

An example of these values can be taken from the interfaces.inc file for the Interfaces widget:

<?php [...]
$interfaces_title = gettext("Interfaces");
$interfaces_title_link = "status_interfaces.php";
?>