There are four ways to specify an HTML element(s) for a widget. To recap, most widgets will require an element ID name. This ID links to an element, such as a <div>, in the HTML report page. Widgets can take one or more element IDs if required and there are numerous ways to define one.

By name
Custom function
Threshold
Calendar

By name

The simplest, and most common, way to define an element ID for a widget is to reference it by name.

So, if you wanted to put a graph widget in a <div> with an ID of 'graph' you would do this:

ele: ['graph']

Custom function

A JavaScript function can be defined as long as it returns a valid element ID. For example:

ele: ['getElement(||voip.jitter||,55)']

The getElement function would be passed the result for VoIP Jitter and the number 55. It would then simply have to return a valid element ID. Example below.

function getElement(jitter, number) {
    if(jitter < 100 && number > 0) return 'graph';
    return 'badgraph';
}

Threshold

Basing the element ID off a metric threshold can be useful. For example, if a result is good you may want text to appear in a specific place than when the result is bad.

An API function is provided to do just that. It can be used like this:

ele: ['ppf_eleThresh("!voip.jitter|bad", "threshtrue", "threshfalse")']

The first parameter is the threshold definition. In the example above we are testing if the VoIP Jitter result is NOT bad.

The second parameter is the element ID name when the threshold check is TRUE.

The third parameter is the element ID name when the threshold check is FALSE.

So, for the example above, if the VoIP Jitter result is found to be NOT bad the element ID threshtrue will be used. If the VoIP Jitter result IS bad then threshfalse will be used as the element ID.

The first parameter can also be an array of threhsolds. For example:

ele: ['ppf_eleThresh(["!voip.jitter|bad","!voip.loss|bad","!voip.mos|bad"], "threshtrue", "threshfalse")']

In this example all three treshold checks (Jitter not bad, loss NOT bad, and MOS not bad) would have to be true to pass the test.

Calendar

Basing the element ID off a calendar condition can be useful. For example, if a result is good you may want text to appear in a specific place depending on the day of the week.

An API function is provided to do just that. It can be used like this:

ele: ['ppf_eleCal("todayvalid","caltrue","calfalse")']

The first parameter is the calendar condition. In the example above we are testing if todayvalid is true for today. Remember you can use a leading exclamation point (!) to define the negative.

The second parameter is the element ID name when the calendar condition is TRUE.

The third parameter is the element ID name when the calendar condition is FALSE.

So, for the example above, if the calendar condition todayvalid is true the element ID caltrue will be used. If the calendar condition todayvalid is not true then calfalse will be used as the element ID.

Defining multiple elements

To define more than one element simply extend the array. Doing so will place the identical widget in each element. This can be useful for things like copyright statements that may appear on every page.

ele: ['ele1', 'ele2', 'ele3']

You can mix and match functions, thresholds, etc. as defined above.