Widget Loader

Purpose

You can define SDK widgets using a JavaScript array. For this purpose, use the load method provided by the aps/load module:

load(widget-definition, placeAt);
  • widget-definition is the widget definition in the JSON format.

  • placeAt specifies the widget’s parent using one of the following:

    • DOM node

    • DOM node ID

    • Widget object

Usage

This method accepts two input arguments:

  • A JavaScript array describing a widget or an array of such arrays. An array describing a widget may have three elements:

    • Module name: the name of the module that builds the widget

    • Object: a set of widget properties

    • Array: an array containing arrays with a definition of child widgets

    Only the first element is mandatory. The remaining properties are optional. All properties of a specific widget see in API documentation. The third element is ignored for non-container widgets that cannot have child widgets..

  • The DOMNode ID or the DOMNode itself, in which the required widgets will be added. If you do not specify the second argument, the method will add the required widgets after all children in the Body node.

The method returns a promise for the requested widgets. This allows an application to wait for the creation of the widgets before processing them.

Warning

Do not process widgets immediately after calling the load method, because the latter does not complete creation of the requested widgets in such a short period. The following code is incorrect:

load([ "aps/ProgressBar", { id: "myProgBar", value: 35 } ]);
var pb = registry.byId("myProgBar");

In the following example, an application waits for the completion of the widget creation process and only then starts processing the requested widget:

load([ "aps/ProgressBar", { id: "myProgBar", value: 0 } ]).then(function(pb) {
   pb.set("value", 41);
});

If the load method creates an array of widgets, the then() method resolves the requested array of widgets as in the following example:

load([
    ["aps/TextBox"],
    ["aps/Output"]
]).then(function(arr){
    // arr - [<widget TextBox>, <widget Output>]
});

Examples

Standalone Widget

In the following example, a simple output widget is created from the aps/ProgressBar module.

require(["aps/load", "aps/Ready!"],
   function(load){
      load([ "aps/ProgressBar", { value: "35%" } ]);
});

The load uses only one array defining the needed wizard. The array contains the module name and the value property.

Widget with Child Widgets

The following example illustrates embedding one widget (aps/ProgressBar) into another (aps/Container).

require(["aps/load", "aps/Ready!"],
   function(load){
      load([ "aps/Container", { title: "Progress Bar" },
            [[ "aps/ProgressBar", { value: "35%" } ]] ]);
});

This time, the array contains the definition of the parent widget as well as the definition of its child.

List of Widgets

If you need to define a list of widgets, follow this example:

require(["aps/load", "aps/Ready!"],
   function(load){
      load([ [ "aps/CheckBox", {
               description:   "DNS zone management",
               hint:          "If granted, makes DNS service parameters act as a preset."
            }
          ], [
            "aps/CheckBox", {
               description:   "Hosting settings management",
               hint:          "If granted, makes the following hosting parameters act as a preset:
                               SSL support and support for programming and scripting languages,
                               custom error documents, and (Windows only)
                               Microsoft FrontPage support."
            }
          ], [
            "aps/CheckBox", {
               description:   "PHP safe mode management",
               hint:          "If granted, makes the hosting parameter \"PHP 'safe_mode'
                               on\" act as a preset."
            }
      ]]);
});

Note

There is only one argument that is an array containing other arrays, each defining a widget.