Html Report
The Html Report allows you to create a Widget in HTML and JavaScript that displays the results of a Data Query. Hence, Html Report Widgets are similar to Html but Html Report require a Data Query that delivery data to them which the Html Widgets do not required. Html Report should be used when you work with the results of a Data Query and the desired functionality cannot be realized with existing Widgets but you do not need the full range of capabilities of Custom Widgets. Therefore, Html Report fills the gab between existing Widgets, including View Widgets, Form Widgets on one side and Chart Widgets on the other side.
If your HTML and JavaScript code does not interact with the result of a Data Query, you should use Html instead of Html Report.
Widget properties
- Widget version - Version of the Widget used in this Dashboard. If a new version of this Widget is available and you want to use it, you have to manually update the version here. When a new Widget is added to the Dashboard, automatically the latest version is placed.
- Template - Here you have to enter the HTML and JavaScript code that defines the behavior of the Html Report.
- Html Report supports jQuery to implement the JavaScipt code.
- Access to the results of the Data Query is given by the the following codes:
{{#each row}}
and{{/each}}
marks the start and the end of the block in which the results of the Data Query are used- In this block the Html Report automatically iterates over all rows in the Data Query result
{{ColumnName}}
accesses the entry of the column with the nameColumnName
in the current row.- See the example below for how
{{#each row}}
,{{ColumnName}}
and{{/each}}
are used.
- Data query - The Data Query providing the data for the Html Report. The Data Query is only allowed to deliver one Result Set
- Set data query parameters to fixed values (Key: data query parameter, value: fixed value) - Maps fixed values to the parameters of the Data Query that provides the data for the Widget:
- Add - Adds a new Data Query parameter mapping
- Key - Name of the Data Query parameter, i.e, target of the mapping
- Value - Value of the Data Query parameter entered directly here, i.e., source of the mapping
- - Removes the Data Query parameter mapping
- Set data query parameters to dashboard parameters (Key: data query parameter, value: dashboard parameter) - Maps Dashboard Parameter to the parameters of the Data Query:
- Add - Adds a new Data Query parameter mapping
- Key - Name of the Data Query parameter, i.e, target of the mapping
- Value - Name of the Dashboard Parameters parameter, i.e., source of the mapping
- - Removes the Data Query parameter mapping
Example
This example renders the Data Query as a table and offers the possibility to change the row color. The color change depends on the button the User presses and the on a Dashboard Parameter. For this code to depends on a Data Query in a special format and a single Dashboard Parameter:
- The Data Query must return three columns with the names
Id
,ShortName
andDescription
. These content of these columns is rendered by the code{{Id}}
,{{ShortName}}
, and{{Description}}
, respectively. - There is only one Dashboard Parameter and this Dashboard Parameter holds a valid row number of the rendered table. Obviously, the row number should be checked if it is well-defined and in the correct boundaries of the table, but this is omitted here to keep the example short.
<script>
// Function to change to row's background color to yellow
function onYellowClick() {
// Get the value of the first parameter. This is the index of the row
var row = aurora.getExistingParamsFromUrl()[0].Value;
// Change the background color of the row
document.getElementById("myTable").getElementsByTagName("tr")[row].style.backgroundColor = "yellow";
}
// Function to change to row's background color to red
function onRedClick() {
// Get the value of the first parameter. This is the index of the row
var row = aurora.getExistingParamsFromUrl()[0].Value;
// Change the background color of the row
document.getElementById("myTable").getElementsByTagName("tr")[row].style.backgroundColor = "red";
}
</script>
<!-- CSS formatting of the table -->
<style>
table {
width: 100%;
}
td,
th {
border-bottom: 1px solid #dddddd;
text-align: left;
padding: 8px;
},
th {
font-weight: bold;
}
</style>
<!-- Render the actual table -->
<table id="myTable" >
<!-- Render the table head -->
<tr>
<th>Unique ID</th>
<th>Element Name</th>
<th>Sales Text</th>
</tr>
<!-- For each row in the Result Set the block between {{#each rows}} and {{/each}} is repeated. -->
<!-- {{ColumnName}} accesses the value of the column in the current row -->
{{#each rows}}
<tr>
<td>{{Id}}</td>
<td>{{ShortName}}</td>
<td>{{Description}}</td>
</tr>
{{/each}}
</table>
<!-- Button to change the row's background color to yellow -->
<button onclick="onYellowClick()" type="button">Yellow</button>
<!-- Button to change the row's background color to red -->
<button onclick="onRedClick()" type="button">Red</button>
JavaScript Functions
The usage of jQuery is supported in the in your JavaScript and HTML code. Furthermore, additional JavaScript Functions are available to interact with Novunex Platform specific functionality. These functions are available by calling aurora.functionName(...)
, where functionName
can be one of these functions:
-
apiUrl()
- Returns the base URL of the core API -
clientBaseUrl()
- Returns the base URL of the current Account -
createGuid()
- Generates a unique identifier in GUID format -
debounce( func, wait, immediate )
- Delays the call of the functionfunc
by the waiting time specified inwait
.wait
is interpreted as milliseconds. The wait is only executed ifimmediate
is set tofalse
. Ifimmediate
is set totrue
,func
is called immediately. -
forceLogout()
- Forces an logout from the current user session -
getAccessToken()
- Returns the current access token of the authenticated User -
getApiSubscriptionKey()
- Returns the API Subscription key -
getExistingParamsFromUrl()
- Returns all Dashboard Parameters as an array. Each element in the array is an object in the form of{ "Name": "ParameterName", "Value": "ParameterValue" }
. -
getFromCache( name )
- Retrieves the value stored in the local cache under the keyname
. All values are returned as string. -
getSubscriptionId()
- Returns the current Subscription ID -
hexToRgb( hex )
- Converts the hex color string inhex
to a RGB color string, e.g. “03F” to “0033FF” -
htmlEncode( val )
- Encodes the stringval
to be in the HTML format, e.g., replacing<
,>
characters. -
parseExpression( expressionString, contextIndex )
- Replaces variable names in theexpressionString
with their value.expressionString
has to be a valid Form Control Expression and the variables have to be defined in the current context.contextIndex
is deprecated and can be leftnull
. -
pushToCache( name, value )
- Storesvalue
in the local cache under the keyname
-
slugify( text )
- Generates URL slugs, i.e, replaces white spaces within-
characters, removes all non-word characters, replaces multiple-
with single-
characters and trims start and end of string from any white spaces -
tryParseJson( jsonString )
- ParsesjsonString
into a JavaScript Object. If the parsing fails,false
is returned. -
showApiError(...)
- Generates an error popup and is used used in to handle the failure of theajax(...)
and theupload(...)
function. See the documentation of theupload(...)
function for an example usage. -
ajax( settings )
- Executes a core service API call by calling thejQuery.ajax()
function of the jQuery framework.settings
is passed to the jQuery function. See the documentation of theupload(...)
function for an example usage. -
upload( type, url, data )
- Starts a file upload request, that has to be done in two steps:- The file content is uploaded first by calling
upload( type, url, data )
, wheretype
specifies the HTTP method,url
specifies the target of the request anddata
holds the actual data. The data has to be encoded asmultipart/form-data
and can hold the content of one or more files, but all files combines must be below the limit of 512MB. To keep the code responsive, it is advised to limit the number of files uploaded each time.upload(...)
uploads the file content, creates the file in the file storage of the Novunex Platform and then returns the list of URIs to uniquely identify the newly created files on the Novunex Platform. The list of URIs is sorted in the same order as the list uploaded files. - The meta data is uploaded next by calling
ajax(...)
. The meta data can also be uploaded as a list to handle multiple files at the same time, just like the file content before was. Obviously, this list need to be sorted in the same order. The following meta data entries are supported:url
- Mandatory entry that establishes the connection between the file content and its meta data. This must be set to the URI returned byupload(...)
.name
- Mandatory file name shown on the Novunex Platform for the uploaded file.category
- Optional categorization of the file. Either one of the predefined categoriesDocuments
,Images
,Spreadsheets
,Audio
andVideos
or a free text entry to define a custom category can be specified.description
- Optional free text describing the file.size
- Optional file size in bytes
The example below shows to implementation of a function to upload multiple files at once by using the
upload(...)
and theajax(...)
functions. This example interacts with the other code the following way:- The files are expected to be uploaded by an file selector HTML element. Hence, somewhere on the page in input element of type
file
is required, like<input type="file" id="myfile" name="myfile">
. Then, the example function can be called like
uploadAll( Array.from( document.getElementById('myfile').files ) );
- Similarly, once the files and the meta data are uploaded successfully, a map of the file names and the ID assigned by the Novunex Platform is composed. This map is then propagated to another function
uploadComplete( finishedFiles )
. Hence, this function needs to be implemented to handle the successful file upload.
function uploadAll( inputFiles ) { // Prepare the file content as multipart/form-data var uploadContent = new FormData(); inputFiles.forEach( function (file, index) { uploadContent.append('file-' + index, file, file.name); }); // Upload the file content aurora.upload({ type: 'post', url: aurora.apiUrl() + '/file/upload', data: uploadContent }) .fail( aurora.showApiError ) // When the file content has been uploaded successfully, the URIs are returned .done( function(uris) { // Compile the meta data of the files var uploadMetadata = { files: [] }; inputFiles.forEach( function (file, index) { uploadMetadata.files.push({ // Mandatory: Link the meta data to the file content via the URL/URI url: uris[index], // Mandatory: Set the name of the file on the Novunex Platform name: file.name, // Optional category category: 'Documents', // Optional description description: 'My file description string.', // Optional file size in bytes size: file.size }); }); // Upload the meta data aurora.ajax({ type: 'put', url: aurora.apiUrl() + '/file', data: JSON.stringify( uploadMetadata ) }) .fail( aurora.showApiError ) .done( function(fileIds) { const finishedFiles = new Map(); fileIds.forEach( function( fileId, index ) { finishedFiles.set( inputFiles[index].name, fileId ); }); // Inform the other components about the successful upload uploadComplete( finishedFiles ); }); }); }
- The file content is uploaded first by calling
JavaScript User Information
The user
objects offers information about the current User. This information can be accessed with aurora.user.propertyName
, where propertyName
can be one of the following properties:
id
- The ID of the current Userusername
- The user name of the current User, i.e., this is the email address of the UseraccessToken
- OAuth access token of the User currently active in this sessionrefreshToken
- OAuth refresh token of the current User needed to refresh theaccessToken
once it expiressubscriptionId
- The unique ID of the subscription the current User is logged inapiAccessKey
- The subscription key for thesubscriptionId
culture
- The culture setting of the current User, e.g.,en-US
,de-DE
,zh-CN
, etc.accountGuid
- The globally unique ID of the current Account
Samples
Here you find code samples that are often required for HTMLs:
- Load external JavaScript libraries - This examples loads JavaScript libraries that are not already provided by the Novunex Platform. All JavaScript libraries specified in the array
scripts
are loaded by this code. After executing this code in your HTML, you can use said JavaScript libraries.
$(function () {
// Define the libraries to be loaded
var scripts = [ "https://example.com/libs/mylib.js",
"https://domain.com/res/other.js" ];
function loadScript(scripts) {
// Iterate over all libraries
var url = scripts.shift();
$.getScript(url, function () {
// As long as there are libraries, load them
if (scripts.length > 0) {
loadScript(scripts);
// If there are no more libraries, call init() to use the libraries
} else {
init();
}
});
}
}