Previous topic

Model

Next topic

Declarations

DOCUMENTATION
Last updated 20-Dec-2016

Widgets

Purpose

The APS JS SDK provides a set of modules for creating and controlling various visual interface elements of web applications. We mean such elements as an interactive button, slider, toolbar, progress bar, etc.

Documentation Overview

This document contains detailed description of the most significant and often used properties of APS JS SDK widgets. Before you start studying a widget, be aware of the following general sections of the document:

  • The Declarations section explains in details various ways to define and load widgets.
  • The List of Widgets section contains a table with all widgets in alphabetical order.
  • The Widget Hierarchy section illustrates the nesting rules for widgets.
  • The Base Properties and Methods document describes the properties and methods that are common for all widgets.

In addition to this document, the following places can be handy in your design and development activity:

  • JS Modules is a reference guide providing the complete list of all properties and methods of the widgets and models with proper syntax and short explanation.
  • If the description of a widget in this document does not have a link to demo examples, please take a look at the common demo example .

Layout

Before you start designing a custom view for a control panel using APS widgets as building elements, get familiar with the following rules and layout samples.

Warning

In this section, you will find the recommended and thoroughly tested solutions. In a case, your solution includes a widget hierarchy different from the recommended, the view on a screen may differ from what you expected to see, for example, you can encounter incorrect alignment or miss a text.

Top Level

The system control panel (CP) loads an application UI code into an IFrame differently depending on the CP version:

  • In PCP/CCP v1, each application view defines its own root module based on aps/PageContainer (hereafter the “aps/” prefix is omitted for brevity).
  • In CCP v2, each application has the bootstrapApplhtml file that loads the UI root container based on PageContainer. All views of the application, except for pop-ups, load their widgets into that container, but only one of the views is active at a moment.
../../_images/pageContainer.png

As presented in the above diagram, an application builds the following UI components:

  • The navigation section in the APP-META.xml file defines the header and footer UI components displayed beyond the PageContainer:

    • The view label on the top, for example “New VPS”

    • The view navigation buttons on the bottom

      Note

      The view source code defines event handlers for those buttons.

  • The PageContainer always has a container based on the MessageList module for displaying application messages. A view source code (JavaScript) defines dynamically the messages based on Message to print within the MessageList.

  • Inside PageContainer, the view source code defines widgets to display in the main part of the screen.

Top Level Containers

Directly inside the UI root PageContainer, you can use the containers presented in the following diagram.

../../_images/top-containers.png

Warning

Do not add or delete the MessageList container since it must be always inside PageContainer.

Widget Hierarchy

The following table illustrates the allowed hierarchy of containers with plain widgets on the lowest levels and allowed usage of the common properties (gridSize, title, and label).

HIERARCHY PROPERTIES EXAMPLES
MessageList ( ? )
Message ( ? )
—— Button ( ? )
 
ListSwitcher ( ? )
Grid ( ? )
—— Toolbar ( ? )
——— Button ( ? )
—— columns ( ? ) [renderCell]:
——— Output ( ? )
——— Status ( ? )
——— Gauge ( ? )
——— TextBox ( ? )
——— Password ( ? )
——— Spinner ( ? )
——— DateTextBox ( ? )
——— DropDownButton ( ? )
——— Switch ( ? )
Tiles ( ? )
—— Toolbar ( ? )
——— Button ( ? )
—— Tile ( ? )
——— Toolbar ( ? )
———— Button ( ? )
——— FieldSet ( ? )
———— Gauge ( ? )
———— Output ( ? )
———— Status ( ? )
———— ToolTip ( ? )
———— Pie ( ? )
———— UsageInfo ( ? )
———— Switch ( ? )
———— Container ( ? )
————— Gauge ( ? )
————— Output ( ? )
————— Status ( ? )
————— ToolTip ( ? )
————— Pie ( ? )
————— UsageInfo ( ? )
————— Switch ( ? )
———— UsageInfo ( ? )
—— PieTile ( ? )

















gridSize


gridSize title
gridSize label
gridSize label
gridSize label

gridSize label
gridSize label
gridSize label
gridSize label
gridSize



gridSize
gridSize
gridSize


WidgetList ( ? )
Tiles ( ? )
—— Tile ( ? )
——— Toolbar ( ? )
———— Button ( ? )
——— FieldSet ( ? )
———— Gauge ( ? )
———— Output ( ? )
———— Status ( ? )
———— ToolTip ( ? )
———— Pie ( ? )
———— UsageInfo ( ? )
———— Switch ( ? )
———— Container ( ? )
————— Gauge ( ? )
————— Output ( ? )
————— Status ( ? )
————— ToolTip ( ? )
————— Pie ( ? )
————— UsageInfo ( ? )
————— Switch ( ? )
———— UsageInfo ( ? )
—— PieTile ( ? )
Grid ( ? )
—— Toolbar ( ? )
——— Button ( ? )
—— columns ( ? ) [renderCell]:
——— Output ( ? )
——— Status ( ? )
——— Gauge ( ? )
——— TextBox ( ? )
——— Password ( ? )
——— Spinner ( ? )
——— DateTextBox ( ? )
——— DropDownButton ( ? )
——— Switch ( ? )
Panel ( ? )
—— Toolbar ( ? )
——— Button ( ? )
—— FieldSet ( ? )
——— Gauge ( ? )
——— Output ( ? )
——— Status ( ? )
——— ToolTip ( ? )
——— Pie ( ? )
——— UsageInfo ( ? )
——— Switch ( ? )
——— Container ( ? )
———— Gauge ( ? )
———— Output ( ? )
———— Status ( ? )
———— ToolTip ( ? )
———— Pie ( ? )
———— UsageInfo ( ? )
———— Switch ( ? )


