Dashlets

A New Dashlet

Figuring out what you want the dashlet to do is probably the hardest part of creating a new dashlet. Just like in the component example, we've already made the decision. We're going to display the current plugin output of a particular service from a fused server.

This is good for a few reasons: 1) We're going to get to see some of the advanced functions that really help you build a distinguished dashlet, and 2) It introduces us to pulling data from the fused servers in a sane way.

So, just like in the component guide, we're going to perform the develoopment directly on the Fusion server. And just like last time, we can export our dashlet once it's been completed to share with the world.

We'll call our dashlet showoutput. Let's jump right in, create the working directory and create the files:

mkdir -p /usr/local/nagiosfusion/html/includes/dashlets/showoutput/
cd /usr/local/nagiosfusion/html/includes/dashlets/showoutput/
touch showoutput.inc.php
touch showoutput.php

The showoutput.inc.php file is the one required for Fusion to load the code that is present in that file - this will include the registering of the dashlet. The showoutput.php file will contain the actual dashlet.

So before we start, let's go over what exactly happens: when you register a dashlet with Fusion, you tell it a few things. Among those things, you tell it specific parameters that your dashlet accepts, along with the page that contains all of the code for the actual dashlet that is displayed. The parameters you specify are passed to the dashlet page as query parameters.

Whew! That was a mouthful. Now open up showoutput.inc.php with your favorite editor (vi showoutput.inc.php) and we'll start getting some code in there:

<?php

register_showoutput_dashlet();

function register_showoutput_dashlet() {

    $dashlet_opts = array(
        DASHLET_NAME        => 'showoutput',
        DASHLET_SERVER_TYPE => SERVER_TYPE_XI | SERVER_TYPE_CORE,
        DASHLET_VERSION     => '1.0.0',
        DASHLET_DATE        => '06/01/2017',
        DASHLET_AUTHOR      => 'Nagios Enterprises and Friends',
        DASHLET_DESCRIPTION => _('Show the output of a service'),
        DASHLET_COPYRIGHT   => '© 2017 Nagios Enterprises, LLC',
        DASHLET_HOMEPAGE    => 'www.nagios.com',
        DASHLET_LICENSE     => _('GPL v2'),
        DASHLET_LOAD_URL    => get_dashlets_base_url() . 'showoutput/showoutput.php',
        DASHLET_TITLE       => _('Show Output'),
        DASHLET_PARAMS      => 'get_dashlet_dependent_params',
        );

    register_dashlet($dashlet_opts);
}

Dashlet Options

So what'd we do? We called a register function, which built an array of options and passed it to register_dashlet! Just like our component counterpart function, we have a long list of data that we submit to the dashlet registration process.

Index	Explanation
DASHLET_NAME	REQUIRED - The short, unique name of the dashlet.
DASHLET_SERVER_TYPE	REQUIRED - What types of remote servers are you pulling data from? This is a bitmask built from SERVER_TYPE_XI and SERVER_TYPE_CORE.
DASHLET_AUTHOR	The author of the component. This is displayed with the component information.
DASHLET_DESCRIPTION	REQUIRED - A brief description of the component. This is displayed with the component information.
DASHLET_VERSION	The version of the component. This is displayed with the component information.
DASHLET_DATE	The date that this component was last updated. This is displayed with the component information.
DASHLET_COPYRIGHT	The copyright notice of the component. This is displayed with the component information.
DASHLET_LICENSE	The license applied to this component. This is displayed with the component information.
DASHLET_HOMEPAGE	The webpage about the author, or where to find more details about the component. This is displayed with the component information.
DASHLET_BGCOLOR	The default background color of the dashlet.
DASHLET_HEIGHT	The default height of the dashlet.
DASHLET_WIDTH	The default width of the dashlet.
DASHLET_PARAMS	This value is required if you plan on accepting variable parameters in the dashlet you create. It either accepts an array of predetermined values, or a function to call that returns an array of values when necessary. The section below will cover the parameters in more detail.
DASHLET_PREVIEW	The URL of the preview image of this dashlet. (Use get_dashlets_base_url() to build a relative URL).
DASHLET_TITLE	REQUIRED - The title to be displayed.
DASHLET_LOAD_URL	REQUIRED - The URL that the dashlet system loads (via ajax) from a dashboard. (Use get_dashlets_base_url() to build a relative URL).

Dashlet Parameters

