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 textual settings it is possible to use some of the below defined tags to achieve more dynamic behaviour of dashboards.

Evaluating a tag means that

1. the tag is parsed from the containing text
2. it's intended behaviour is executed
3. the tag definition is replaced by the tag's return value

Tags in textual settings are always evaluated before the setting value is used by the UI element. During the tag evaluation the setting value is treated as text only, although it might be JSON, SVG or CSS.

Tag definition syntax

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

In more details, tags have the following syntax:

• Tag starts with <#tagname, where tagname is the name of the tag. There is always a space after the tagName.
• Tag ends with > character.
• Tag contains one or many parameters as name-value pairs (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 (including the space) appears in the text. If the syntax doesn't continue according to the syntax rules, an error is caused.

Examples of syntaxes that cause tag parsing 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 tags:

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

Escaping examples:

• <#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 the 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. 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 which escaping or encoding is added to the context variable value when the value is used. This parameter is needed, so that the value is compatible with its context, e.g. inside string literal quotation marks. Following values can be used:
  • none: No escaping (default value)
  • json: Escaping suitable for JSON string literals (characters to escape: " and \, escape charater: \)
  • js: Escaping suitable for JavaScript string literals (characters to escape: ", ' and \, escape charater: \)
  • xml: Escaping suitable for xml text nodes (characters to escape: <, >, &, ' and ")
  • html:
  • uri: encodeuri()
  • uricomponent: encodeuricomponent()
• 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. (will be used in future)

Examples:

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

Short syntax for Variable tag

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 short syntax differs from normal tags in a way that the short syntax doesn't contain parameters, whereas normal tags always have at least one parameter. The short syntax is identified by the tag parser only if it's properly written, i.e. there are no error messages for incorrectly defined short syntax.

Action tag

Action tag references to a QPR MobileDashboard action. The tag can be used in a javascript code, because the replaced value is a call to a QPR MobileDashboard's internal javascript function which triggers the action. All context variables in the effective context are automatically passed to the triggered action.

Parameters:

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

An error is caused, if the referenced action is not found.

Examples:

• Tag <#action name="DrilldownToDetails"> can be embedded into SVG code as follows: <svg onclick="<#action name="DrilldownToDetails">">
• Action with parameter assignments: <#action name="drilldownToCities" param1="value1" param2="value2">

Info tag (supported in future)

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

Parameters (only one in this case):

• name: Information/setting/property name (mandatory). Following names are supported:
  • enticeSessionId: QPR MobileDashboard session id.
  • meaSessionId: QPR Suite session id (empty if there is no active session to QPR Suite).
  • paSessionId: QPR ProcessAnalyzer session id (empty if there is no active session to QPR ProcessAnalyzer).
  • baseUrl: Beginning part of the url of the currently opened QPR MobileDashboard view (url part until the hash sign). Example: https://demo.qpr.com/mobiledash/.
  • urlParameters: Parameters of the currently opened QPR MobileDashboard url, i.e. the session context variables. Example: sys:dashboard=1234&var1=value1&val2=value2.
  • username: User name of the currently logged in user.
  • uiLanguage: Language code of the currently used UI language. Available UI language codes: EN (English), FI (Finnish), AR (Arabic).

Note. it's possible to combine the baseUrl with the urlParameters to get a full bookmark url: e.g. <#baseUrl>#/dashboard?<#urlParameters> Examples:

• <#info name="paSessionId">

Datasetcell tag (supported in future)

Datasetcell tag is used to retrieve a single cell value from a dataset.

Parameters:

• name: Identifier of the referenced dataset. This parameter is mandatory.
• columnName: Referenced column name in the dataset. This parameter is optional, and if omitted, it's the first column of the dataset. This parameter is alternative to columnIndex.
• columnIndex: Referenced column index in the dataset (starting from number 1). This parameter is optional, and also alternative to columnName.
• rowIndex: Referenced row number name in the dataset (starting from number 1). This parameter is optional and if omitted, 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">
• <#datasetcell name="scorecards" columnIndex="2" rowIndex="3">

Translate tag (supported in future)

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

Parameters:

• text: Text to translate. This parameter is mandatory.
• context: Defined in which context the translatable text appears. This enables to have different translations for same translatable text. If omitted, empty context is assumed.
• language: Language name to which translate the text. This parameter is optional, and if omitted, the current UI language is assumed.

Examples:

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