HTML Properties

The HTML presentation object is used to display custom written HTML content inside QPR UI views. HTML presentation objects are able to interact with context variables. Main differences to External Content presentation object are follows:

External content is basically a link to an external web page that resides outside QPR UI. HTML presentation object settings contains the needed HTML code, and thus the content is stored to QPR UI and transfered when exporting and importing views. Still, the HTML code may refer to external resources in web, but that should be avoided so that views are easily deployable.
External content presentation object is not able to draw outside its area in the view. This is because External content presentation object is tecnically an iframe, and browsers don't allow iframes to draw to its parent window area. HTML presentation object is able to draw outside its content area.
The HTML code in the HTML presentation object is not an entire web page but an HTML block, such as a DIV tag. External content presentation object needs to link to full web page (starting with HTML tag).

Security note: HTML presentation objects can embed JavaScript code into the dashboards, which may cause information security issues, because the embedded code is executed when users open the dashboard. Thus the dashboard designer persons need to be trusted. Viewer users are not able to change dashboards and embed JavaScript code into dashboards.

Properties Tab

The following properties can be set on the Properties tab:

Name: Name of the HTML presentation object. The name is not visible in the dashboard.
Description: Description for the HTML presentation object. The description is not visible in the dashboard.

Datasets Tab

Presentation Tab

The following settings can be set on the Presentation tab:

HTML code contains the HTML that will make up the displayed HTML content. Also CSS and JavaScript blocks can be used. You can also use context variables in the HTML code. If the used context variable values change, the HTML presentation object is initialized and possible stored state in JavaScript variables in the code are lost.
Horizontal / Vertical scrollbar defines how the horizontal or vertical scrollbar is shown for the HTML presentation object. Options are:
- Auto: Scrollbar is visible if the content is scrollable (i.e. HTML presentation object height is greater than the available area for the presentation object in the view). Scrollbar is hidden, if the content is not scrollable. Setting widths of the HTML content programmatically may be more difficult as the available width depends whether the vertical scrollbar is shown.
- Visible: Scrollbar is always visible. If the content is not scrollable, the scrollbar is grayed.
- Hidden: Scrollbar is never shown. This setting can be used when the HTML presentation object should not contain scrollbars to prevent the scrollbars appearing in any case. If the height of the HTML presentation object is greater than the available area in the view, rest of the content is not accessible.

Setting Context Variables

Context variable values can be modified by the HTML presentation object using the following JavaScript functions in the code:

Function name	Function parameters	Description
qpr.setSessionVariable	variable name (String) variable value (String) presentation object runtime id (String) create history entry (Boolean)	Changes a variable value. The presentation object runtime id defines the scope where the variable is set. null means setting the variable in the session scope. When setting variables defined in UI element scopes, the scope can be set to be the current presentation object with the <#uniqueId> tag (see examples below). Remember to use quotes, as presentation object runtime id is a string. The history entry is a boolean value defining whether to create a new browser history entry of the variable change. true defines that a new browser history entry is created, meaning that when a user clicks the Back button, it reverts the changed variable value to a state before the variable value change. When false, the variable value change is embedded to the last already existing history entry. The parameter is optional and by default it's true. More information about web browser history: https://developer.mozilla.org/en-US/docs/Web/API/History_API.
qpr.setSessionVariables	variables to set (object)	Sets multiple variables at the same time. When variables are changed at the same time, any functionality is not executed between the variable value changes. For example, if there is query using two variables, and the variables are changed at the same time, the query is rerun after the both variables have been changed. If using the qpr.setSessionVariable function twice for the same purpose, the query is rerun instantly after the first variable change and then second time after the other variable change. For this function, there is one parameter which is an array of objects, where each objects has the following properties: key: Variable name. value: Variable value. presentationObjectRuntimeId: defines the scope where the variable is set. This function doesn't support the history entry parameter, and a new history entry is created every time when this function is used.
qpr.deleteSessionVariable	variable name to delete (String) create history entry (Boolean)	Deletes a session variable. Creating a new history entry works like in the qpr.setSessionVariable function. Note that it's not possible to delete variables defined in UI element scopes.

