Find Out How

Print Friendly Version

Create a New Custom Widget

Use the following steps to create a new custom widget for use in your dashboards. If you'd like to add an existing widget, see Add a Widget. The default widget created will be a "Hello, World" widget that will require further programming. Refer to the Widget Library API below.

  1. Navigate to Central > Dashboards.

    2. If you're creating a new dashboard, give it a name.

Dashboards list

Enter a name for the widget. For example, MyWidget.

Select a category for the new widget. We recommend Custom for user-created widgets, but any category can be chosen or a new one created.

 

Enter a class name. For example, MyWidgetClass.

 

In the Type drop-down, select from among Unspecified, Composition/Result, Monitor, and Utility. If you're not sure, choose Utility.

Optionally, enter a description of the new widget.

 

The Widget Editor populates the code field with sample code based on the class name provided.

 

Click OK when you are done.

The widget is created and added to the dashboard in the location where Add New Widget was clicked.

 

Widget Library API Reference

Creating a New Custom Widget in SOASTA CloudTest produces a new MyWidget widget that presents the API as a template and is intended for user editing.

The template code defines a WidgetLogic() class for SOASTA CloudTest, MyWidget. It then instantiates the class and provides an example use of methods, parameters and arguments. For example, typing MyWidget as a class name will result in the following class:

MyWidget.prototype = new WidgetLogic();

MyWidget()

An example MyWidget() instance is defined.


function MyWidget()

The Start Method

start

Calls to start the widget when it should draw its contents. This method will be called once per dashboard load, the widget is then responsible for updating itself thereafter.

Start Useful Methods

this.getResultIDs() returns the active result ID(s), if applicable (null otherwise)
this.getMonitorIDs() returns the active monitor ID(s), if applicable (null otherwise)
this.saveCustomSettings() saves the widget custom settings immediately (useful for persisting user settings/data)

MyWidget.prototype.start = function()
{

}

"Start" Useful Fields

this.canvas The HTML element into which the widget should add DOM elements
this.widget

The Widget Object, which contains:

  • customSettings

    • an associative array (JS object) that contains any user-specified settings for this widget

  • id

    • a unique identifer (whole number) for the widget

  • color

    • the user-defined color of the widget

  • title

    • the user-defined title of the widget

  • displayName

    • the widget's default display name

  • height

    • the user-specified custom height of the widget, or -1 if the user has not specified a height.
 

Other Methods

destroy

This function, if defined, will be called once if the widget is removed from a dashboard.

MyWidget.prototype.destroy = function()
{

}

getCustomSettingsPanelHTML

This function, if defined, can return a string of HTML which will be added to the widget's edit panel. This allows the user to specify widget custom settings that can be accessed in the start() method via the "customSettings" field.

MyWidget.prototype.getCustomSettingsPanelHTML = function()
 {

 }

hideLoadingIndicator()

Hides the loading indicator image for the widget.

  

hidePausePlayButton()

Hides a previously-shown pause/play button.

hidePausePlayButton()

isPaused()

Returns true if the widget is paused. This function should be called prior to doing any refresh if the widget supports the pause / play button.

isPaused()

isWidgetVisible

Returns true if the widget is visible, false otherwise.

isWidgetVisible()

onChangeResultIDNotification()

This is called when the current active result ID changes (either by user selection or by playing a composition)

  

onWidgetResize

This function, if defined, will be called when a widget is resized. Usually this function does not need to be defined. You only need to do so if you have special rendering code in your widget that needs the size of the container.

MyWidget.prototype.onWidgetResize = function(newSize)
 {

 }

setPrintLayout

If this widget needs to render itself differently for print layout, you can use this function to do so. When the widget is ready to be printed, call the "callbackFunction" that is passed in.

    Parameters:

  • bForPrinting

    • Boolean. True, if the widget should draw for print layout, false, if the widget should draw for normal screen layout.

  • oLayoutArg

    • Contains user-selected layout options:

    • .paperSize – paper size, such as "Letter", "Legal", "A4", etcetera
    • .orientation – paper orientation, either "portrait" or "landscape"
  • callbackFunction

    • The function that must be called after the widget is finished with layout changes.

MyWidget.prototype.setPrintLayout = function(bForPrinting, oLayoutArgs, callbackFunction)
{
callbackFunction();
}

setPaused(bPaused)

Sets the widget's pause / play state.

    Parameters:

  • bPaused

    • Boolean. True, if paused; false, for play.

setPaused(bPaused)

showLoadingIndicator()

Shows a loading indicator image for the widget.

showLoadingIndicator()

showPausePlayButton()

If desired, a widget can call this to show a pause/play button.

showPausePlayButton()

togglePaused()

Toggles the widget's pause / play state.

togglePaused()

©2010 SOASTA, Inc