Creating Widget Templates

Widgets are used on the Home>Dashboard page. Traffic Sentinel is delivered with a number of standard widgets that can be configured to display many types of data (see Customizing the Dashboard tutorial).

Traffic Sentinel's widget function makes use of template documents written in XML (eXtensible Markup Language). The XML document specifies the structure of the widget (the title, description, inputs and links). Scripts contained in the widget template are used to construct queries, process results and add tables and charts to the report.

This tutorial describes how to build and install widget templates that add new functionality to Traffic Sentinel. Before proceeding with this tututorial it is worth studying the Scripting Queries tutorial since the it introduces the scripting capabilities of Traffic Sentinel.

XML

The following example illustrates the basic elements of a template. First, create a new template file, time.xml with the following contents:

<widget name="Time" type="html" refresh="60">
  <link>http://www.inmon.com/tutorials2/widgettemplate.php</link>
  <description>This widget contains tutorial Time example.</description>
  <input name="datefmt" type="string" label="Format" value="yy-mm-dd HH:mm"/>
  <script><![CDATA[
print("<p>");
print(formatdate(new Date(), datefmt));
println("</p>");
  ]]></script>
</widget>

This simple example demonstrates the basic components of a widget template. Each widget is given a name and a type (and optionally a refresh time in seconds). There are two supported widget types:

html The widget displays HTML formatted text.
png The widget will display a chart.

The link contains a reference to additional information associated with the widget (in this example a reference to this page). The description provides additional information about the widget. A single input is defined that provides an argument to the script.

Use the Home>Install page to install a new template file (the file must have a .xml extension).

Scripting

The Scripting Queries described some of the basic scripting techniques in Traffic Sentinel. Generally the best approach to devoloping a new script is to experiment with the script using the Report>Script interface. Once the basic query is working, it can be incorporated into a widget template.

Traffic Sentinel provides additional Javascript functions for use in widget templates.

print() and println()

The time.xml example showed how the print() and println() functions can be used to generate HTML output. Care must be taken to generate well formed HTML that will display within the space allowed for widget output. Badly formed HTML can cause problems with the whole widget page.

Widget

The Widget class provides functions to simplify the display of information in the widget. The following sections show how the Widget class is used to display tables and charts.

Table

The Table class is used to represent tabular data. The tutorial Scripting Queries shows how tables are returned by queries. The following script shows how a query result can be added to a widget.

<widget name="Top IP Sources Table" type="html" refresh="60" >
  <description>Top sources of bytes.</description>
  <input name="interval" type="interval" value="last5minutes" >
    <option value="last5minutes" >Last 5 Minutes</option>
    <option value="last10minutes" >Last 10 Minutes</option>
  </input>
  <script><![CDATA[
var w = Widget.current();
var q = Query.topN("rttraffic","ipsource,bytes",null,interval,"bytes",5);
var table = q.run();
w.table(table);
  ]]></script>
</widget>

Note The widget generates type is set to html because a table will be displayed. The widget will refresh its contents every 60 seconds. The widget script makes use of one input, interval with default value last5minutes respectively.

Chart

The Chart class is used to construct a chart for inclusion in a widget.

The following example shows how a chart can be constructed from the tabular result of a query.

<widget name="Top IP Sources Chart" type="png" refresh="60">
  <description>Chart showing top IP sources by number of bytes.</description>
  <input name="interval" type="interval" value="last5minutes" >
    <option value="last5minutes" >Last 5 Minutes</option>
    <option value="last10minutes" >Last 10 Minutes</option>
  </input>
  <script><![CDATA[
var w = Widget.current();
var q = Query.topN("rttraffic","ipsource,bytes",null,interval,"bytes",5);
var table = q.run();
var chart = Chart.singleSeries(
              "bar", "Top IP Sources",
              table, "IP Source", 0, "Bytes", 1);
w.chart(chart);
  ]]></script>
</widget>

Inputs

The <input /> tags are an important part of the widget template, allowing values to be edited on the Dashboard page (see Customizing the Dashboard). Inputs allow multiple copies of a widget to be instantiated, each with different settings.

An input can have the following attributes:

name the name of the variable that will be created in javascript.
type the type of the variable (see below).
label a user friendly name that will be used in forms to label the input field.
value a default value for the variable.
required by default all inputs must be provided before the script will be run. Setting required to "false" makes the input optional.

Every input must have at least a name and a type.

If an input represents an enumerated type (i.e. it can only have one of a fixed set of values) then <option> values can be used (see the first chart example).

If an input is optional (i.e. required = "false") then the script must not assume that the variable exists. The following fragment shows how the existance of an optional input can be tested

<input name="height" type="integer" />
<script><![CDATA[
var h = 100;
if(typeof(height) != 'undefined') h = height;

Input types are used to check values and ensure that they are valid. When input values are entered into a form they will be checked and the user will be notified if an input has in invalid value. In addition the type of the input is used to provide assistance to the user by providing common options to enter into the input field.

The following types are defined:

string any string is allowed.
integer a positive integer or zero is allowed.
address any address is allowed. Addresses can be further constrained by appending an address type (e.g. address.ip only allows ip addresses).
subnet a subnet (specified in CIDR notation) is allowed.
protocol any protocol (e.g. TCP:80) is allowed. If you want to limit inputs to a particular protocol type then appending the type will further constrain the input (e.g. protocol.TCP will only allow TCP protocols).
agent allows an agent address.
interface allows a switch/router port.
path allows site>zone>group>agent style path to specify a part of the network.
view a view input is used to obtain attribute names from a database view. A view input must always be qualified by a view name (e.g. view.historytrmx or view.rttraffic). Optionally, a view input can be further qualified as a key or a value (e.g. view.historytrmx.key).
filter a filter input is used to obtain a boolean filter expression that can be applied in a query. The filter input must always be qualified with a view name (e.g. filter.historytrmx).
interval a time token that can be used to specify an interval in a query (e.g. "today").
group a time grouping used in a trend query (e.g. "hour").

If a type ends in the token [] then a comma separated list of values of the specified type is allowed (e.g. view.rttraffic.key[]).

Support