Examples:

Set a session scope context variable value:
qpr.setSessionVariable("variable1", "value1");

Set a UI element scope context variable value:
qpr.setSessionVariable("variable1", "value1", "<#uniqueId>");

Set a session scope context variable value without creating a new browser history entry:
qpr.setSessionVariable("variable1", "value1", null, false);

Set multiple context variables at the same time:
qpr.setSessionVariables([
  {key: "variable1", value: "value1", presentationObjectRuntimeId: "<#uniqueId>"}, //UI element scope variable
  {key: "variable2", value: "value2"} //session scope variable
]);

Delete a session scope context variable value:
qpr.deleteSessionVariable("variable1");

Available Callback Functions

It's possible to use below listed callback functions in the HTML code. Callback function is a function that QPR UI calls when a certain event occurs. The following callback functions are available:

Function	Description
function <#contextChangeFunction>(changedContextVariables)	This function is automatically called by QPR UI when the variables seen by the HTML presentation objects change. The changed variables are available in the changedContextVariables parameter as key-value pairs. This function is also called when the HTML presentation object is initialized (the view is loaded). Use this function to write custom logic that should occur in the HTML presentation object when variables change.
function <#resizeFunction>(newWidth, newHeight)	This function is automatically called by QPR UI when the HTML presentation object drawing area in the view changes, for example as a result of changing browser window size. The function is needed, if the resize logic needs to be written using JavaScript. This function is called also when the HTML presentation object is initialized (the view is loaded).
function <#datasetChangeFunction>(datasetIdentifier, datasetChangeCallbackFunction)	This function is called when anydatasets change that are visible to this HTML presentation object. Changed dataset identifier is provided as the first parameter. The second parameter is a callback function, which can be called if the HTML presentation object needs to access the changed dataset data. As a parameter for this callback function, you need to provide the function that is then called back by QPR UI with the actual dataset data. See the example below in this page.

Notes:

These functions need to be defined inside the script block.
The actual function names are not known in view design time and this is why the tag syntax is used. QPR UI will replace the tags with the actual function names when the HTML presentation object is rendered. This is also to guarantee that the function names are unique when there are same HTML code used multiple times in the view.
These functions are not called when the HTML presentation object is hidden (using the Show in view setting).

Direct Queries to Datasources

It's possible to fetch data from QPR UI datasources (QPR Suite Web Service, QPR ProcessAnalyzer, and QPR Reporting Expression) without creating datasets, called direct queries. This is done using JavaScript function qpr.runQuery(datasourceType, queryParameters, successCallback, errorCallback, identifier).

Parameters for the qpr.runQuery function:

datasourceType: The used datasource type. Possible values are QprSuite, QPRProcessAnalyzer, and QPRReportingExpression. You can also use the following constants: qpr.DatasourceTypes.QPRSuite, qpr.DatasourceTypes.QPRProcessAnalyzer and qpr.DatasourceTypes.QPRReportingExpression.
queryParameters: Query parameters as a JavaScript object. Note that you need to use \n as linefeed, and escape double-quotes with the \ character. The available parameters are:
- query: The actual query. Used with all datasource types.
- criteria: Used with the QprSuite datasource type. See QPR Suite Web Service for the description.
- sortby: Used with the QprSuite datasource type. See QPR Suite Web Service for the description.
- attributes: Used with the QprSuite datasource type. See QPR Suite Web Service for the description.
- options: Used with the QprSuite datasource type. See QPR Suite Web Service for the description.
successCallback: The callback function to execute when the query is successfully run and data is available.
errorCallback: The callback function to execute when running the query fails. The function can have the following parameters:
- errormessage: The error message. Always used.
- identifier: Used if the identifier parameter was provided for the qpr.runQuery function.
- wserror: If the query failed and the error originated from the web service, the wserror contains an object which describes the details of the error.
identifier: An optional javascript object that is returned fo the success and fail callbacks.

