Application Packaging Standard

Last updated 18-Mar-2019

Using RQL

Resource Query Language (RQL) in declaration of navigation elements makes the UI structure more flexible.

In this document:

Scope

RQL statements operate properties of variables declared in navigation elements.

The following attributes of navigation elements can use RQL to calculate their values.

  • visible in an item, view, or view-plugin element accepts a boolean value. This hides the respective visual component or makes it visible on the screen. In the following example, the showNetworkTab property of the vpsmanagement variable defines if the control panel will show the item.

    <item id="network" label="Network" visible="vpsmanagement.showNetworkTab=eq=true()">
    
  • filter in a var element defines resources to be added to the declared variable. The following declaration of the vps variable adds a linked offer to the variable:

    <view id="server-edit" label="Edit">
         <var name="vps" type-id="http://aps-standard.org/samples/basic/vps/2.0"
              filter="select(offer)"/>
         <controls>
              <cancel/>
              <finish/>
         </controls>
    </view>
    

    This allows the server-edit view to process not only the selected VPS but also the offer linked with it.

  • A label or step-label of a navigation item, wizard host, or view can get its value dynamically. In the following example, the offer-edit view will display the name of the offer opened for editing:

    <view id="offer-edit" label="Edit Offer {offer.name}">
         <var name="offer" type-id="http://aps-standard.org/samples/offer-mgmt/offer/1.0"/>
         <controls>
              <cancel/>
              <submit/>
         </controls>
    </view>
    

Rules and Limitations

The mentioned above RQL operations are performed before a visual element is processed. The navigation mechanism can read only navigation data and is not able to change any data.

  • To specify a property of a variable, use the dot notation. For example if the vps variable has the id property, RQL may use the property as vps.id.
  • The navigation mechanism does not generate any special queries to the APS controller and operates only variables declared in navigation elements. That is why, you cannot use such RQL functions as implementing(), limit(), or sort().
  • It is not allowed to change any properties in RQL statements, that is no assignment is supported.
  • The filter property is processed by the APS controller. That is why, a filter must operate objects and their properties that the APS controller can find in its database. For example, it should not use a variable name defined in navigation metadata.
  • Access to an element of a variable collection, for example, myVar.servers[11], is not allowed.
  • In RQL statement, a string not recognized as a variable name is automatically recognized as a string or a number in dependence of its value. For example hello is processed as a string, and 123 or 3.14 is processed as a number, respectively integer or double. A string in the form of date/time, for example, 2015-09-04T00:00:00+04:00, is processed as the date type.
  • XML text must contain allowed characters as specified by W3C Recommendation, 2.2 .
  • You should escape markup elements using one of the escape constructions:
    • Entity name in the form of “&entity_name;” in accordance with W3C Recommendation, 2.4 , for example, “&amp;” represents “&”, and “&lt;” represents “<”.
    • Entity reference in the form of “&entity_reference;” in accordance with W3C Recommendation, 4.1 , for example, decimal code “&#38;” or hexadecimal code “&#x26;” represents “&”.