gridSize


gridSize title
gridSize label
gridSize label
gridSize label

gridSize label
gridSize label
gridSize label
gridSize label
gridSize



gridSize
gridSize
gridSize


















gridSize title
gridSize label
gridSize label
gridSize label

gridSize label
gridSize label
gridSize label
gridSize label
gridSize



gridSize
gridSize
gridSize
Toolbar ( ? )
Button ( ? )

Grid ( ? )
Toolbar ( ? )
—— Button ( ? )
— columns ( ? ) [renderCell]:
—— Output ( ? )
—— Status ( ? )
—— Gauge ( ? )
—— TextBox ( ? )
—— Password ( ? )
—— Spinner ( ? )
—— DateTextBox ( ? )
—— DropDownButton ( ? )
—— Switch ( ? )

Tiles ( ? )
Tile ( ? )
—— Toolbar ( ? )
——— Button ( ? )
—— FieldSet ( ? )
——— Gauge ( ? )
——— Output ( ? )
——— Status ( ? )
——— ToolTip ( ? )
——— Pie ( ? )
——— UsageInfo ( ? )
——— Switch ( ? )
——— Container ( ? )
———— Gauge ( ? )
———— Output ( ? )
———— Status ( ? )
———— ToolTip ( ? )
———— Pie ( ? )
———— UsageInfo ( ? )
———— Switch ( ? )
—— UsageInfo ( ? )
PieTile ( ? )

gridSize


gridSize title
gridSize label
gridSize label
gridSize label

gridSize label
gridSize label
gridSize label
gridSize label
gridSize



gridSize
gridSize
gridSize
Container ( ? )
Output ( ? )

Panel ( ? )
FieldSet ( ? )
—— Gauge ( ? )
—— Output ( ? )
—— TextBox ( ? )
—— Password ( ? )
—— DateTextBox ( ? )
—— Spinner ( ? )
—— ComboBox ( ? )
—— Select ( ? )
—— CheckBox ( ? )
—— RadioButton ( ? )
—— Status ( ? )
—— ToolTip ( ? )
—— TextArea ( ? )
—— MultiSelect ( ? )
—— Pie ( ? )
—— UsageInfo ( ? )
—— Button ( ? )
—— Switch ( ? )
—— Container ( ? )
——— Gauge ( ? )
——— Output ( ? )
——— TextBox ( ? )
——— Password ( ? )
——— DateTextBox ( ? )
——— Spinner ( ? )
——— ComboBox ( ? )
——— Select ( ? )
——— CheckBox ( ? )
——— RadioButton ( ? )
——— Status ( ? )
——— ToolTip ( ? )
——— Pie ( ? )
——— UsageInfo ( ? )
——— Switch ( ? )
Container ( ? )
—— Gauge ( ? )
—— Output ( ? )
—— Status ( ? )
—— ToolTip ( ? )
—— Pie ( ? )
—— UsageInfo ( ? )
—— Switch ( ? )
Grid ( ? )
—— Toolbar ( ? )
——— Button ( ? )
—— columns ( ? ) [renderCell]:
——— Output ( ? )
——— Status ( ? )
——— Gauge ( ? )
——— TextBox ( ? )
——— Password ( ? )
——— Spinner ( ? )
——— DateTextBox ( ? )
——— DropDownButton ( ? )
——— Switch ( ? )

gridSize title
gridSize label
gridSize label
gridSize label
gridSize label
gridSize label
gridSize label
gridSize label
gridSize label
gridSize label
gridSize label
gridSize label

gridSize label
gridSize label
gridSize label
gridSize label
gridSize
gridSize label
gridSize label
gridSize

gridSize
gridSize
gridSize
gridSize
gridSize
gridSize




gridSize
gridSize
gridSize
gridSize label
gridSize



gridSize
gridSize
gridSize

Widget Definition

In your application, you can define and load a widget using one of the ways:

Regardless of a selected declaration way, all widgets must be located within the root container aps/PageContainer in accordance with the following rules:

  • Each widget is implemented by its own module in the aps namespace.
  • In an HTML page, the main widget aps/PageContainer layouts the page, i.e. defines messages, screen captions, etc.
  • Each widget can be bound with a model using the watch and/or dojox/mvc/at method.
../../_images/view-api.png

To verify which control panel version is currently used, use the has(aps-bs) method (‘aps-bs’ stands for ‘APS bootstrap’). It returns true only if CCP v2 (NextCP) is used. The following example illustrates how to verify if CCP v2 is turned on:

if(has('aps-bs'))
   new Tiles({ ... });  // If CCP v2, then use aps/Tiles
Model