Navigation Variables

Declaration in Meta

A <var> element inside a <navigation> or <item> element declares a variable representing a singular resource or a collection of resources.

<var
   name="offers"
   type-id="http://aps-standard.org/samples/offer-mgmt/offer/1.0"
   required="false"
   collection="true"
/>

Attributes

The <var> element contains the following attributes:

Attribute	Type	Default	Example	Description
name	string	N/a	name = “offers”	Unique variable name that can be used in JavaScript
type-id	URI	N/a	type-id = “http://aps.test/offer-mgmt/offer/1.0”	APS type identifying a resource or a collection of resources
required	boolean	“true”	required = “false”	A view cannot be opened if a required variable is empty
collection	boolean	“false”	collection = “true”	Specifies if the variable contains a single resource or a collection of resources
filter	RQL string	N/a	filter = “select(offer)”	Allows filtering a subset of the required collection. If the select(<list of attributes>) function is used, it adds selected properties of related resources to presentation of a collection or a single resource

Navigation elements inherit the variables declared in their parents. It means, the item position in the tree defines the scope of declared variables available for the item. That is why, try to avoid conflicts when assigning the name and type to a variable.

When a variable is singular (collection="false" by default), its value is defined explicitly or implicitly, as explained in the following cases:

• Suppose, we have a list of virtual private servers (VPSes) displayed by the servers view. You clicked on the name of a VPS to start editing it in the server.edit view. If a variable is declared for the server.edit view and it refers to the APS type defining the VPS schema, the JSON object representing the selected VPS will be assigned to the variable. Here, we have the explicit assignment of the variable that the VPS editor in the view will use.
• Suppose, the same VPS editor view was called from another view by means of the gotoView() operation. In this case, for the declared variable, the APS controller will try to find resources of the specified type in the current subscription. This is an example of implicit identification of a variable. If more than one resources will be found, this is identified as a conflict, and the controller will mark the variable as unresolved. The VPS edit view can work only with one resource, but none is identified in case of a conflict.

Variables in View Context

When the control panel opens a view, the latter gets the aps.context object that brings two var-related objects:

• aps.context.vars is a named list containing all variables resolved for the current view, for example:

  vars: {
     domains: [ ],
     users: [{<user1>}, {<user2>}, {<user3>}]
  }
  

  Every object in the above list, for example {user1}, is a full JSON representation of an APS resource.

• aps.context.varsMeta is a named list that presents a range of the resources for each resolved variable, for example:

  varsMeta: {
     users: {range: "items 0-2/123"},
     domains: {range: "items */0"}
  }
  

The range value is the same as the value of the Content-Range header. It indicates the number of the resources represented by the variable (first two numbers) and the total number of the resources in the APS database (the last number).

Examples

Get Collection of Offers

Let us consider an application (APS type "http://aps-standard.org/samples/var-opt") providing VPSes to subscribers. When a customer creates a VPS basing on a selected offer, the custom view (for example, view ID is server.new-1) must present a collection of offers from the customer’s subscription.

For this effect, in APS meta, a variable must be declared in the server.new-1 view or in its parent, either in an item, or a view, or the navigation root, for example:

<var name="offers" type-id="http://aps-standard.org/samples/offer-mgmt/offer/1.0"
     collection="true" />

The declared offers variable must bring a collection of offers to the view.

When the user panel is opening the server-new-1 view, it sends a request for the navigation properties similar to this:

POST /aps/2//navigation

{  "placeholder":"http://www.aps-standard.org/ui/service",
   ...
   "viewId":"http://aps-standard.org/samples/var-opt#server-new-1"
}

If the customer has subscribed to 2 offers, Silver and Gold, the APS controller will respond as follows:

HTTP/1.1 200 OK

{
   "items":
   [
      {
         "type": "navigation",
         "id": "http://aps-standard.org/samples/var-opt#ccp",
         "label": "VPS Management",
         "children":
         [
            {
               "type": "item",
               "id": "http://aps-standard.org/samples/var-opt#servers",
               "label": "Servers",
               "children":
               [
                  {
                     "type": "view",
                     "id": "http://aps-standard.org/samples/var-opt#server-new-1",
                     "label": "New VPS",
                     "src": "/aps/2/packages/5f1fbd93-...-3c05a9dbe62f/ui/server-new-1.html",
                     "vars":
                     {
                        "offers":
                        [
                           {
                              "aps":
                              {
                                 "type": "http://aps-standard.org/samples/var-opt/offer/1.0",
                                 "id": "81ad1d31-76eb-45a9-af19-d489b72f0833",
                                 ...
                              },
                              "name": "Gold",
                              ...
                           },
                           {
                              "aps":
                              {
                                 "type": "http://aps-standard.org/samples/var-opt/offer/1.0",
                                 "id": "05f43e47-f277-43cc-b3a4-2f658f8506bd",
                                 ...
                              },
                              "name": "Silver",
                              ...
                           }
                        ]
                     },
                     ...
                     "controls":
                     [
                        {
                           "type": "cancel"
                        },
                        {
                           "type": "next"
                        }
                     ]
                  }
               ]
            }
         ]
      }
   ],
   ...
}

Processing of the variable in the server-new-1 view might be as follows:

1. Get collection from the offers variable:

   var offerList = aps.context.vars.offers;
   

2. Define the number of the offers in the APS database if needed:

   var offerCount = aps.context.varsMeta.offers.range.split("/").pop();
   

3. Arrange a data source, for example, using an APS/Memory object:

   var offerCache = new Memory({ data: offerList, idProperty: "aps.id" });
   

4. Present the collection in a selection widget by offer names:

   ["aps/Select", { store: offerCache, labelAttr: "name", value: at(model.offer.aps, "id")}]
   

Get Properties of Linked Resources

When processing a VPS in UI, you need to get some properties of the offer linked with the VPS. For this purpose, declare a vps variable and use a filter with selection of an offer link:

<var name="vps" type-id="http://aps-standard.org/samples/offer-mgmt/vps/1.0"
   filter="select(offer)"/>

When the user panel is opening the view for editing a VPS, it sends a request for the navigation properties and gets the vps variable that contains not only the full JSON presentation of the selected VPS but also the JSON presentation of the offer linked with it. This allows getting any property of the linked offer.

The following example illustrates how to get APS ID of the offer linked with the selected VPS.

1. Get the variable from the view context data:

   • In the user panel, the view context aps.context object is available by the time the view is opened:

     var vps = aps.context.vars.vps;
     

   • In UX1, the view context is available as the input parameter in the onContext method:

     onContext: function(context) {
         var vps = context.vars.vps;
         ...
     }
     

2. Continue data processing, for example:

   var offerApsId = vps.offer.aps.id;
   

Monitoring Actual State

Navigation variables, available for a view, are updated only when the platform user panel is opening the view.

Note

In cases, when somebody needs to continuously monitor resource states in a grid, the use of an APS/Store collection instead of a navigation variable is the best practice solution.

Data displayed on a screen can be out of date if the screen is not refreshed for a long time. The following function will refresh the screen with a defined period.

var timeout,
refresh = function() {
     grid.refresh();
     timeout = setTimeout(refresh, 1500);
};

Let us suppose, the grid widget declares its store element as an APS/Store object. Then, the grid.refresh() function will cause the store to update its contents from the APS controller.

In the other case, when the grid widget uses an APS/Memory object as its store, whose data is based on a navigation variable, the refresh will also cause update of the store. But since the navigation variable is not updated, the store actually will still remain the same.

← Navigation Elements

Plugging to User Panels →