In this document:
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"
/>
The <var> element contains the following attributes:
Attribute |
Type |
Default |
Example |
Description |
---|---|---|---|---|
name |
string |
N/a |
name = “offers” |
A unique variable name that can be used in JavaScript |
type-id |
URI |
N/a |
type-id = |
An 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 whether the variable contains a single resource or a collection of resources |
filter |
N/a |
filter = “select(offer)” |
Allows for filtering of a subset of the required collection. If the select(<list of attributes>) function is used, it adds selected properties of related resources to the presentation of a collection or a single resource |
Navigation elements inherit the variables declared in their parents. This means, the item position in the tree defines
the scope of declared variables available for the item. For this reason, 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:
There is a list of virtual private servers (VPSes) displayed by the servers
view.
You clicked 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.
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 is found, this is identified as a conflict, and the APS controller will mark
the variable as unresolved. The VPS edit view can work only with one resource, but none is identified if there is
a conflict.
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 in accordance with
pagination rules. 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).
Let us consider an application (APS type "http://aps-standard.org/samples/var-opt"
) providing VPSes to subscribers.
When a customer creates a VPS based 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, 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:
Get collection from the offers
variable:
var offerList = aps.context.vars.offers;
Define the number of the offers in the APS database if needed:
var offerCount = aps.context.varsMeta.offers.range.split("/").pop();
Arrange a data source, for example, using an APS/Memory
object:
var offerCache = new Memory({ data: offerList, idProperty: "aps.id" });
Present the collection in a selection widget by offer names:
["aps/Select", { store: offerCache, labelAttr: "name", value: at(model.offer.aps, "id")}]
When processing a VPS in the UI, you need to get specific 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 opens 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 representation of the selected VPS, but also
the JSON representation of the offer
linked with it. This allows for it to get any property of the linked offer.
The following example illustrates how to get the APS ID of the offer linked with the selected VPS.
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;
...
}
Continue data processing, for example:
var offerApsId = vps.offer.aps.id;
Navigation variables available for a view are updated only when the platform user panel is opening the view.
Note
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);
};
If the grid widget declares its store element as an APS/Store
object, the grid.refresh()
function
will cause the store to update its contents from the APS controller.
In another case, when the grid widget uses an APS/Memory
object (whose data is based on a navigation
variable) as its store, the refresh will also cause update of the store. But because the navigation variable is not updated,
the store actually will still remain the same.