APSC Methods

The user panel API of the hosting platform exposes several methods in the aps.apsc namespace that application views can call.

Status Processing

The following are the methods that application views can call to process object status.

METHOD

ARGUMENTS

DESCRIPTION

buttonState

control - enum: "cancel" or "submit"
properties - object

Allows the changing of some properties of the cancel and submit navigation buttons. The properties object is a named set of one or more properties from the following list: {label: <”string”>, visible:<boolean>, disabled:<boolean>}.

cancelProcessing

-

The user panel releases the current view or button from the waiting status. For example, a button event handler can use it to make the button available for the user.

hideLoading

-

Hides the loading status of the current view from the screen. The onContext method usually calls it after all other actions are done.

showLoading

-

Displays the loading status on the screen.

Message Processing

The following are the methods that application views call to manage messages displayed on top of the screen.

METHOD

ARGUMENTS

DESCRIPTION

displayMessage

{ "id": <string>,
"description": <text>,
"type": <enum string>,
}

Creates a new message with an assigned id and type. It displays the text specified by the description.

removeMessage

ID - string

Removes the message according to the specified ID.

removeAllMessages

-

Removes all messages from the screen.

Note

The methods can be effectively used by a hidden IFrame. For example, a wizard can print out a message on the screen where currently another IFrame is visualized (a view plugged into the wizard). The type argument defines a CSS class that will be applied to the message. The type values are the same as used in aps/Message.

Example

  1. Display two messages:

    aps.apsc.displayMessage({"id":"text-1","description":"Attention. Text of the test message 1","type":"warning"});
    aps.apsc.displayMessage({"id":"text-2","description":"Info. Text of the test message 2","type":"info"});
    
  2. Remove the first message:

    aps.apsc.removeMessage("text-1");
    
  3. Remove all messages:

    aps.apsc.removeAllMessages();
    

Details

externalHttpRequest

The method allows an application UI view to send an HTTP request from its parent DOM node. If this is a GET request to open a new page, the latter will appear in the parent DOM node, and the current view will be closed. The method accepts on its input a set of named parameters, that is, aps.apsc.externalHttpRequest({<params>}), where <params> is a named set of the following arguments:

  • method is an optional argument that specifies a verb in the HTTP request. The default value is ‘GET’ and another option is ‘POST’. For example:

    "method": "POST"
    
  • action is a URL address, for example:

    "action": "https://aps.test/action/"
    
  • data is an optional set of parameters to be sent in the body of the HTTP request. For example:

    "data": {"name": "John Smith", "view": "Gallery"}
    

This is a simple view code demonstrating the externalHttpRequest method:

define(["aps/View"],
   function(View) {
      return declare(View, {
         init: function() {
            return ["aps/Container", [
               ["aps/Button", {
                  title: "View APS SDK Documentation",
                  onClick: function() {
                     aps.apsc.externalHttpRequest({
                        'method': 'GET',
                        'action': 'https://docs.cloudblue.com/cbc/sdk/'
                     });
                     this.cancel();
                  }
               }]
            ]];
         }
      })
});

Note

externalHttpRequest is the recommended method for a custom view to redirect a user to an external system and open a new view generated by that system in the browser.

Warning

The other ways of reaching the parent DOM node in order to send an HTTP request to an external service from that node and opening an external view in the parent node are considered insecure. For example, the third line in the following code tries to reach the window.top node. This is insecure operation and therefore the none of the code is allowed:

var form = document.createElement('form');
form.setAttribute('action', 'some/url');
window.top.document.body.appendChild(form);
form.submit();

gotoView

The main navigation method is aps.apsc.gotoView(view,resourceId,params). It allows navigation directly to the specified view inside the current application. The method accepts the following arguments:

  • view can specify the destination view in one of the following ways:

    • Directly: it equals the ID of the destination view

    • Indirectly through a resource: it presents a special object with the following structure:

      {
         "viewId": "viewId",
         "resourceId": "resourceId"
      }
      

    In this case, the view, specified by the view ID, will be searched inside the package where the resource with the specified resource ID is located.

  • resourceID is an optional argument. It is the ID of a resource that will be passed into the destination view.

  • params is an optional list of parameters generally described as:

    {
        <param1_name>: <parameter value>,
        <param2_name>: <parameter value>,
        ...
    }
    

    The list of parameters is declared in metadata along with a declaration of the view, for example:

    <view id="myView1">
       <params spec="version=ge=2.1">
            <param name="myParam1" required="true" type="boolean" />
            <param name="myParam2" required="false" type="string" />
       </params>
    </view>
    

    In a <param> element, you can use the following attributes similar to those used in APS type properties:

    ATTRIBUTE

    Type

    Default

    Required

    Description

    name

    String

    undefined

    yes

    Identifies a parameter in the list of parameters sent to a view. In the above example, the parameter names are shown as <param1_name> and <param2_name>. The parameter name must not start with “__” (a double underscore).

    type

    String

    undefined

    yes

    Any JSON primitive, array, APS type ID, or APS structure.

    required

    Boolean

    false

    -

    If a parameter is required, but not passed in the gotoView call, the call will fail.

    format

    String enum: “date-time” | “date” | “time” | “uri” | “email” | “ipv4” | “ipv6” | “ip-address” | “domain-name” | “host-name” | “version” | “regex”

    undefined

    -

    Specifies the content format.

    pattern

    Regular expression

    undefined

    -

    Specifies a regular expression that the parameter value must match. If it is specified, the format attribute is ignored.

    min-length

    Non-negative integer

    undefined

    -

    Sets the minimum length threshold for the string value when the type is “string”.

    max-length

    Non-negative integer

    undefined

    -

    Sets the maximum length threshold for the string value when the type is “string”.

    min-items

    Non-negative integer

    undefined

    -

    Sets the minimum number of elements in the array when the type is “array”.

    max-items

    Non-negative integer

    undefined

    -

    Sets the minimum number of elements in the array, when the type is “array”.

    unique-items

    Boolean

    undefined

    -

    Indicates that all items in an array instance must be unique, that is, the array does not contain two identical (equal) values.

    default

    Matches the type attribute

    undefined

    -

    Specifies a default value for the property.

The destination view gets the passed parameters in the aps.context.params object.