Widget Constructors

SDK widgets may be defined by means of JavaScript constructors of the respective modules.

Usage

For this purpose, you need first to declare SDK modules, which will be used in the view, and associate the names of constructors with them in the main call-back function.

To define and activate a widget in a view, go through the following steps when creating the view:

1. Declare the SDK module that contains the wizard definition, for example:

   require(["aps/Button", "aps/ready!"],...);
   

2. In the main call-back function, associate the names of constructors with the declared modules.

   function(Button) {...}
   

3. In the main call-back function, create the needed wizard by means of the associated constructors. If you are going to use the startup() method, specify the place for the wizard on the screen. It is “idDiv” in the following example.

   var btn = new Button( {
      id: "example1",
      label: "I am simple button"
   }, "idDiv");
   

4. Activate needed wizards using one of the following ways:

   • startup method:

     var btn = new Button( {
        id: "example1",
        label: "I am simple button"
     }, "idDiv");
     btn.startup();
     

   • placeAt method:

     var btn = new Button( {
        id: "example1",
        label: "I am simple button"
     });
     btn.placeAt("idDiv");
     

In the following example, a button is defined and activated:

<div id="idDiv"></div>

require(["aps/Button", "aps/ready!"],
   function(Button) {
      var btn = new Button( {
         id: "example1",
         label: "I am simple button"
      }, "idDiv");
      btn.startup();
});

Methods

Method	Arguments	Description
Widget Constructor	List of widget properties ID of an HTML DOM node to place the widget (optional)	Creates a widget and, optionally, places it in the defined HTMLNode
placeAt	HTML DOM node or its ID Insertion type	The insertion type specifies a relative place around the specified DOM node to insert the wizard
addChild	Child widget Insertion type	The insertion type specifies a relative place around the parent to insert the specified child wizard
removeChild	Child widget	Removes the specified child wizard
removeAll	-	Removes all child wizards

Constructor

A constructor may accept two arguments: an object with the properties of the element being created and the ID of an HTML DOM node in place of which you need to insert the element. If you do not specify the second element, then the wizard after its creation will not be inserted into DOM, and the DOM node that represents it will be saved in the domNode property of the object being created.

Widget Hierarchy

To add child elements to a widget, you need to use the addChild method, which accepts as the first argument the object of a child widget and as the second argument - an insertion type (see the above table). You can delete a child element using the removeChild method, to which you need to pass the object of the child element. There is also the removeAll method you can use to delete all child elements of a widget.

<div id="idDiv"></div>

require(["aps/Container", "aps/Button", "aps/ready!"],
   function(Container, Button){
      var con = new Container({}, "idDiv");

      con.addChild(new Button({
         id: "example1",
         label: "I am simple button"
      });
      con.startup();
});

startup

In the end of wizard definition you can call the startup method for the widget at the top of hierarchy. After such a call at the parent widget, the widget will itself call the startup` method for each of its child elements.

placeAt

After the widget is created, you can insert it in an arbitrary place of the DOM tree using the .placeAt(domNode, insertType) method. This method can accept two arguments: an HTML DOM node or its ID and an insertion type. The below table lists the possible types of widget insertion into an HTML node:

Argument value	Insertion type
after	Widget will be inserted right after the specified DOM node.
before	Widget will be inserted right before the specified DOM node.
first	Widget will be inserted before the first child element of the specified DOM node.
last	Widget will be inserted after the last child element of the specified DOM node.
i (number)	Widget will be inserted before the i-th child element of the specified DOM node.
only	Widget will be inserted instead of all child elements of the specified DOM node.
replace	Widget will be inserted instead of the specified DOM node.

By default the second argument equals “last”. The placeAt methods also calls the startup method. So, you do not need to call both methods.

Examples

The following examples illustrate the usage of insertion types presented earlier in the table.

• after

  Was:

  <div>
     <div id="divAfter"></div>
  </div>
  

  A widget is inserted:

  wAfter.placeAt("divAfter", "after");
  

  Became:

  <div>
     <div id="divAfter"></div>
     <div id="wAfter" widgetId="wAfter">...</div>
  </div>
  

• before

  Was:

  <div>
     <div id="divBefore"></div>
  </div>
  

  A widget is inserted:

  wBefore.placeAt("divBefore", "before");
  

  Became:

  <div>
     <div id="wBefore" widgetId="wBefore">...</div>
     <div id="divBefore"></div>
  </div>
  

• first

  Was:

  <div>
     <div id="divFirst">
        <div id="child1"></div>
        <div id="child2"></div>
     </div>
  </div>
  

  A widget is inserted:

  wFirst.placeAt("divFirst", "first");
  

  Became:

  <div>
     <div id="divFirst">
        <div id="wFirst" widgetId="wFirst">...</div>
        <div id="child1"></div>
        <div id="child2"></div>
     </div>
  </div>
  

• last

  Was:

  <div>
     <div id="divLast">
        <div id="child1"></div>
        <div id="child2"></div>
     </div>
  </div>
  

  A widget is inserted:

  wLast.placeAt("divLast");
  

  Became:

  <div>
     <div id="divLast">
        <div id="child1"></div>
        <div id="child2"></div>
        <div id="wLast" widgetId="wLast">...</div>
     </div>
  </div>
  

• i (number)

  Was:

  <div>
     <div id="divNumber">
        <div id="child1"></div>
        <div id="child2"></div>
     </div>
  </div>
  

  A widget is inserted:

  wNumber.placeAt("divNumber", 1);
  

  Became:

  <div>
     <div id="divNumber">
        <div id="child1"></div>
        <div id="wNumber" widgetId="wNumber">...</div>
        <div id="child2"></div>
     </div>
  </div>
  

• only

  Was:

  <div>
     <div id="divOnly">
        <div id="child1"></div>
        <div id="child2"></div>
     </div>
  </div>
  

  A widget is inserted:

  wOnly.placeAt("divOnly", "only");
  

  Became:

  <div>
     <div id="divOnly">
        <div id="wOnly" widgetId="wOnly">...</div>
     </div>
  </div>
  

• replace

  Was:

  <div>
     <div id="divReplace">
        <div id="child1"></div>
        <div id="child2"></div>
     </div>
  </div>
  

  A widget is inserted:

  wReplace.placeAt("divReplace", "replace");
  

  Became:

  <div>
     <div id="wReplace" widgetId="wReplace">...</div>
  </div>
  

← Widget Loader

Declarative Method →