Difference between revisions of "Dynamic Tags in QPR UI"

Latest revision as of 10:30, 11 December 2020

Tags can be used in many settings fields when designing dashboards to add dynamic behaviour to the dashboards. If a tag used in a presentation object's settings field refers to a context variable, and that variable values changes, also that setting field value changes and the presentation object updates to reflect the new settings.

Evaluating a tag means that the tag is parsed (detected) from the containing text, its intended behaviour is executed and 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.

Tags have the following syntax: <#tagname parameter1="value1" parameter2="value2" ... parameterN="valueN">

In more details:

Tag starts with <#tagname, where tagname is the name of the tag, and 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 \\.
Newline characters are not allowed in tags (if a newline character is encountered, the searched text ends)

Escaping examples:

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

A tag is assumed if a text contains <#tagname (including the space) appears in the text. If the syntax doesn't continue according to the syntax rules, an error is caused.

Available tags

Settings where tags can be used

Dynamic tags can be used in following settings:

Data Grid presentation object JSON settings field
HTML presentation object HTML code field
SVG presentation object SVG code field
Panel and any presentation object Name field
Dataset query and parameter fields
QPR Suite Web Service query and parameter fields in Gata Grid presentation object's Query tab

Difference between revisions of "Dynamic Tags in QPR UI"

Latest revision as of 10:30, 11 December 2020

Available tags

Settings where tags can be used

Navigation menu

Search

@@ Line 1: / Line 1: @@
-QPR supports tags that are defined in this page.
+''Tags'' can be used in many settings fields when designing dashboards to add dynamic behaviour to the dashboards. If a tag used in a presentation object's settings field refers to a context variable, and that variable values changes, also that setting field value changes and the presentation object updates to reflect the new settings.
-== General about dynamic tags ==
+'''Evaluating''' a tag means that the tag is parsed (detected) from the containing text, its intended behaviour is executed and 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.
-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
+Tags have the following syntax: '''<#tagname parameter1="value1" parameter2="value2" ... parameterN="valueN">'''
-# The tag is parsed (detected) from the containing text
-# Its intended behaviour is executed
-# 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.
+In more details:
+* Tag starts with '''<#tagname''', where '''tagname''' is the name of the tag, and ends with '''>''' character.
-== 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 '''\\'''.
 * Newline characters are not allowed in tags (if a newline character is encountered, the searched text ends)
-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. This means that the tag parser needs to know which tags names are available in the parsed content.
-Examples of syntaxes that cause tag parsing error:
-* <#variable name="var1"
-* <#variable name="var1"escape="json">
-* <#variable name="var1" escape=json">
-* <#variable name="var1" escape=json>
-* <#variable name="var"1" escape="json">
-Examples of syntax that doesn't cause error, because the beginning is not interpreted as a tag (assuming "variable" tags can be used in the parsed content):
-* '''<variable''' (hash character missing)
-* '''<#variables''' (no space after "variable")
 Escaping examples:
