APSC Methods

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

Navigation Methods

The following are the methods that application views call to direct the user to another view, either internal or external.

METHOD	ARGUMENTS	DESCRIPTION
externalHttpRequest	{ method: <GET | POST>, action: <URL>, data: {<set of named parameters>} }	Allows an application to send an HTTP request from the parent document. Refer to the externalHttpRequest section for more details.
gotoView	view - string or object resourceId - string params - object	Navigates the user to another view specified by the view argument as explained in the gotoView section. It is also possible to send a resource ID through the resourceId argument and parameters through params.
gotoURL	directLink - string	Navigates the user to another view as specified by the directLink argument.
next	data - any	If the view is inside a wizard, it calls this method to navigate the user to the next wizard step. Optionally, it can pass some data to the wizard. Normally, the onNext handler calls this method.
prev	-	If the view is inside a wizard, it calls this method to navigate the user to the previous wizard step. Normally, the onPrev handler, if used, calls this method after performing some internal actions.
showPopup	{ viewId: <view ID>, resourceId: <resource ID>, params: <object with parameters>, modal: <isModal> }	Shows the popup view identified by the viewId argument. The usage is similar to aps.apsc.gotoView().
wizardState	wizardState - object of the same structure as aps.context.wizardState	Wizard host uses it to send updates of the wizardState object to the control panel. This influences the chain of views in the wizard.

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 changing 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	-	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 normally calls it after all other actions are done.
showLoading	-	Shows 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://doc.apsstandard.org'
                     });
                     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, particularly, opening an external view in the parent node are considered insecure as specified in the certification requirements. For example, the third line in the following code tries to reach the window.top node. This is insecure operation and thus the whole code is NOT 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 navigating 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 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>. Parameter name MUST NOT start with “__” (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.

← Data Exchange

Application Methods →