Widget Categories

For your convenience, all widgets exposed by APS JS SDK are split into categories as presented by this document.

Inputs

Input category allows a user to enter values of objects in various ways. It consists of the following widgets:

• aps/CheckBox

• aps/ComboBox

• aps/DateTextBox

• aps/MultiSelect

• aps/Password

• aps/RadioButton

• aps/Select

• aps/Slider

• aps/Spinner

• aps/TextArea

• aps/TextBox

• aps/Switch

Common Properties

There are some general properties and methods used by all or by most of the widgets of this category.

PROPERTY	TYPE	DEFAULT	User Panel	Description
autoSize	Boolean	true	CP	Used only in widgets that have the input text field and this directly affects the size property
size	Integer	10	CP	Used only in widgets that have the input text field and this defines the width of this field
label	String	“”	CP, UX1	Widget label: - In the CP, it is displayed only if an aps/FieldSet is the parent - In the UX1, it is displayed above the widget regardless of inclusion into an aps/FieldSet
description	String	“”	CP, UX1	Widget description placed under the widget content
hint	String	“”	CP, UX1	Additional help placed under the widget content or under the description if it is used
placeHolder	String	“”	CP, UX1	In an input text field, it is a grayed out text used to display a sample value. For a button, it is a pop-up tooltip.

Size and Autosize

The autoSize and size properties are used in CP and only in those widgets that have the input field to enter a text. By default, the autoSize property is set to true, and a CSS class with a certain width is assigned to the widget based on the value of the size property:

size <= 7	f-small-size (40px)
7 < size <= 33	f-middle-size (215px)
size > 33	f-big-size (240px)

If you switch the autoSize property to false, the input field width is defined by the browser.

Validation

Input widgets usually have their own custom validation methods as explained in the following sections. In some of widgets (TextBox, TextArea, and ComboBox), it is also possible to define an external or custom validation method. The method is linked with a widget through the extraValidator property. Currently, there are two options for this property:

• To validate the mail address format, use the isEmailAddress validator in the aps/validate/web module.

• Assign a custom method, to use your own validation algorithm.

If you need to define your own error message displayed in case the extra validator returns false, redefine the getCustomErrorMessage method to return the needed message.

Both options are demonstrated in the following example:

RUN DEMO

require([
    "dojo/_base/declare",
    "aps/_View",
    "aps/load",
    "aps/validate/web",
    "aps/ready!"
], function(declare, _View, load, web) {

    var namePattern1 = /^\d/,
        namePattern2 = /_/,
        flag;
    load(["aps/PageContainer", [
        ["aps/Container", [

            ["aps/TextBox", {
                id: "name",
                label: "Your Name",
                value: "",
                required: true,
                missingMessage: "The field is required",
                gridSize: "md-6",
                pattern: ".*-123",
                invalidMessage: "Ensure the name is not started with a digit and append `-123` to the name",
                extraValidator: function(val) {
                    // Data processing, e.g.:
                    flag = namePattern2.test(val);
                    if (namePattern1.test(val) || flag) {
                        return false;
                    }
                    return true;
                },
                getCustomErrorMessage: function(){
                    if(flag)
                        return "Underscore is not allowed in a name";
                }
            }],

            ["aps/TextBox", {
                id: "getmailaddress",
                label: "Your Mail Address",
                value: "test@aps",
                gridSize: "md-6",
                extraValidator: web.isEmailAddress
            }]

        ]]
    ]]);
});

When testing the validation process, pay attention to the following validation order.

1. If a value is required but is actually empty, the error message assigned to the missingMessage property is displayed.

2. If a value does not match the pattern, the error message assigned to the invalidMessage property is displayed.

3. If the extra validation function returns false, the error message is determined as follows:

   • If the getCustomErrorMessage method returns a message, this will be displayed.

   • Otherwise, the error message assigned to the invalidMessage property is displayed.

Buttons

This input category allows a user to activate a certain process. It consists of the following widgets:

• aps/Button: a general button that you can insert in any place of a view screen.

• aps/DropDownButton: a drop-down list of buttons providing a list of actions over an object usually in a aps/Tile or in a aps/Grid.