-* <#action name="drill\\down\"abc\""> (name parameter contents: drill\down"abc")
-== Settings where tags can be used ==
-Dynamic tags can be used in following settings:
-* [[Data Grid Properties|Data Grid]] presentation object '''JSON settings''' field (Variable tag and the short syntax)
-* [[SVG Properties|SVG]] presentation object '''SVG code''' field  (Action tag, Variable tag and and the short syntax)
-* [[Panel Properties|Panel]] and any presentation object '''Name''' field (Variable tag and the short syntax)
-* ProcessAnalyzer and QPR Suite web service queries in data grid presentation object's Query tab (Variable tag and the short syntax)
-== 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. Also [[QPR MobileDashboard System Variables|system context variables]] can be used.
-If the referenced context variable doesn't exist, an error is caused.
-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: \)
-** '''javascript''': Escaping suitable for JavaScript string literals (characters to escape: ", ' and \, escape charater: \)
-** '''xml''': Escaping suitable for xml text nodes (characters to escape: <, >, &, ' and ", resulting strings: & quot;, & apos;, & lt;, & gt;, & amp;)
-** '''html''': Encoding that the following JavaScript code performs: '''$('<div/>').text("textToEncode").html();'''. Html encoding is needed when a text is put in a html code and the text should not be interpreted as html.
-** '''uri''': Escaping suitable for full url's. Implements JavaScript encodeUri() function. (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURI)
-** '''uricomponent''': Escaping suitable for url address pars such as parameters. Implements JavaScript encodeUriComponent() function. (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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:
-* '''<#var1>''' is same as '''<#variable name="var1">'''
-* '''{#var1}''' is same as '''<#variable name="var1">'''
-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.
-Note on context variables that contain spaces: When using <#var1> syntax, it's not possible to refer to context variables that use spaces. Using the {#var1} syntax, spaces are possible.
-== Expression tag ==
-Expression tag is used to calculate an expression (formula) and show its result in place of the tag. It's possible to use context variables as parameters in the expressions. If the expression returns a date or numeric type of data, the data is converted into string using the browsers current locale settings. The expression is calculated again if the context variables used by the expression changes.
-QPR uses Syncfusion Calculate expression language. See all available functions here: https://help.syncfusion.com/js/calculate/supported-formulas/supported-formulas
-Parameters:
-* '''value''': Expression string to calculate.
-* '''escape''': Determines which escaping or encoding is applied to the calculation result so that the value is compatible with its context, e.g. inside string literal quotation marks. Available escapings are the same as in the Variable tag.
-Note that the expression language works a bit incorrectly as it returns '''0''' for empty strings, and also string literals are returned enclosed by quotation marks. For example, '''<#expression value="\"abc\"">''' returns '''"abc"''' which is not correct (the result should not contain quotation marks). To workaround the issue, you can use '''concatenate''' function, for example '''<#expression value="concatenate(\"abc\", \"\")">''' (strings returned by functions work correctly).
-Examples:
-* <#expression value="SQRT([A] * [A] + [B] * [B])">
-* <#expression value="LEFT(\"limit this string to 17 characters\", 17)">
-* <#expression value="UPPER(\"show me in upper case\")">
-* <#expression value="YEAR(NOW())">
-* <#expression value="EDATE(NOW(), 12)">
-== 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 supported 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">'''
-= Tags supported in future =
-== Dataset tag ==
-Dataset tag is used to convert a dataset into a JSON format to be used in a JSON configuration, for example in a chart or datagrid.
-Parameters:
-* '''identifier''': Dataset name
-* '''grouping''': When the grouping is defined, JSON is structured in a two level hierarchy described below. Following format is used: '''[Group column name in dataset];[Group attribute name in JSON];[Inner array attribute name in JSON]'''. In the hierarchy the outer level contains an object array where the objects have two attributes: the defined "Group attribute name in JSON" and "Inner array attribute name in JSON". "Group attribute name in JSON" contains the group name, and "Group attribute name in JSON" contains an object array where there is data of that single group.
-* '''[all other parameters]''': All other parameters define column mappings from the dataset to the JSON presentation. Parameter name is the column name in the formatted JSON and parameter value is column name in the dataset. If referenced column is not found, an error is returned. All unmapped columns in the dataset are mapped with same names in JSON. Empty value means that if the dataset contains the defined column, it is not mapped.
-Examples:
-* <#dataset identifier="scorecards" name="scorecardName" x="" y="revenue" color="statusColor">
-* If there is a dataset with columns A, B and C, and there is a tag '''<#dataset identifier="datasetname" D="A" B="">''', the resulting JSON contains columns D and C. Column A as mapped with the name D, column B is not mapped at all and C as mapped with the same name.
-* Grouping example:
-There is the following dataset with identifier '''MetricsQuery''' (presented here in CSV format):
-<pre>
-Country;Year;Efficiency
-India;2015;28
-India;2016;25
-India;2017;26
-Germany;2015;31
-Germany;2016;28
-Germany;2017;30
-England;2015;36
-England;2016;32
-England;2017;34
-</pre>
-With tag '''<#dataset identifier="MetricsQuery" grouping="Country;name;points" x="Year" y="Efficiency">''' the result is as follows:
 <pre>
-[
+<#action name="drill\\down\"abc\""> (name parameter contents: drill\down"abc")
-  {
-    "points": [{"x": 2015, "y": 28}, {"x": 2016, y: 25}, {"x": 2017, "y": 26}],
-    "name": "India"
-  },
-  {
-    "points": [{"x": 2015, "y": 31}, {"x": 2016, "y": 28}, {"x": 2017, "y": 30}],
-    "name": "Germany"
-  },
-  {
-    "points": [{"x": 2015, "y": 36}, {"x": 2016, "y": 32}, {"x": 2017, "y": 34}],
-    "name": "England"
-  }
-]
 </pre>
-== Translate tag ==
+A tag is assumed if a text contains '''<#tagname ''' (including the space) appears in the text. If the syntax doesn't continue according to the syntax rules, an error is caused.
-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:
+== Available tags ==
-* '''text''': Text to translate. This parameter is mandatory.
+* [[Variable Tag in QPR UI|Variable tag]]
-* '''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.
+* [[Expression Tag in QPR UI|Expression tag]]
-* '''language''': Language name to which translate the text. This parameter is optional, and if omitted, the current UI language is assumed.
+* [[Dataset Tag in QPR UI|Dataset tag]]
-Examples:
+== Settings where tags can be used ==
-* <#translate text="Renenue">
+Dynamic tags can be used in following settings:
-* <#translate text="Renenue" context="bookkeeping">
+* [[Data Grid Properties|Data Grid]] presentation object '''JSON settings''' field
-* <#translate text="Renenue" language="FI">
+* [[HTML Properties|HTML]] presentation object '''HTML code''' field
+* [[SVG Properties|SVG]] presentation object '''SVG code''' field
-= Functions supported in future =
+* [[Panel Properties|Panel]] and any presentation object '''Name''' field
-== Cell function ==
+* [[Datasets in QPR UI|Dataset]] query and parameter fields
-Cell function is used to retrieve a single cell value from a dataset. It's usually used when there is a query to retreave a single value, such as object name - in that case the returned dataset contains only one row and column.
+* QPR Suite Web Service query and parameter fields in Gata Grid presentation object's Query tab
-Parameters:
-# '''name''': Identifier of the referenced dataset. This parameter is mandatory.
-# '''columnName/columnIndex''': Referenced column name or index in the dataset. This parameter is optional, and if omitted, the first column of the dataset is referenced. If the provided parameter is string, it means column name; if it's numerical, it means column index.
-# '''rowIndex''': Referenced row number in the dataset (starting from 1). This parameter is optional and if omitted, the first row is used.
-Error is caused if the referenced dataset identifier, columnName, columnIndex or rowIndex is not found.
-Examples:
-* <#expression value="cell(\"scorecard\")">
-* <#expression value="cell(\"scorecard\", \"symbol\", 3)">
-* <#expression value="cell(\"scorecard\", 2, 3)">
-== Info function ==
-Info function is used to access different kind of user, session and context related information, that may be needed in the user interface. The function has one string value parameter with following options:
-* '''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: '''<nowiki>https://demo.qpr.com/mobiledash/</nowiki>'''.
-* '''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 active UI language. Available UI language codes: '''EN''' (English), '''FI''' (Finnish), '''AR''' (Arabic).
-* '''meaWsUrl''': QPR Suite web services url.
-* '''paWsUrl''': QPR ProcessAnalyzer web services url.
-Note. it's possible to combine the baseUrl with the urlParameters to get a full bookmark url: e.g. '''<#baseUrl>#/dashboard?<#urlParameters>'''
-Examples:
-* <#expression value="info(\"baseUrl\")">
-[[Category: QPR MobileDashboard]]
+[[Category: QPR UI]]