For your convenience, all widgets exposed by APS JS SDK are split into categories as presented by this document.
In this document:
Input category allows a user to enter values of objects in various ways. It consists of the following widgets:
There are some general properties and methods used by all or by most of the widgets of this category.
PROPERTY |
TYPE |
DEFAULT |
Description |
|
---|---|---|---|---|
Boolean |
true |
CP |
Used only in widgets that have the input text field and this directly affects the size property |
|
Integer |
10 |
CP |
Used only in widgets that have the input text field and this defines the width of this field |
|
|
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
|
|
String |
“” |
CP, UX1 |
Widget description placed under the widget content |
|
String |
“” |
CP, UX1 |
Additional help placed under the widget content or under the description if it is used |
|
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. |
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.
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:
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.
If a value is required
but is actually empty, the error message assigned to the missingMessage
property is displayed.
If a value does not match the pattern
, the error message assigned to the invalidMessage
property is displayed.
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.
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.
A widget from the container category usually embeds a number of other widgets including other containers. It consists of the following widgets:
There are common properties and methods used by containers as presented here.
PROPERTY |
TYPE |
DEFAULT |
DESCRIPTION |
|
---|---|---|---|---|
|
String |
empty |
CP, UX1 |
Text displayed as a label when the widget is inside an aps/FieldSet widget |
|
String |
empty |
CP, UX1 |
Text displayed in the header of the container |
|
String |
empty |
CP, UX1 |
Text displayed under the header of the container and over the content of the container |
|
String |
empty |
CP, UX1 |
Supplementary information |
|
Boolean |
false |
CP, UX1 |
Hides the container contents, leaving visible only its title and label visible |
|
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.
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
}]
]
]
]
]);
});
The following methods are used to manage child widgets in a container.
METHOD |
ARGUMENTS |
Description |
---|---|---|
child, insertIndex |
Inserts the specified child widget into the position specified by the insertIndex argument. |
|
|
child |
Removes the specified child widget from the parent widget. |
|
|
Removes all children. |
|
|
Called after the widget and all its children have been created. Also used when the widget is declared using the widget constructor method. |
|
|
It is called after |
|
|
Calls the |
|
|
Destroys the widget and all its child objects. |
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.
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.
There are two widgets in this category that function together:
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.
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: