Dynamic Tags in QPR UI

Note: Documentation in this page mainly applies to upcoming QPR MobileDashboard versions.

General about text tags

In some UI element settings it is possible to use some of the below defined tags. Tag evaluation means that

1. the tag is parsed from the text
2. it's behaviour is executed
3. the tag text is replaced by what the tag is supposed to provide

The tags are always evaluated before the setting value is used by the UI element. In the tag evaluation phase the setting value is treated text only, although it might be JSON, SVG or CSS.

Tag syntax

Tag syntax has following form: <#tagname parameter1="value1" parameter2="value2" ... parameterN="valueN">

Tags have following syntax:

• Tag start with <#tagname , where tagname is the name of the tag (note the space after tag name).
• Tag ends with >.
• Tag contains one to many parameters as key-value pairs (different parameters are separated by space).
• Parameter name is followed by = which is followed by parameter value in double-quotes (").
• If parameter value contains double-quotes they are escaped with \ character, example \".
• \ character is escaped with \\.

Tag is assumed if tag start <#tagname is appears in the text. If the syntax doesn't continue according to the syntax rules an error is caused.

Examples of syntax that causes error:

• <#variable name="var1"
• <#variable name="var1"escaping="json">
• <#variable name="var1" escaping=json">
• <#variable name="var1" escaping=json>
• <#variable name="var"1" escaping="json">

Examples of syntax that doesn't cause error, because they are not interpreted as tag at all:

• <variable
• <#variables
• <#variableparameter1=value1>

Escapings example: string in parameters are escaped with JSON escaping

• Example: <#action name="drill\\down\"abc\""> (name parameter contents: drill\down"abc")

Variable tag

Variable tag references to a context variable, i.e. when the tag is evaluated the tag is replaced by context variable value. The value is taken from the effective context of that UI element, where the tag resides. When the referenced context variable value changes, the UI element, which setting contain the variable tag, is also refreshed. UI element decides the logic how the UI element is refreshed. Variable tag is not able change the context variable value.

Variable tag contains following parameters:

• name: Name of the referenced context variable. This parameter is mandatory.
• escape: Determines how the context variable value is manipulated before the value is replaced to the text. This parameter is used so that the value fits in place, e.g. inside string literal quotation marks.
  • none: No escaping (default value)
  • json: Escaping suitable for JSON string literals (characters to escape: " and \)
  • javascript: Escaping suitable for JavaScript string literals (characters to escape: "', '' and \)
  • xml: Escaping suitable for xml text nodes (characters to escape: <', >, &, '' and ")
• jsonpath: Contains a JSON path expression (more information: https://github.com/json-path/JsonPath). Context variable value is expected to contain a JSON value and instead of replacing the whole JSON value, the JSON path expression is evaluated for the JSON value and the result is replaced.

Examples:

• <#variable name="variable1" escape="json">
• <#variable name="somejsondata" jsonpath="$.store.book[0].title">

Action tag

Action tag references to a QPR MobileDashboard action. It can be used in a javascript code, because the replaced value is a call to a javascrip function. All context variable in the effective context are automatically passed to the action.

Parameters:

• name: Referenced action identifier. This parameter is mandatory.
• [action parameters] as key-value pairs of assigned action parameters (will be used in future)

Example 1: Tag <#action name="DrilldownToDetails"> can be embedded into SVG code: <svg onclick="<#action name="DrilldownToDetails">">. Example 2: Action with parameter assignments: <#action name="drilldownToCities" param1="value1" param2="value2">

Info tag (supported in future)

Info tag is used to access different kinds of user, session and context related information, that may be in the functioning of the dashboards. The information can only be read and not set.

Parameter:

• name: Information/setting/property name (mandatory). Following are supported: enticeSessionId, meaSessionId, paSessionId, baseUrl, bookmarkUrl, username, uiLanguage

Example:

• <#info name="paSessionId">

Datasetcell tag (supported in future)

Datasetcell tag is used retrieves a single cell value from a UI element dataset.

Parameters:

• name: Identifier of the referenced dataset. This parameter is mandatory.
• columnName: Referenced column name in the dataset. This parameter is optional, and by default the first column is used. This is alternative to columnIndex.
• columnIndex: Referenced column index in the dataset. This parameter is optional, and also alternative to columnName.
• rowIndex: Referenced row number name in the dataset. This parameter is optional and by default the first data row is used.

Error is caused if the referenced dataset identifier, columnName, columnIndex or rowIndex is not found.

Examples:

• <#datasetcell name="scorecards">
• <#datasetcell name="scorecards" columnName="symbol" rowIndex="3">

Translate tag (supported in future)

Translate tag is used to get a translated value for a string from a translation table (separate feature). This tag is used to build multilingual dashboards. If translation text is not found from the translations table, the original text is returned.

Parameters:

• text: Text to translate. This parameter is mandatory.
• context: Enables to have different translations for same text.
• language:

Examples:

• <#translate text="Renenue">
• <#translate text="Renenue" context="bookkeeping">
• <#translate text="Renenue" language="FI">

Context variable short syntax

There is also the following short syntax for the Variable tag:

• <#variable1> is same as <#variable name="variable1">.
• {#variable1} is same as <#variable name="variable1">.
• {|variable1} is same as <#variable name="variable1" escape="json">.

The last two are for legacy features support.

The short syntax differs from other tags in a way that the short syntax doesn't have parameters (other tags always have at least one parameter). The short syntax is identified by tag parser only if it's properly written, i.e. there are no error messages for wrongly defined syntax.