QPR PowerPoint Reports
Introduction to QPR PowerPoint Reports
Majority of the concepts related to QPR Word Reports also apply to QPR PowerPoint Reports. The following QPR Word Reports sections are valid also for QPR PowerPoint Reports:
- Working with report templates
- Tags that can be used in templates
- Expression language that can be used in tags
- Authentication and data security
QPR PowerPoint Reports supports Open XML file format, and files of that format be opened e.g. in Microsoft Office and OpenOffice. Report templates can be either pptx or pptm files. Mediatype for the downloaded final report is application/vnd.openxmlformats-officedocument.presentationml.presentation.
More information about Open XML format: https://support.office.com/en-us/article/open-xml-formats-and-file-name-extensions-5200d93c-3449-4380-8e11-31ef14555b18
QPR PowerPoint Reports can be accessed using the following url:
http(s)://SERVERNAME/QPRWebServicesExtensions/DynamicPowerPointReports.ashx?report=reportname¶meter1=param1value¶meter2=param2value
where SERVERNAME is the hostname of your QPR server.
The report template is processed into the final report as follows. Slides are processed one by one starting from the first slide. When a slide is processed, the slide notes are processed first, and following tags are searched in the notes: parameter, variable, reportsettings and loop. The scope for the defined parameters and variables is the notes part only. If loop tag is defined, new slides are created based on how many times the slide is looped (it's also possible to loop multiple slides). When the loop tag is processed, the slide processing is stopped, and the processing starts again from the first looped slide. Now slide content and comments are processed, and following tags are searched: parameter, variable, reportsettings, attribute, expression and link (note that loop tags cannot be used here). Parameters and variables need to be defined for each slide separately.
Configuration
Following table contains QPR PowerPoint Reports parameters, which are configured in the QPR Reporting Add-on web.config file (by default in C:\inetpub\wwwroot\QPRWebServicesExtensions\web.config).
| Parameter | Description |
|---|---|
| dprtemplatesphysicalpath | Folder in the file system where QPR PowerPoint Reports template files are located. |
| reporttemplateparameter (optional) | Defines the name of the parameter for the report template path. By default, it is report. See chapter Working with Report Templates for configuring the report template path. |
| defaultimageformat (optional) | Default image format for QPR Web Service’s GetGraph method. This setting is used if image format is not explicitly defined in the GetGraph options. |
Setting Content Visibility
Tags Attribute, Expression, Image, Link and Loop tags have a parameter visible, which can be used to hide the content that the tag is about to render. Available values are true (shown) or false (hidden). By default, the visible property is true (the tag is shown).
Tags
Attribute Tag (att)
Attribute tag is used to show a property of an object. The attribute value is fetched 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, if there are multiple id's in the object attribute or if attribute followrelations used (more information below). If QueryObjects is used, separator and sortby attributes are applied.
| Parameter | Description |
|---|---|
| object (string) | A single object id or a comma separated list of object id's. If there is only one object, it is passed as a parameter objectId of GetAttributeAsString method. If there are no object id's at all, the tag result will be empty. (optional) |
| attribute (string) | Attribute name to be shown. This is passed as a parameter attribute of GetAttributeAsString or QueryObjects method. |
| options (string) | This is passed as a parameter options of GetAttributeAsString or QueryObjects method. (optional) |
| expression (expression string) | An expression used to modify the returned attribute values, e.g. to make conversions etc. The attribute value is placed as an argument "value" to this expression (see the examples). (optional) |
| followrelations (string) | Name of the relations 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) | If multiple objects are defined, this property defined the character(s) separating the shown attributes of multiple objects. Empty values are not shown (i.e. no empties between separators). Default is a new line character. (optional) |
| sortby (string) | Applied sorting if there are multiple objects returned. Default sorting is by the name attribute. (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 / 2018\")" expression="[value] * 2.54"> <#attribute object=="[measureId]" followrelations="childobjects,childobjects"attribute="measure.value(series=\"ACT\",period=\"1 / 2017\")" separator=", " sortby="name">
Expression Tag (exp)
Expression tag is used to add a result of an expression (formula) to a slide. The defined expression is evaluated and the result is set in place of the tag. The tag may contain any parameters which are provided as arguments to the expression (see examples).
| Parameter | Description |
|---|---|
| value (object) | Text producted by the tag. Expression behavior is achieved when this parameter is defined as an expression. Note that the values shown in the report are always strings (sequence of characters), so the value must be of a type that can be converted into a string, such as string, integer, double, datetime, boolean, or an array of any of the previous types. If the value is not a string, an implicit conversion to a string is made. In case of date type, dateformat defined in the Reportsettings tag or a default format yyyy-MM-dd is used. |
| visible (boolean) | Determines content visibility shown by the tag. See setting content visibility. (optional) |
Examples:
<#expression value=="'Value is: ' + [variable1]"> <#expression value1=="5" value=="2 * [value1] + 1"> (result is 11).
Image Tag
Image tag is used to add an image in the slide. Images can be fetched from different sources, see different options in availablebinary data functions.
If there are errors in fetching the image, an error message is placed as the description text of the placeholder image in the final report.
Image size in the slide depends on its resolution and the properties listed below. Image size is calculated as follows:
- dpi defines image base size (dpi can be defined explicitly or used image’s dpi value)
- scaling is applied for that (expanding or shrinking the image)
- maxwidth and maxheight restrictions are applied last maintaining the aspect ratio (always shrinking)
In the expressions of the dpi, scaling, maxwidth and maxheight parameters, it’s possible to use following arguments representing information from the image (see an example below):
- width (int)
- height (int)
- horizontaldpi (decimal)
- verticaldpi (decimal)
- format (string) (e.g. png, jpeg, gif)
If you need an image to appear always as a certain size regardless of its resolution, the scaling can be defined as a large enough number, and set maxwidth (or maxheight) to be the desired image size. This way the maximum width restriction is always applied and the size of the image is the desired.
| Attribute | Description |
|---|---|
| imagedata (byte array) | Image as a byte array. See available functions in expression language documentation in Binary Data Functions. Note that the type of the file needs to be a bitmap e.g. png, jpg or gif. |
| dpi (decimal) | Determines the image size as dots per inches. If not defined, dpi information in the image data is used. (optional) |
| scaling (decimal) | Image scaling as percentage value ("100" means no change in size). E.g. value "200" doubles the size of the image. Scaling is applied before maximum width and height restrictions. (optional) |
| maxwidth (decimal) | Maximum image width in centimeters. If the image is wider than this maximum width, the image is scaled smaller to so that its width is this maximum width. (optional) |
| maxheight (decimal) | Maximum image height in centimeters. If the image is higher than this maximum height, the image is scaled smaller to so that its height is this maximum height. (optional) |
| crop (boolean) | Determines whether unnecessary areas near the borders are removed from the image. Needed if the image contains too much white (or other background color) space. If the whole image is white color it is removed. Either "true" or "false". Default is false. (optional) |
| backgroundcolor (string) | Defines the background color of the image for cropping unnecessary borders. The background color is defined as an RGB hexadecimals, e.g. "00FFb7". Default is white ("FFFFFF"). (optional) |
| croptop (integer) | Number of pixels to remove from the top side of the image. If trying to remove more than the size of the image, heigth of the resulting image will be one pixel. (optional) |
| cropright (integer) | Number of pixels to remove from the right side of the image. If trying to remove more than the size of the image, width of the resulting image will be one pixel. (optional) |
| cropbottom (integer) | Number of pixels to remove from the bottom side of the image. If trying to remove more than the size of the image, heigth of the resulting image will be one pixel. (optional) |
| cropleft (integer) | Number of pixels to remove from the left side of the image. If trying to remove more than the size of the image, width of the resulting image will be one pixel. (optional) |
| centerhorizontally (boolean) | When replacing the placeholder image with the real one, this setting determines whether to keep the center spot of the image in the same place. When false, the left border of the image is stays in the same place. (optional) |
| centervertically (boolean) | When replacing the placeholder image with the real one, this setting determines whether to keep the center spot of the image in the same place. When false, the top border of the image is stays in the same place. (optional) |
| visible (boolean) | Determines content visibility shown by the tag. See setting content visibility. (optional) |
Examples
<#image object=="QprGraphData([diagramid], 'graphtype=processlevel,witdh=1500')" maxwidth="17.5" dpi="1.5*[horizontaldpi]">
<#image imagedata=="httpFileData('https://www.qpr.com/')">
Link Tag
Link tag is used to add a clickable hyperlink to a slide. If the link address is empty or other ways invalid, no link is displayed in the report. Note that the tag generates the hyperlink, so the report template should not already contain a hyperlink, but only the tag as text.
| Parameter | Description |
|---|---|
| address (string) | Url address (location) to which the hyperlink is pointing. |
| text (string) | Link’s displayed text. |
| screentip (string) | Link’s screen tip. (optional) |
| target (string) | Link’s target. (optional) |
| visible (boolean) | Determines content visibility shown by the tag. See setting content visibility. (optional) |
Example
<#link address=="getPortalUrl([diagramid], '', '')" text="Link to QPR Portal" target="_BLANK" screentip="Click here is go to QPR Portal">
Loop tag
Loop tag is used to repeat slides. The Loop tag must be defined in the notes section of the first looped slide. If there are multiple slides to be looped, define the number of slides using the slidecount parameter. If there is only one slide to be looped, there is no need to define this parameter, as by default it's 1.
All parameters and variables defined in the notes section can be used in the loop tag. Note that parameters and variables defined in the slide content cannot be used by the Loop tag. Also, it's not possible to define a Loop tag in the slide content.
| Attribute | Description |
|---|---|
| dataset (dataset) | Dataset looped by the tag. There will be as many slides as there are rows in the dataset, when a single slide is looped. All columns are available as parameters in the looped slides. Note that the parameters need to be defined in the slide content. |
| slidecount (integer) | Number of slides that are repeated. By default only the slide where the Loop tag is defined is repeated. (optional) |
| visible (boolean) | Determines content visibility shown by the tag. See Setting Content Visibility. (optional) |
| (all other parameters) | All other attributes are passed to the looped slides as parameters. Note that the above mentioned attributes are not passed as parameters, as they have a special purpose in the tag. (optional) |
Examples:
<#loop dataset=="AddDatasetRow(AddDatasetRow(AddDatasetRow(CreateDataset(Array('Risk', 'Cost', 'Category')), 4, 6, 'Category 1'), 2, 3, 'Category 2'), 1, 8, 'Category 3')" slidecount="2" extraparameter="myValue">
Parameter Tag (par)
Parameter tag defines parameters for the slide. Only parameters that are defined using Parameter tags are available to be used in the report. The report request url may contain parameters which are omitted in the report. Defining parameters makes sure that the needed parameters are passed to the report when the report is run (running report gives an error if this is not the case).
| Parameter | Description |
|---|---|
| inputname (string) | Name of the parameter in the url. |
| outputname (string) | Parameter name used in the report. If this is not defined, the used name is same as the input name. With this setting, it's possible to use different name in the report template than the name passed to the report in the url. (optional) |
| defaultvalue (object) | The default value is used when the parameter is not passed to the report. Defining a default value means that the parameter is optional. If no default value is defined and the parameter is not passed, an error occurs. (optional) |
| datatype (string) | Converts the parameter value into the defined format. Possible formats are integer, double, boolean, datetime and string. All parameters are strings by default, because the url address is a string. This setting can be used to convert numerical parameter values into numerical datatypes. (optional) |
| validation (expression string) | Validation expression for the parameter. There is an argument value available (containing the parameter value) in the validation expression. If the expression returns false, a validation error is thrown by the report. The there are certain special requirements for the parameters, they can be checked using the validation expressions, e.g. value must be a positive integer. |
| validationmessage (string) | Error message to show, if the validation fails (see the validation parameter). |
Example
<parameter inputname="nameOfUrlParameter" outputvalue="nameInTheReport" defaultvalue="value1">
Reportsettings Tag
Reportsettings tag is for defining the report level settings. The tag is optional. Maximum of one Reportsettings tag can exist in a single PowerPoint template.
| Attribute | Description |
|---|---|
| name (string) | Name of the downloaded report. If this is not defined, the report name is same as the name of the template. (optional) |
| dateformat (string) | Formating for date type of information that is shown in the report. More information about formatting http://msdn.microsoft.com/enus/library/8kb3ddd4(v=vs.100).aspx. Default date format is yyyy-MM-dd. (optional) |
| contentdispositiontype (string) | This setting sets the http response’s content disposition’s disposition type. Allowed values are attachment and inline. Default value is attachment. More information http://www.ietf.org/rfc/rfc2183.txt. (optional) |
Example
<#reportsettings name="Process report" updatefields="true" contentdispositiontype="inline">
Variable Tag (var)
This tag is used to define a variable in the slide. Variables can be used in other tags as expression arguments. Variable values cannot be changed during the report run – their value is calculated when the report run begins.
Variables are useful, when there is an expression which value is used several places in the report. Variables may also be used to simplify formulas, when part of a formula is defined as a variable. There cannot be a variable having a same name as a parameter in the same report.
| Attribute | Description |
|---|---|
| name (string) | Variable name. |
| value (object) | Variable value. |
Example: Report has tag <#variable name="variable1" value="2">. This variable can be used in other expressions, e.g. <#expression value="3 + [variable1]"> (result is 5).
Direct Tags
It’s possible to reference to parameters and variables using tags which name equal parameter or variable name. These are called direct tags. For example if a report has a variable var1, a tag <#var1> can be used. Note that, the same result can be achieved using variable tag: <#variable value=="[var1]">.
Note the following when using direct tags:
- Direct tags cannot contain any attributes, unlike all other tags always contain at least one attribute.
- In the direct tags, variable value is implicitly converted into string. E.g. date variables are converted using date format defined in the Reportsettings tag.
- It's not possible to use visible attribute.