Building your first mashup with Qlik Sense Desktop or Qlik Sense Enterprise on Windows
This topic guides you through setting up a mashup using the Capability APIs. It assumes that you are using Qlik Sense Desktop or a Qlik Sense Enterprise on Windows server to host your mashup files. To follow along in this topic, you should ideally have access to the Helpdesk Management app that is provided with Qlik Sense Desktop; if you don't have access to this app, the steps outlined here can apply to any Qlik Sense app with the appropriate substitution of app ID and object IDs.
You can also simply host your mashup files outside of Qlik Sense entirely but be sure to add the origin to the whitelist of the virtual proxy in the QMC.
Creating the container
Create a folder named helpdesk to contain your assets:
C:\Users\<UserName>\Documents\helpdesk
Creating the QEXT file
The next step is to create a QEXT file in the folder you just created and name it helpdesk.qext.
It should look something like the following:
{
"type": "mashup",
"name": "helpdesk",
"description": "Basic responsive mashup template",
"version": "1.0.0",
"author": "",
"homepage": "",
"keywords": "qlik-sense, visualization, mashup",
"license": "",
"repository": "",
"dependencies": {
"qlik-sense": ">=3.0.x"
}
}
Anatomy of the QEXT file
name
Mandatory.
Defines the name of the mashup. Default is to use the file name.
type
Mandatory.
Should always be "mashup" for mashups.
description
Optional.
Description of the mashup. Default is to use the file name.
version
Optional.
Defines your individual version handling of the mashup. This setting is manually defined.
Creating the main script file
Then it is time to create the main JavaScript file. This is also placed in the same folder as the QEXT file and we name it helpdesk.js.
Configuring your Qlik Sense host
The Qlik Sense host being used must be configured in your mashup. This is needed for the following reasons:
- To define the actual Qlik associative engine connection, which is used when you open an app or get a list of apps. This is covered by the config JavaScript object, used as a parameter in the openApp call.
- To define where the Qlik Sense client side software and extensions should be loaded from. This is achieved by configuring RequireJS with the require.config call and setting the baseUrl.
In most cases, you use the same server for both purposes which means you can create the baseUrl from the config object. If the Qlik Sense server also is hosting the mashup, you can take the necessary parameters from the browser URL, as shown in the following example:
var config = {
host: window.location.hostname,
prefix: window.location.pathname.substr( 0, window.location.pathname.toLowerCase().lastIndexOf( "/extensions" ) + 1 ),
port: window.location.port,
isSecure: window.location.protocol === "https:"
};
require.config( {
baseUrl: ( config.isSecure ? "https://" : "http://" ) + config.host + (config.port ? ":" + config.port : "") + config.prefix + "resources"
} );
If the mashup is deployed to an external web server, this configuration needs to be modified:
- host should be set to your Qlik Sense host.
- prefix should be set to your virtual proxy, terminated by /, or just / if you do not use a virtual proxy.
- port should be set to the port that your Qlik Sense server is using.
- isSecure should be true if your server is using https (which is recommended), or false if using http.
Setting the global require and alert
The JavaScript file is loaded in the browser when your mashup is used. RequireJS is used as a module loader.
require( ["js/qlik"], function ( qlik ) {
qlik.on( "error", function ( error ) {
$( '#popupText' ).append( error.message + "<br>" );
$( '#popup' ).fadeIn( 1000 );
} );
$( "#closePopup" ).click( function () {
$( '#popup' ).hide();
} );
//open apps -- inserted here --
//get objects -- inserted here --
} );
Connecting to the Qlik Sense app
You need to connect to the Qlik Sense app containing the objects you want to display on your web page.
- For Qlik Sense Desktop:
//open apps -- inserted here -- var app = qlik.openApp( 'Helpdesk Management.qvf', config );
- For Qlik Sense Enterprise on Windows:
//open apps -- inserted here -- var app = qlik.openApp( 'AppId', config ); //Replace 'AppId' with the actual helpdesk app ID
Tip noteThe app ID can be retrieved by opening the app in the Hub. The app ID is displayed in the browser URL.
Retrieving the Qlik Sense objects to use
You then need to fetch the objects you want to display.
//get objects -- inserted here --
app.visualization.get('uETyGUP').then(function(vis){
vis.show("QV01");
} );
app.visualization.get('xfvKMP').then(function(vis){
vis.show("QV02");
} );
app.visualization.get('rJFbvG').then(function(vis){
vis.show("QV03");
} );
app.visualization.get('PAppmU').then(function(vis){
vis.show("QV04");
} );
app.visualization.get('ca4463f1-31fc-4eed-98a7-5e770b8387f3').then(function(vis){
vis.show("QV05");
} );
app.visualization.get('ff551649-420e-428d-bede-38accf80dce8').then(function(vis){
vis.show("QV06");
} );
Pre-selecting fields in the app
Making pre-selections in the app before rendering visualizations is a best practice. It allows the engine to do calculations once, which is quicker and puts less burden on the engine than making selections after the visualizations are rendered.
//function to pre-select fields
function getCaseOwner(callback) {
// call some backend functionality and call the “callback” function when ready
callback("Thomas R. Allman");
}
//call getCaseOwner with callback function
getCaseOwner(function(caseOwner) {
app.field("Case Owner").selectMatch(caseOwner)
.then(function() {
//get objects -- inserted here --
app.visualization.get('uETyGUP').then(function(vis){
vis.show("QV01");
} );
app.visualization.get('xfvKMP').then(function(vis){
vis.show("QV02");
} );
app.visualization.get('rJFbvG').then(function(vis){
vis.show("QV03");
} );
app.visualization.get('PAppmU').then(function(vis){
vis.show("QV04");
} );
app.visualization.get('ca4463f1-31fc-4eed-98a7-5e770b8387f3').then(function(vis){
vis.show("QV05");
} );
app.visualization.get('ff551649-420e-428d-bede-38accf80dce8').then(function(vis){
vis.show("QV06");
} );
})
})
Creating the main HTML file
Create an HTML file, name it helpdesk.html, and save in the same folder as the QEXT file.
Defining the relationships
The relationship between the current document and the linked Qlik Sense defined style sheet is specified in a link rel tag inside the head of the HTML file.
<link rel="stylesheet" href="../../resources/autogenerated/qlik-styles.css">
<script src="../../resources/assets/external/requirejs/require.js"></script>
<script src="helpdesk.js"></script>
Adding an internal style sheet
Add some internal styling inside the head of the HTML file to organize the presentation of the charts.
<style>
div.flex-container {
display: flex;
flex-wrap: wrap;
margin: 0 45px 45px 0;
}
div.qvobject {
flex: 1 1 auto;
height: 300px;
min-width: 400px;
margin: 45px 0 0 45px;
}
</style>
Placing the Qlik Sense objects
The Qlik Sense objects that have been defined in the JavaScript file are placed inside div tags inside the body of the HTML file.
<div class="flex-container">
<div id="QV01" class="qvobject"></div>
<div id="QV02" class="qvobject"></div>
<div id="QV03" class="qvobject"></div>
<div id="QV04" class="qvobject"></div>
<div id="QV05" class="qvobject"></div>
<div id="QV06" class="qvobject"></div>
</div>
Testing the mashup
Now is a good time to test your mashup. The URL to your mashup uses the following syntax:
http://<ComputerName>:Port/extensions/<MashupName>/<MashupName>.html
Testing the mashup with Qlik Sense Desktop
Do the following:
- Copy the mashup files to C:\Users\<UserName>\Documents\Qlik\Sense\Extensions\helpdesk
- Enter the following URL in a browser:
http://localhost:4848/extensions/helpdesk/helpdesk.html
Testing the mashup with Qlik Sense Enterprise on Windows
Do the following:
- Compress the folder that contains all your mashup files.
- Open the Qlik Management Console
- From the QMC start page, open Extensions.
- Click Import in the action bar.
- Click Choose File and navigate to C:\Users\<UserName>\Documents\helpdesk.zip.
- Select the compressed mashup folder to import and click Import.
The mashup is imported into Qlik Sense Enterprise and should now appear in the list of extensions.
- Enter the following URL in a browser:
https://QSE_domain/extensions/helpdesk/helpdesk.html
Port 443 is the default port for HTTPS so it is not necessary to specify it in the mashup URL.