For example, the following HTML code will query the names and descriptions of all the QPR Metrics models with the text Dentorex in their names available in the QPR Suite Web Service, and display the queried data in a data grid:

<div id="grid<#uniqueId>"></div>

<script>
(function() {

  function dataAvailable(data, identifier) {  
    if (data == null || data.sheets == null || data.sheets.length == 0 || data.sheets[0] == null || data.sheets[0].values == null || data.sheets[0].values.length == 0) return;
    var convertedData = [];
    for (var row = 1; row < data.sheets[0].values[0].length; row++) {
      var rowObject = {};
      for (var column = 0; column < data.sheets[0].values.length; column++) {
        rowObject[data.sheets[0].values[column][0].attribute] = data.sheets[0].values[column][row].value;
      }
    convertedData.push(rowObject);
    }
    $("#grid<#uniqueId>").ejGrid({dataSource: convertedData});
  }

  function errorOccurred(errormessage, identifier, wserror) {
    alert("failure, message: " + errormessage +  ", identifier: " + identifier + ", error details: " + wserror);
  }

  var datasourceType = qpr.DatasourceTypes.QPRSuite;
  var identifier = "myQueryIdentifier";
  var parameters = {
    "query": "[SC].Models",
    "attributes": "name, description",
    "criteria": "Find(\"Dentorex\", name)",
    "sortby": "name",
    "options": ""
  };

  qpr.runQuery(datasourceType, parameters, dataAvailable, errorOccurred, identifier);
})()
</script>

See the Examples section for more example(s).

Import QPR ProcessAnalyzer Data

QPR ProcessAnalyzer data can be imported by using the JavaScript function qpr.ImportProcessAnalyzerData(csvData, parameters, successcallback, errorcallback). Parameters for the qpr.ImportProcessAnalyzerData function:

csvData: A javascript file object or a string containing the imported data. It can be fetched with the following kind of query: $('input[type="file"]').inputFile[0].files[0].
parameters: A JSON object with the following contents:
- FileType: String. Defines the format of the imported file. Options are csv, pacm and xes.
- FileName: String. Name of the imported file (optional). If FileType parameter is not provided, the file format is determined from the extension of the file name.
- ImportMode: String. Defines which kind of data is imported. Options are 0 (events), 1 (cases) (default) and 2 (datatable).
- DataTableName: Name of the datatable. Used when ImportMode=2.
- CSVDelimiter: String. The delimiter character. The default is ; (semicolon).
- CSVQualifier: String. Default value is " (doublequote).
- CSVTimeFormat: String. The date format to use. Default value is yyyy-MM-dd HH\\:mm\\:ss,fff.
- CSVStartImportFromLine: String. Row number from which the import is to be started. Default value is 1.
- DestinationType: String. Use value 0, when creating a new model. Use value 1, when importing data to an existing model.
- TargetProjectId: Integer. QPR ProcessAnalyzer project id. Used when creating a new model to an existing project (DestinationType=0). When creating a new project, this parameter is left null.
- ModelName: String. QPR ProcessAnalyzer model name. Used when creating a new model (i.e. DestinationType=0).
- TargetModelId: Integer. QPR ProcessAnalyzer model id. Used when importing data to an existing model (i.e. DestinationType=1).
successcallback(TargetProjectId, modelId, viewId): The function that is called when the import is finished and no errors occurred. The parameters (integers) indicate the project/model/view where the import was done.
errorcallback(message): The function that is called if an error occurred. Message (string) describes the error.

Event Data CSV Format

The CSV file containing Event Data to be imported should use the following format:

Delimiter = Semicolon, Tab or Specified in the "Other" field
Text Qualifier = Specified in the "Text qualifier" field
Date Format (only used for the start time field) = Specified in the "Date Format" field. Supported format is: "yyyy-MM-dd HH:mm:ss,fff", where dd = zero-padded day of the month, from 01 through 31; MM = zero-padded month, from 01 through 12; yyyy = year as a four-digit number; HH = zero padded hour, using a 24-hour clock from 00 to 23; mm = zero-padded minute, from 00 through 59; ss = second, from 00 through 59; fff = millisecond.
EndOfLine = CR+LF (i.e. Windows style)

