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 | User Panel | Description |
---|---|---|---|---|
autoSize | Boolean | true | CP | Used only in widgets that have the input text field and directly affects the size property |
size | Integer | 10 | CP | Used only in widgets that have the input text field and defines the width of this field |
label |
String | “” | CP, UX1 | Widget label:
- In CP, it is displayed only if an aps/FieldSet is the parent
- In 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 description if it is used |
placeHolder |
String | “” | CP, UX1 | In an input text field, it is a grayed out text used to show a sample value. For a button, it is a popup 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 own custom validation methods as explained in the next sections.
In some of widgets (TextBox, TextArea, and ComboBox), it is also possible to define an external
or custom validate method. The method is linked with a widget through the extraValidator
property.
Currently, there are two options for this property:
isEmailAddress
validator in the aps/validate/web
module.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.
required
but is actually empty, the error message assigned to the missingMessage
property is displayed.pattern
, the error message assigned to the invalidMessage
property is displayed.getCustomErrorMessage
method returns a message, this will be displayed.invalidMessage
property is displayed.Input category allows a user to activate a certain process. It consists of the following widgets:
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 normally 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 | User Panel | DESCRIPTION |
---|---|---|---|---|
label |
String | empty | CP, UX1 | Text shown as a label when the widget is inside an aps/FieldSet widget |
title |
String | empty | CP, UX1 | Text shown in the header of the container |
description |
String | empty | CP, UX1 | Text shown 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 |
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.
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 |
---|---|---|
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. |
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:
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 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 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 manage dynamically notifications in a control panel.
The methods of this category allow you to use a popup visual window to show a certain contents and get a confirmation of an operation if necessary: