Use Qlik in your own apps and sites
A new version of my Qlik Sense Extension Variable is now available.
No new functionality, but some minor internal changes:
This release is part of the preparation for the certification of the extension. Read more about that here. This extension is however still not certified.
Update 2020-06-27: Qlik sense has changed since I originally wrote this, up to date version of using a Promise can be found here:
One of the great new features in Qlik Sense is snapshots and storytelling. It allows you to create a snapshot of your visualizations, with the current selection state, and then include the snapshot in a story. Behind the scenes Qlik Sense also uses snapshot for export to PDF, PowerPoint and image. This makes it even more important for you to make your extension work well with snapshots. Sometimes this is however not easy…
To turn snapshots on, you need to include a few lines in your extension:
This will give you a context menu in the client with alternatives to create snapshot and export the visualization. That might be enough, but it might not be enough. To verify it you should:
You visualization is actually used in three contexts, that are somewhat different:
To make it actually work in all, you might need to do some more work.
One problem, mainly in export, is to let Qlik Sense know when your extension actually is ready with the rendering. You might get just an empty area in your powerpoint, or just the header but no content. This might be because the image is taken before your extension is ready.
The mechanism to fix this is a javascript concept called a Promise. Your paint method should return a Promise, that resolves when the rendering is ready. Qlik Sense will then wait until the Promise is resolved and then grab the image.
This is described where briefly in Qlik Sense help under ‘Set up “finished rendering” notification, like this:
This will return a Promise, that immediately resolves. This might not be good enough, since you might want to wait for something until you resolve. In my case, I used highcarts and highcharts has a callback function that will be called when rendering is ready. The final solution is like this:
So, I create a deferred object before calling the Highcharts rendering method. I can then return the promise that belongs to the deferred, but I do not resolve it until Highcharts tells me that rendering is complete, actually I had to add an additional delay of 1 second to make sure. There is currently no documentation of qlik.Promise in Qlik Sense help, but you can look in the angularjs documentation.
If it’s still not working, you should take a look at animations. Animations in analyse mode are good (if used the right way…) and might help the user discover insights in their data, but in export they should be turned off.
In Highcharts there are actually two flags you should turn off to diable animations. It might be enough to turn off just one of them, but why not both:
The isSnapshot flag which I use to determine if we are in analyse mode or in snapshot (story or export) is undocumented, so this solution might break in future Qlik Sense versions, but in September 2017 it works.
Sometimes in your extension you need to acces the QIX Engine API. You might need to make or clear selections, apply a bookmark or something else. Traditionally you would use the Capabilities APIs for this. You would load the qlik module, get hold of the app with the help of the currApp() method, and call whatever function you needed.
But there is another way. You could do it the way the built-in client does, and use enigmajs instead. Enigmajs creates a javascript wrapper around the QIX api, a wrapper that includes all methods defined in the version of QIX your system is using. Qlik actually has open-sourced enigmajs, you can read more, and download it from the Github repository.
Important features of enigmajs:
Unlike the Capabilities APIs, enigmajs does not come with a lot of dependencies on requirejs, angularjs and Qlik Sense client code. This makes it well suited for use in envorinments where you use other frameworks, like react or future frameworks we have not heard of yet. Of course if you’re using it inside an extension, you already have all of these dependencies, so that is not so important.
Note that Qlik flags enigmajs as experimental in the current release. I would be very surprised if it goes away any time soon, but details in the implementation might change, you need to be aware of that.
Qlik Sense creates a server side Generic Object for each instance of your extension (for all built-in charts too, actually). Around that Generic Object will be a javascript wrapper that exposes all the methods available. In the extension you can find it at:
this.backendApi.model.enigmaModel
It will expose all the methods defined in the Generic Object QIX engine API. As you can see, there are a lot of methods. It also has an app property, that exposes QIX Engine API app object. And the app has a global property, that is a wrapper around QIX Engine Global. This gives you access to the complete QIX Engine API.
I have converted my Variable extension for Qlik Sense to use enigmajs instead of the Capabilities API, as versions before 4.0 did. The key call of the extension is after the conversion like this:
function setVariableValue(ext, name, value) {return ext.backendApi.model.enigmaModel.app.getVariableByName(name).then(function (v) {return v.setStringValue(value);});}
If you need access to QIX Engine API from within your extension, enigmajs can help you with that. Unlike the Capabilities API it provides wrappers for all methods. But you should be aware that it only wraps engine api, not client-side functionality. It however works nicely within the client and invalidation and refresh of objects will work as expected.
One of the most popular new features in Qlik Sense is snapshots and storytelling. When you discover something interesting in your Qlik Sense app you can take a snapshot of a visualization, including its selections and data, and then build a story where you use it. And you can recreate the selections from the snapshot and drill deeper into your data or look at it from another angle.
In many cases this works automatically for your extension too, but sometimes it doesn’t. In recent versions of Qlik Sense new features, like printing and export to PDF are also built on the snapshot feature, which makes it even more important for it to work. So here is a description of how it works and what you need to do to make your extension work in snapshots.
You create a snapshot by clicking the camera icon in the visualization context menu. Qlik Sense will then make a copy of the data used for the rendering, known as the layout. This structure is then included in a new bookmark, that is created in Qix engine. Note that it’s not the HTML that is saved, nor is it a bitmap of the actual visualization on the screen. It’s the data.
So when the user wants to look at the snapshot, the data is loaded from the bookmark, Qlik Sense then checks what extension was used to visualize it, loads the extension, creates an object using the visualization, and calls the paint method of the visualization. But the layout parameter will not contain live data from the current selection state, it will contain data from the snapshot.
For snapshots to work your extension should use only the layout when rendering. You should not try to use the capabilities APIs to access data dynamically. Most likely it will not work, and if you manage to get it working, the data you get will be live and not reflect the state when the snapshot was taken. So make sure you add the data you need to the properties structure instead.
Also you need to keep the layout clean. It is good practice to treat it as read-only, adding nice-to-have references make make it impossible to serialize the layout, and creating the snapshot might fail.
And don’t forget to test creating snapshots from your extensions. Also verify that printing and exporting to PDF works, very likely your users expect them to.
I have just released a new version (3.1) of the Qlik Sense variable extension at GitHub and Qlik Branch. News in this relaese is that you can have dynamic values for your dropdown list and buttons. It is based on a contribution, but I refactored it somewhat to make it a bit more general and make buttons dynamic too.
It should be totally backward compatible with the previous release and upgrading should not cause you any problems.
A Qlik Sense Generic Object can also be used to list objects in the Qlik Sense app to which it belongs. You can use it to list things like:
The javascript APIs provide the app.getList method, which is a wrapper that helps you get theses lists. It will create a session object for you with the list you are requesting, get that actual data in the list and call your callback function once the data is available.
List are live – your callbacks might be called several times
Just like with other Generic Objects the data might be invalidated. If you are using the javascript APIs it will then be automatically revalidated and your callback function will be called again, so you should be prepared that your callback might be called multiple times. But unlike the Hypercube and List Object the lists are not affected by the users selections. Instead they will be invalidated when the underlying data changes:
Configure the data you get in your list
The data you get in your lists is configurable. If you use the API method, you will get a default set of fields for each item in the list, but you can set the list up to suite your needs.
As an example, if you use the api method getList(‘measure’, callback), you will get a list where records look like this:
The first and second part, qInfo and qMeta, will always be there. They contain the id to use when refering to this measure and title and description use ful in a list of measures. The third part however, qData, is configurable. The default configuration just gives you tags and title one more time, but if you instead want more data about the measure, you can use your own measure list definition like this:
Under qData you provide your own mapping of the properties you want. In this case I have just specified that I want everything under qMeasure included. You can also specify individual fields.
And get output that includes more data for the measures:
And the same goes for the other lists, you can supply your own definitions and get more data included.
Somtimes your extension does not work as expected. Here are some things you should do
The browser that is built in in desktop might cache your extension files, so it is not really suited for extension development. Also in a browser you have better tools for troubleshooting and debugging. I use Google Chrome, since I think the developer tools are pretty good, but other browsers also have developer tools.
The console shows you if something goes wrong in your javascript code, some files are not found etc, so this is in most cases the first place to look for errors.
When you are doing extension development the cache is your enemy: caching might mean that you are actually running an older version of your extension than you think. In Chrome you can turn it off in developer tools, in the network tab:
Note that the cache will only be disabled if you have developer tools open, so you should keep them open when developing.
Open your source code in the browsers developer tools:
Verify that this is the correct version.
The developer tools includes a very good debugger. Use it! Good places to set a breakpoint would be:
Note that you can also see the contents of structures like the layout and evaluate expressions used. And, of course step through your code.
Filenames of your qext file needs to be unique. If you are developing on Qlik Sense desktop it is your own responsibility to make sure that this is the case. If you make backup copies of your extension, do not save them under MyDocuments/Qlik/Sense/Extensions.
This post was originally published in Qlik Community: https://community.qlik.com/docs/DOC-8985
When you use the getObject. call of the Qlik Sense mashup API (also known as the Capabilities API or qlik.js) it works a bit like a black box: you just call it and it will inject some Qlik content into your page , you don’t have to bother about the content, it might be any type of chart, it might even be an extension. But it you want to, you can access the data of the visualization.
The key to this is the return value from getObject. The method returns, as it says in the documentation ‘a promise of an object model’. That means you can use the return value to get access to the data in the visualization, or even call some methods to modify the visualization automatically.
Only you have to understand:
Promise
The fact that getObject returns a Promise means that you will get an object with a then method. The then method will take a parameter, a function, that is called when getObject is ready, that is after a while, normally just some milliseconds, so to you it will look like immediately, but for the computer this is a long time.
What happens when you call getObject is:
Only after these two calls will the promise resolve, and the method you supplied as a parameter to the then method will be called. That means that at this stage the object you get will be a model with valid data.
The model
A good way to find out the contents of model is to use the debugger in your browser and inspect it. Some important parts of the model:
So, to sum this up, you can get the title of the visualization like this:
You find a full working example in the Github repository.
This post is based on a session I originally held at Qonnections 2015, under the title ‘5 things you did not know you can do with the Mashup API’.
One of the really powerful features of Qlik Sense API’s is the possibility to dynamically modify visualizations. You can build solutions that allows the user not only to make selections and have them reflected in all charts displayed (that’s the default, you will get that automatically if you don’t turn it off) but also to dynamically change chart properties and do things like
And all of this can be done for both built-in visualizations and extensions in the same way. The key to all of this is the applyPatches method and soft patches.
Soft patches
A soft patch is a temporary change to properties for a visualization. The fact that it is temporary means:
You make sure that its a soft patch by setting the second parameter in the applyPatches call to true. The first parameter is the list of patches you want to apply. Since you might want to apply several patches, it is an array, where each entry has three values:
Perhaps this is clearer if we look at an example:
What we do in this example is that we show a list of dimensions and measures to the user. When the user clicks on one of them, we move it to be the first one in the sort order, and use applyPatches to update the array and the chart will be resorted. Since it is all done with soft patches, it will not affect other users.
You find a full working example in the Github repository.
This post is based on a session I originally held at Qonnections 2015, under the title ‘5 things you did not know you can do with the Mashup API’.