Therefore, the CSV file having Event Data to be imported can be roughly in the format as in the example below:

Case ID;Activity;Start Time;SAP_User;Organization
2208767;Handling unit;2011-11-17 08:24:12,018;Timothy;Delivery
2208767;Invoice;2011-11-18 15:41:32,670;Sharon;Finance
2208767;Outbound Delivery;2011-11-14 04:15:55,133;James;Delivery

Case Attributes CSV Format

The CSV file containing Case Attributes to be imported should use the following format:

Delimiter = Semicolon, Tab or Specified in the "Other" field
Text Qualifier = Specified in the "Text qualifier" field
EndOfLine = CR+LF (i.e. Windows style)

Therefore, the CSV file having Case Attributes to be imported can be roughly in the format as in the example below:

Case ID;Region;Cost;Account Manager;Product Group;Customer Group
2208767;New York;1141;William Davis;Shirts;Kids
2381009;Los Angeles;623;William Davis;Shirts;Kids
3393390;New York;1124;Patricia White;Socks;Men

Note: When importing a CSV file, QPR ProcessAnalyzer tries to identify the correct character encoding. If the identification fails and you see some incorrect characters, save the CSV file in UTF-8 encoding before the import, for example in the following way:

Open the file in Notepad.
Select File > Save As.
Change the Encoding to be UTF-8.

Tag uniqueId

<#uniqueId> tag can be used in the HTML code. It provides a unique number in the entire view (also inside Repeater). The unique number is useful to be able to generate unique HTML id's. See the example below for a usecase. Unique id's are needed because all HTML presentation objects' code belong to the same HTML page, and there should be a way to differentiate between HTML presentation objects. This way exactly the same HTML code can be used in different HTML presentation objects in the same view.

Best Practices for HTML Presentation Objects

HTML presentation objects should be created in a way that they draw inside the presentation object area in the view. In practice, the css position property should be static (more information: https://www.w3schools.com/css/css_positioning.asp). It's possible to create HTML presentation objects that draw outside its area but those HTML presentation objects might not be fully compatible with the future QPR UI releases. It's still allowed to create these kind of HTML presentation objects if preparing to adjust them during QPR UI version upgrades.

When defining CSS styles in HTML presentation objects, note that CSS definitions are global in the HTML page, and thus it's possible to add CSS that affects structures outside the HTML presentation object. To make sure that the CSS doesn't have unintentional effects outside the HTML presentation object, use id's or classes that are unique. It can be done by using the <uniqueId> tag in the name of the id or class.

Example: Reading Datasets

In the HTML code, it is possible to define a callback function that is called when a dataset changes. This change function is also called for all available datasets, when the HTML presentation object is drawn. The dataset itself is available as a table. Eaxmple code:

<div id="content_<#uniqueId>"></div>

<script>
function <#datasetChangeFunction>(datasetIdentifier, datasetChangeCallbackFunction) {
  if (datasetIdentifier == "myDataset") {
    datasetChangeCallbackFunction(myDatasetAvailable<#uniqueId>);
  }
}

function myDatasetAvailable<#uniqueId>(datasetData) {
  if (datasetData == null || datasetData.sheets == null || datasetData.sheets.length == 0 || datasetData.sheets[0] == null || datasetData.sheets[0].values == null || datasetData.sheets[0].values.length == 0) return;
  var convertedData = [];
  for (var row = 1; row < datasetData.sheets[0].values[0].length; row++) {
    var rowObject = {};
    for (var column = 0; column < datasetData.sheets[0].values.length; column++) {
      rowObject[datasetData.sheets[0].values[column][0].attribute] = datasetData.sheets[0].values[column][row].value;
    }
    convertedData.push(rowObject);
  }
  $("#content_<#uniqueId>").ejGrid({dataSource: convertedData});
}
</script>

See the Pivot Grid, Bubble Chart, Gantt Chart, and Multiselect Dropdown List links below for more examples.

Examples