QPR Web Views
Introduction to QPR Web Views
QPR Web Views is a technology for QPR Suite to generate web pages (html pages) displaying content from a QPR system. QPR Web Views works as an IIS web application, and data is fetched from QPR using QPR Web Service interface. The web views are based on file templates containing html, css and javascript. QPR Web Views works like QPR Web Application Server (WAS), but QPR Web Views tags are QPR Web Service based and more generic purpose.
QPR Web Views contains following main features:
- Web views are generated as they are requested, so the web views always contain the latest data.
- Web views can have parameters affecting web view’s contents.
- QPR Web Views contains an embedded formula calculation engine. All tags may be defined using expressions which values are calculated as the views are generated.
- Web views may get their content from other templates, and templates can also be called recursively (templates calling themselves). Templates makes it possible to assemble views from smaller parts.
QPR Web Views is based on the following concepts:
- Web views are based on templates, which are normal text files which contain html, css and javascript. When a view is generated, a template is taken as a basis, and in processing, content from QPR system is added to the template, forming the final web page.
- Templates contain tags, which instruct how the content is added to the page and how dynamic parts of the view are built.
- Tags contain attributes, which offer additional information of the tag.
- QPR Web Service is used through its methods. Methods called by QPR Web Views directly are GetAttributeAsString and QueryObjects. Also GetPortalUrl, GetGraphAsStream and GetBinaryDataAsStream can be utilized but they are called by the result web page from user browser. All QPR Web Service methods are documented under http://kb.qpr.com/qpr2017-1/index.html?functions.htm.
- Loop is a list of QPR system objects (elements) returned by QPR Web Service’s QueryObjects method. In a loop a template is called for every looped object.
QPR Web Views views can be embedded as part of QPR Portal or called from External Reports Menu (accelerator) dropdown list. It’s able to automatically pass parameters, such as model or selected object to the report.
Web views are accessed using a url, which determines the template to be run (parameter tpl), and the url also passes all needed parameters to the template. The url depends on the server computer name and the path where QPR Web Views is installed in IIS. Note that parameter names are case sensitive.
An example url: http://SERVERNAME/QPRWebServicesExtensions/DynamicWebViews.ashx?tpl=viewname¶meter1=param1value¶meter2=param2value
Parameters
Following table contains QPR Web Views’s parameters, which are configured in the web.config file of QPR Web Services Extensions
| Parameter Name | Description |
|---|---|
| dwvtemplatesphysicalpath | Folder in the file system where template files are located. Also this folder needs to be created. |
| templatecaching | Determines whether template files caching is enabled (true) or disabled (false). Template caching means that templates are read from file system to server memory when the IIS web application starts. When template caching is enabled, pages are processed faster and disk load as reduces. Template caching should be enabled for production environments.
Template caching is usually be disabled for development work, so that changes in templates can be seen immediately in result pages. When template caching is disabled, all templates are read into memory every time, when a page is requested. |
| qprwebapplicationname | Name of the QPR web application in IIS. In the default installation for QPR 2017, it is QPR2017-1. This parameter is not mandatory, but it should be defined, as it can be used by html content to reference QPR resources published in IIS (such as images and css files). |
Working with Templates
QPR Web Views is based on text templates files. When a web view is called, a template is taken as a basis, and all tags in the template are processed. Templates are stored in the server disk. Template files have extension tpl. The result content fetched using http have in http response header Content-Type: text/html; charset=utf-8.
Templates may be organized in folders. Folders inside folders are also supported. Template root location is determined by configuration setting templatephysicalpath.
There are two ways to reference templates:
- absolute: Absolute paths start with / and they contain the full path to the template starting from the templates root. Example: /folderName1/folderName2/templateName.
- relative: Relative paths don’t start with /, and they reference to a template in relation to the template where the reference is made. Example: to reference a template in the same folder use syntaxt templateName.
When a web view processing fails, an html page showing an error message is displayed. The error message a likely to reveal, in which template and tag the error occurred.
Template Tags
Tags are used to add content to the web view. Syntax for defining tags is following:
<#tagname attribute1="attribute1 value" attribute2="attribute2 value" attribute3="attribute3 value">
If an attribute value is calculated using an expression (formula), two equals signs are used instead of one, e.g.
<#tagname attribute1=="1+1" attribute2="1+1"> (attribute1 value is integer 2, attribute2 value is string "1+1").
In the following sub chapters optional tag attributes are marked with "(optional)". Other tags are mandatory – if any of them is missing, an error is caused. In addition, for some of the mandatory attributes the value of the attribute must not be empty (i.e. attributeName="" is not allowed). If the attribute value comes from an expression, note that the expression may evaluate as empty (thus causing an error in non-empty mandatory attribute).
When processing a tag, attribute expressions are calculated from left to right. All template parameters, template variables and already calculated attribute values are available as expression arguments when later attribute expressions are calculated. An argument is kind of an input variable that can be used in an expression with syntax [argumentName]. E.g.
<#expression attribute1="3" value=="[attribute1] + 2"> (result is 5)
Tag specific arguments have a priority over template parameters and template variables, when there are same names used.
Attribute names should only contain characters a-z, 0-9 and _.
Values for all boolean valued tags (such as visible) may be defined as "true" or "false" or as a boolean valued expression, e.g. visible=="[variable1]=1" (the result of the equality comparison is of type boolean). Tag visibility is processed in the normal left to right order. When visibility tag is processed and its value is false, the tag processing stops at that point. This has an effect on processing performance. In addition, possible later expression errors don’t emerge in that case.
Following abbreviated tag names can be used: attribute=att, expression=exp, parameter=par and variable=var. Tags must be written in lower case.
Attribute Tag (att)
This tag is used to get properties of QPR objects by using QPR Web Service’s GetAttributeAsString method (more information: http://kb.qpr.com/qpr2017-1/index.html?getattributeasstring.htm).
This tag uses QueryObjects instead of GetAttributeAsString, when there are multiple id’s in the object attribute or attribute followrelations used (more information below). If QueryObjects is used, separator and sortby attributes are applied.
| Attribute | Description |
|---|---|
| object (string) | Object id or list of object id’s separated by comma (,). If this contains only one id, it is passed as a parameter objectId of GetAttributeAsString method. If this attribute is not provided or is empty, the tag will be evaluated to empty. (optional) |
| attribute (string) | This is passed as parameter attribute of GetAttributeAsString or QueryObjects method. |
| options (string) | This is passed as parameter options of GetAttributeAsString or QueryObjects method. (optional) |
| expression (expression string) | An expression where the result is placed as an argument "value" (see the examples). (optional) |
| followrelations (string) | Name of the relation attributes to follow to get another object or a set of other objects. If there are multiple subsequent relations to follow, the relations are separated by comma (,) (see the examples). (optional) |
| separator (string) | Character(s) separating list of attributes of different objects. Empty values are not shown (i.e. no empties between separators). Default is a new line (<br />). (optional) |
| sortby (string) | Sorting if there are multiple objects returned. Default sorting is by name. (optional) |
| visible (boolean) | Determines content visibility shown by the tag. See Setting Content Visibility. (optional) |
Examples:
<#attribute object=="[objectId]" attribute="name"> <#attribute object="[measureId]" attribute="measure.value(series=\"ACT\",period=\"1 / 2017\")" expression="[value] * 2.54"> <#attribute object=="[measureId]" followrelatiosn="childobjects,childobjects"attribute="measure.value(series=\"ACT\",period=\"1 / 2017\")" separator="," sortby="name">
Dataset Tag
This tag is for showing information from a dataset in the web view. Dataset consist of multiple columns and rows. Dataset tags shows a header template (once) and row templates for each row in the dataset. Dataset tag has following attributes
| Attribute | Description |
|---|---|
| data (dataset) | Dataset shown by the tag. |
| headertemplate (string) | Template for dataset header. The header template is shown once before the row templates. Header template can be used e.g. for showing a column names. Header template is optional, so if the parameter is left out, no header template is shown.
Following type of parameters are passed to the header template: - columnheader_1, columnheader_2, … columheader_n containing names of the dataset columns - headerarray containing column names as an object array Note that if the column names are known, the header can be set fixed in the web view and header template is not needed. (optional) |
| headertemplatedata (byte array) | Alternative to headertemplate. Contains the used header template as a byte array. (optional) |
| rowtemplate (string) | Template for dataset rows. The template is looped for each row in the dataset in the order rows are in the dataset. Following parameters are passed to the rows template:
- column_1, column_2, … column_n containing dataset cell data - parameters which names are same as column names, containing dataset cell data - same parameters that are passed to the header template, i.e. columnheader_1, columnheader_2, … columheader_n - dataarray containing row’s data s an object array - headerarray containing column names as an object array (optional) |
| rowtemplatedata (byte array) | Alternative to row template or rowtemplateexpression. Contains row template as a byte array. (optional) |
| rowtemplateexpression (string) | Expression defining a row template. Alternative to row template or rowtemplatedata. (optional) |
| footertemplate (string) | Template for dataset footer. The footer template contents is shown once after the row templates. Footer template can be used e.g. for adding table end tags. The footer template is optional, so if the parameter is left out, no footer template is shown. The footer template has the same parameters as the header template.
Following type of parameters are passed to the footer template: columnheader_1, columnheader_2, … columheader_n containing names of the dataset columns. (optional) |
| footertemplatedata (byte array) | Alternative to footer template. Contains the used footer template as a byte array. (optional) |
| visible (boolean) | Determines content visibility shown by the tag. See Setting Content Visibility. (optional) |
| (all other attributes) | All other attributes are passed to the looped template as parameters. Note that all the above mentioned attributes are not passed as parameters, because they have a special meaning in the Dataset tag. (optional) |
Expression Tag (exp)
This tag is for adding a result of an expression (formula) in the web view. The defined expression is evaluated and the result is set in place of the tag. Also static values can be used.
Note that the tag may contain any attributes which are serving as arguments to the value expression.
| Attribute | Description |
|---|---|
| value (object) | The value produced by the tag. |
| visible (boolean) | Determines content visibility shown by the tag. See Setting Content Visibility. (optional) |
Examples:
<#expression value=="[variable1]"> <#expression value1=="5" formula=="2 * [value1] + 3"> (result is 13).
Loop Tag
This tag is for looping through content in following alternative ways:
- Set of QPR elements defined by a QPR Web Service query (more information of QueryObjects, see http://kb.qpr.com/qpr2017-1/index.html?queryobjects.htm
- List of strings (using attribute list). The list itself is a string where items are separated using defined character.
The defined template is called for every looped object.
Following additional parameters are passed to the template:
- • loopindex is an integer starting from zero
- • attributesasarray contains all attribute values as an array
| Attribute | Description |
|---|---|
| tpl | Template name for the looped content (without the file type extension in file system templates). For more information see Working with Templates. (optional) |
| tplexpression | Expression defining the template. Alternative to tpl or templatedata. (optional) |
| templatedata | Looped template file as a byte array. See available function from Binary Data Functions. (optional) |
| query | This is passed as a parameter query of QueryObjects method. |
| criteria | This is passed as a parameter criteria of QueryObjects method. This filters the output set of objects (optional) |
| sortby | This is passed as a parameter sortby of QueryObjects method. This determines the order of the looped objects. Note that without sorting the web views may look different between runs. (optional) |
| attributes | This is passed as a parameter attributes of QueryObjects method. All the queried attribute values are added as parameters to the template. (optional) |
| options | This is passed as a parameter options of QueryObjects method. (optional) |
| loopparameter | Defines the name of the parameter that is passed to the template containing the looped object id. Like other parameters, also this parameter needs to be defined in the template. |
| filter | Additional filtering for returned objects. The filtering is applied after QPR Web Service query has been run. The filter is defined as an expression (it’s not a QPR Web Service criteria), and the expression must be evaluated to boolean. All looped template parameters are available as arguments for the expression.
The filter expression is evaluated for each returned object separately. If it is evaluated to false, the object is filtered out. This additional filtering may be used if the filtering condition cannot be written using QPR Web Service’s criteria. Using QPR Web Service’s criteria is recommended because it offers better performance. (optional) |
| sortvalue | This is an expression which results are used to sort the returned objects. This sorting is applied after the QPR Web Service’s sorting (that is determined by attribute sortby). All looped parameters, template parameters, template variables are available as expression arguments (template parameters have a priority in name conflicts).
Note that because sortvalue is an expression itself, only a single equation sign is usually used. |
| list | List of items as an array that is looped through instead of a QPR Web Service query. When this attribute is used, no QPR Web Service query is made, and thus the following attributes are ignored: query, criteria, sortby attributes, and options. (optional) |
| visible | Determines content visibility shown by the tag. See Setting Content Visibility. (optional) |
| (all other attributes) | All other attributes are passed to the looped template as parameters. Note that all the above mentioned attributes are not passed as parameters, because they have a special meaning in the Loop tag. (optional) |
Example:
<#loop template="ProcessReport" loopparameter="diagramid" query=="'[' + [diagramid] + '].ChildObjects(hierarchy=\"processlevels\")'" sortby="name" attributes="description,owner.name(as= \"processowner\")" recursionlevel=="[recursionlevel] + 1">
In the example, "recursionlevel" is an additional parameter that is passed to the template. Also parameters "description" and “processowner” are passed to the template.
Parameter Tag (par)
This tag defines parameters of the template. Only parameters that are defined using these tags are used by the template, i.e. the url may also contain other parameters that are omitted.
| Attribute | Description |
|---|---|
| inputname (string) | Name of the parameter (url parameter name or a parameter name passed to template) |
| outputname (string) | Parameter name used in the template. Makes it possible to use a parameter with different name than the input name. If output value is not defined, output value is same as input value. (optional) |
| defaultvalue (object) | The default value is used when a parameter value is not passed to the template. If no default value is defined and no parameter value is passed, an error occurs. (optional) |
Example
<parameter inputname="nameOfUrlParameter" outputvalue="nameInTheTemplate" defaultvalue="value1">
Templatesettings Tag
This tag defines template level settings. The tag is optional. Only one tag of this type can exist in a template.
| Attribute | Description |
|---|---|
| allInputDataAsParameters (boolean) | If true, all parameters that are provided to the template, are initialized as parameters. Each parameter contained in the url should be mentioned by name when using the parameter tag, but with allInputDataAsParameters attribute all parameters are initialized as template parameters without explicitly defining each. Default value is false. (optional) |
| dateformat (string) | Format for shown dates. More information about formatting http://msdn.microsoft.com/en-us/library/8kb3ddd4(v=vs.100).aspx. (optional) |
| contenttype (string) | Http response’s Content-Type header when QPR Web Views data is requested. This setting only have an effect in the top level template. Default value is text/html. E.g. application/xml can be used for xml data. Available values: http://www.freeformatter.com/mime-types-list.html. (optional) |
| contentdisposition (string) | Alternative values are "attachment" and "inline". This is the http response’s content disposition’s disposition type. Default value is attachment. For more information: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition. (optional) |
| filename (string) | Filename is used with the contentdisposition attribute defined above. More information: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition. (optional) |
Template Tag
This tag is for adding content from another template. This tag is useful e.g. when there are parts that are structurally similar (making it possible to reuse a template where a part is defined once).
| Attribute | Description |
|---|---|
| tpl (string) | Template name (without file type extension in file system templates). For more information see Working with Templates. (optional) |
| templatedata (byte array) | Looped template file as a byte array. See available functions in expression language documentation in QPR Web Services Extensions Expression Language. (optional) |
| passallparameters (boolean) | Passes all parameters and variables in this template to the called sub template. |
| visible (boolean) | Determines content visibility shown by the tag. See Setting Content Visibility. (optional) |
| (all other attributes) | All other attributes are passed to the called template as parameters. Note that all the above mentioned attributes are not passed as parameters, because they have a special meaning in the template tag. (optional) |
Example:
<#template template="Template2" param1="value1" param2="value2" param3="value3">
Variable Tag (var)
This tag is used to define variables in the template. Variables can be referenced in other tags using expression arguments. Variable tags are processed in the order they appear in the template. It’s a good practice to place the variables in a same place in the beginning of a template. Variable values cannot be changed during the generation – their value is calculated when the run begins.
Variables are useful, when there is an expression which value is used several places in the template. Variables may also be used to simplify formulas, when part of a formula is defined as a variable.
There must not be a variable having a same name as a parameter in the same template. The scope of variables is the template. If the variable must available in other called templates, the variable must be passed as a parameter to the template.
| Attribute | Description |
|---|---|
| name (string) | Variable name |
| value (object) | Variable value. May be a static value or calculated from an expression. |
Example:
Template has tag <#variable name="variable1" value="2">. This variable can be used in other expressions, e.g. <#expression value="3 + [variable1]"> (result is 5).
Expression Language
QPR Web Views uses an expression language enabling all tag parameters can be written using expressions (formulas). Expressions make it possible to define values that are calculated when the web view is generated. Expression valued parameters are defined using two equal signs instead of one. As an example, a parameter value may be
- static (i.e. not an expression), such as visible="false", or
- calculated using an expression, such as visible=="[typename]='Activity'".
See QPR Web Services Extensions Expression Language for available functions and more information of the expression language.
When writing tags, character escaping is required. There are three levels of escaping, explained by the following table.
| Level | Purpose | Needed escaping | Example |
|---|---|---|---|
| 1 | QPR Web Services input | Described in the QPR Web Services documentation | QPR Web Services query:
[PG].models(criteria="name=\"model1\"") |
| 2 | Expressions | Characters \ and ' need to be written as \\ and \' | Above query escaped for an expression:
[PG].models(criteria="name=\\"model1\\"") |
| 3 | Template tags | Character " need to be written as \" | Previous expression escaped for template tag:
[PG].models(criteria=\"name=\\\"model1\\\"\") |
Note that the escaping for expressions (level 2) is not used, when the query is not in an expression.
Data from templates to other templates may be passed with any datatype, so data don’t have to be converted to string. Parameters passed to a template from a url are always strings.
If an expression tag returns a datetime value, it is implicitly converted to string if it’s shown in the web view. Templatesettings tag’s dateformat parameter is used for this.
Setting Content Visibility
Most tags support parameter visible, which is used to hide the content the tag is about to add. Available values are true (shown) or false (hidden). Also the visible parameter can be defined using expressions. Visible tag is optional, and by default its value is true (i.e. the tag is shown).
When a tag is set to hidden, its expressions are not evaluated nor is related QPR data fetched. The tag may thus contains errors, which don’t emerge if the tag is hidden.
Calling QPR Web Service from JavaScript
QPR Web Views based solutions may need to call QPR Web Service from JavaScript code. The following wrappers are available for often needed QPR Web Services methods. It’s recommended to use the wrappers instead of calling QPR Web Service directly.
| Web Service method | Description |
|---|---|
| GetBinaryData.ashx | Wrapper for QPR Web Services’ GetBinaryData method (http://kb.qpr.com/qpr2017-1/index.html?getbinarydata.htm).
Parameters:
|
| GetGraph.ashx | Wrapper for QPR Web Services’ GetGraph method (http://kb.qpr.com/qpr2017-1/index.html?ws_getgraph.htm).
Parameters:
|
| GetPortalUrl.ashx | Wrapper for QPR Web Services’ GetPortalUrl method (http://kb.qpr.com/qpr2017-1/index.html?getportalurl.htm).
Parameters:
|
Example <pre http://localhost/QPRWebServicesExtensions/GetBinaryData.ashx?objectid=PG.12345.6789&attribute=embeddeddata&options=