In regards to the DASHLET_PARAMS index, using the function method is preferrable, because then Fusion isn't waiting for all the dashlets to generate their parameter arrays on every single instantiation. The format of the array required for DASHLET_PARAMS is as follows:

array(
    'param1' => array(
        'name'      => 'Human Readable Parameter Name',
        'options'   => array(
            'id'    => 'Drop Down Selection',
            'id2'   => 'Other option',
            'id3'   => 'Even another',
            ),
        'val' => 'id1',
        ), 

    'param2' => array(
        'name'      => 'A dependent field of param1',
        'dependent' => 'param1',
        'options'   => array(
            'p1'    => 'A field',
            'p2'    => 'Another!'
            ),
        ),
    );
    

Lucky for you, the function to grab a combination of servers/hosts/services already exists in Fusion. You can grab this data with get_dashlet_dependent_params($get_servers, $get_hosts, $get_services) (where the $get_* are booleans). This function is explained in greater detail on the Functions Reference page. If you have any other parameters you wish to use, you can merge this array with another that you've built. If you're only planning on allowing servers/hosts/services, then you can literally pass the string get_dashlet_dependent_params to DASHLET_PARAMS (like we do in our starter code above).

Dashlet Registration

Now that the dashlet has been registered, it builds an internal database containing all that helpful information. Now when you go to the 'Available Dashlets' page - and you click on the 'Dashletize' icon - when the dashletize modal pops up you'll notice that there are several available parameters. Some of those are the common ones such as background color, padding, refresh rate - but also the three we supplied with our use of the get_dashlet_dependent_params function: Server, Host, and Service!

So here's how it works:

• You select the properties of the dashlet and add it to a dashboard
• When you visit the dashboard, it passes each of those as query parameters to the page it loads via ajax per dashlet
• So in our case showoutput.php would become showoutput.php?server=1&host=localhost&service=someservice (as an example)

It's practically magic (it isn't magic)!

The Dashlet

Well, now we need to build the actual dashlet itself. So save the changes in showoutput.inc.php and open up showoutput.php (vi showoutput.php):

<?php
require_once(dirname(__FILE__) . '/../dashlet-helper.inc.php');

dashlets_data_check();
showoutput_dashlet();

function showoutput_dashlet() {

    get_dashlet_dependent_request_vars($server, $host, $service);

    $server = get_server($server);
    if ($server === false) {

        echo '<h3>Invalid server selection!</h3>';
        exit();
    }

    $service_status = get_server_polled_key($server, 'service_status', $limit = 1);
    $host_status = get_server_polled_key($server, 'host_status', $limit = 1);
    if (!isset($service_status[0]['service_status']) || !isset($host_status[0]['host_status'])) {

        echo '<h3>No recent data found for specified server!</h3>';
        exit();
    }

    $services = unpack_array($service_status[0]['service_status']);
    $hosts = unpack_array($host_status[0]['host_status']);
    if (!isset($services[$host][$service]) || !isset($hosts[$host])) {

        echo '<h3>No matching data found for host and service specified!</h3>';
        exit();
    }

    if (isset(($services[$host][$service]['output'])) {

        echo $services[$host][$service]['output'];

    } else {

        echo '<h3>No output found for that service :(</h3>';
    }
}

That's it! If you followed those steps properly you should be able to navigate to your 'Available Dashlets' page, see your dashlet, and add it to a dashboard! Note that if you didn't set a preview you'll likely see a blank section and possibly a warning - don't worry, this will go away as soon as you snap screen shot and enter in your proper DASHLET_PREVIEW array index.

Putting it All Together

Now let's cover each of the important parts that we blindly copied and pasted into our dashlet. It starts with require_once(dirname(__FILE__) . '/../dashlet-helper.inc.php'); - this is the file that gives you access to all of the functions built into Fusion.

Then we create a function and call it (we do this so as not to pollute the global space as much as possible). The first thing you'll see in the function is the function call for get_dashlet_dependent_request_vars. This function accepts three variables which it sets via reference. This is the helper function for get_dashlet_dependent_params - it automatically grabs the parameters set when you utilize that function.

After that you'll notice a few other functions being called - these are all explained in greater detail on the Functions Reference page. The main thing to take note is that after we unpack_array our server polled key we are left with a basic array. We do some basic sanity checking along the way, which is always recommended.

That's it for building a dashlet! Now you can navigate to the 'Manage Dashlets' page under your Fusion Administration navigation link, and select the 'Download this dashlet' icon present on your dashlet. It'll download as a zip file that you can upload to the Nagios Exchange and share with the world!