• aps/Toolbar: buttons in a grid toolbar providing operations over objects selected in the grid.

Besides those buttons that an application can use in its views, there are also Navigation or transition controls explained in general and particularly for UX1.

Containers

A widget from the container category usually embeds a number of other widgets including other containers. It consists of the following widgets:

• aps/ActiveList

• aps/Container

• aps/FieldSet

• aps/ListSwitcher

• aps/PageContainer

• aps/Panel

• aps/Tiles

• aps/Toolbar

• aps/ToolsList

• aps/WidgetList

Common Properties

There are common properties and methods used by containers as presented here.

PROPERTY	TYPE	DEFAULT	User Panel	DESCRIPTION
label	String	empty	CP, UX1	Text displayed as a label when the widget is inside an aps/FieldSet widget
title	String	empty	CP, UX1	Text displayed in the header of the container
description	String	empty	CP, UX1	Text displayed under the header of the container and over the content of the container
hint	String	empty	CP, UX1	Supplementary information
collapsed	Boolean	false	CP, UX1	Hides the container contents, leaving visible only its title and label visible
collapsible	Boolean	false	CP, UX1	Provides an icon that allows a user to collapse the container.

The following example illustrates some of the general container properties.

RUN DEMO

require([
    "aps/load",
    "aps/ready!"
], function(load) {
    load(["aps/Container", {
            title: "Parent Container Title",
            label: "Parent Container Label",
            description: "This is the parent Container description",
            hint: "Hint about the parent Container"
        },
        [
            ["aps/FieldSet", {
                    title: "FieldSet Title",
                    label: "FieldSet Label",
                    description: "This is the Field Set description"
                },
                [
                    ["aps/Container", {
                        title: "Container1 Title",
                        label: "Container1 Label",
                        description: "This is the Container1 description",
                        hint: "Hint about the Container1",
                        collapsed: true
                    }],
                    ["aps/Container", {
                        title: "Container2 Title",
                        label: "Container2 Label",
                        description: "This is the Container2 description",
                        hint: "Hint about the Container2",
                        collapsible: true
                    }]
                ]
            ]
        ]
    ]);
});

Common Methods

The following methods are used to manage child widgets in a container.

METHOD	ARGUMENTS	Description
addChild	child, insertIndex	Inserts the specified child widget into the position specified by the insertIndex argument.
removeChild	child	Removes the specified child widget from the parent widget.
removeAll	-	Removes all children.
startup	-	Called after the widget and all its children have been created. Also used when the widget is declared using the widget constructor method.
layout	-	It is called after startup() to place all children on the page. Composite widgets override this method to size and position their children. The Dojo placeat method calls the startup method.
validate	-	Calls the validate method in each child to check the correctness of input data.
destroy	-	Destroys the widget and all its child objects.

addChild

The addChild(widget, insertIndex) method adds the specified widget as a child into a certain position. The optional insertIndex argument defines this position by means of the following possible values:

• “first”: insert into the first position

• “last” (default value): add to the last position

• Integer in the range started from 0: insert into the specified position

APS JS SDK provides various containers described in the following sections.

validate

The validate method is private. It is always called when a value is changed. If your view has input widgets and you use required or pattern to check the correctness of the input data, the validate method is called in each child to check the correctness of input data. If the data is correct, the method returns true, otherwise the method returns false and sets the focus on the element where the user made a mistake while inputting data.

Messages

There are two widgets in this category that function together:

• aps/MessageList

• aps/Message

The container based on the aps/MessageList module can contain a number of aps/Message widgets. This helps you create and dynamically manage notifications in a user panel.

Outputs

There are various output widgets you can use in your code to display data for users:

• aps/Gauge

• aps/Grid

• aps/Output

• aps/Pie

• aps/ProgressBar

• aps/Status

• aps/Tooltip

• aps/UsageInfo

• aps/WizardControl

Popup Dialogs

The methods of this category allow you to use a popup visual window to display certain contents and get a confirmation of an operation if necessary:

• aps/alert

• aps/confirm

• aps/changePassword

← JS Modules

List of Widgets →