The Visualization API

    Up until Qlik Sense version 2.2 you have had two levels to work on when you want to use Qlik Sense data in your web page:

    • Take a visualization defined in the app and inject it into your web page using the getObject method
    • Programatically create a Generic Object and visualize the data yourself

    While these methods are both very useful, they have some limitations. The getObject method is very easy to use, and the mashup editor will help you to write your code and even let you drag-and-drop visualizations into your web page. But if you want to modify the charts you need to do that in the app itself. And the charts you create will be available in Sense client, which you might not want.

     

    Creating a Generic Object programatically is on the other hand very powerful and flexible, but you have to create visualization yourself (or use some third party package), you don't get any help with this.

     

    The visualization API gives you a third possibility. You get the flexibility of creating Generic Objects on-the-fly but you don't have to visualize the data yourself. Instead you can dynamically create visualizations and reuse the built-in charts or use an extension.

     

    The visualization API

     

    The API is another one of the Capability APIs, public JavaScript APIs to access Qlik Sense. Like most of the calls in the APIs you need to get an app object with the call openApp(appname, config). This is as before. But when you inspect the app object you will see that it has a new sub object, app.visualization. This is the new API.

     

    The API only defines two methods:

     

    1. app.visualization.get(visid). This is basically the same function as the getObject method, only you have to show the visualization yourself, with the new show method.
    2. app.visualization.create(type,cols,options). This is new!! This call allows you to dynamically define a chart in your JavaScript code, reuse the existing visualizations (built-in or extensions), supply the dimensions and measures and set other options for the chart.

    Both methods will give you a promise, that resolves with a QVisualization object. This object has a show method, that allows you to inject your new visualization into a HTML element.

    Create a chart dynamically

    So, to create a chart dynamically in your javascript code, you can now do like this:

    app.visualization.create('barchart',                       // we want a barchart
            ["Case Owner Group","=Avg([Case Duration Time])"], // one dimension, one measure
            {"title":"On the fly barchart"})                   // and we set the title
        .then(                                                 // it's asynchronous, so when its ready
            function(vis){
                vis.show("QV03");                              // show the chart in a HTML element with id "QV03"
            }
    );

    The app.visualization.create method takes the following parameters:

    • type  The visualization type. Could be built-in like barchart or piechart, or an extension
    • cols  An array with dimensions and measures to use. More on that later.
    • options Optionally a javascript object with other options to set

     

    Define dimensions and measures

     

    The second parameter in the visualization.create call is an array of dimensions and measures. In the example above I have used strings, which is the easiest way to define dimensions and measures:

     

        ["Case Owner Group","=Avg([Case Duration Time])"], // one dimension, one measure

    The API will know that it is a measure by looking at the first character. If it is an equals sign ('=') it will be treated as a measure.

     

    Setting more properties on dimensions and measures

    But Qlik Sense allows you to do much more than just set dimensions and measures. The visualization API allows you to set the full range of properties on dimensions and measures. To do this you replace the string with a JavaScript object instead. This object is a NxDimension or a NxMeasure, as documented in the Engine API.  For example if you want to set labels you could do like this:

    app.visualization.create( 'pivot-table',
        [
            "Year",
            {"qDef" : { "qFieldDefs" : ["Case Owner Group"], "qFieldLabels" : ["Group"] }},
            {"qDef" : { "qDef" : "=Avg([Case Duration Time])", "qLabel" : "Avg Case Duration Time" }},
            {"qDef" : { "qDef" : "Sum( [Open Cases] )", "qLabel" : "Open Cases" }}
        ],
        {"title" : "Case Owner Group Case stats per year"}
    ).then( function ( visual ) {
        visual.show( 'QV01' );
    } );

     

    Or if you want to use Qlik Sense function to show only the top values and add a 'others' group for the rest you set the qOtherTotalSpec property:

     

    app.visualization.create( 'barchart',
        [{

            qDef: {qFieldDefs: ["Case Owner Group"]},
      qOtherTotalSpec: {qOtherMode: "OTHER_COUNTED", qOtherCounted: "5"}   
      },
      "=Avg([Case Duration Time])"],
      {"title": "On the fly chart"}
    ).then( function ( barchart ) {
      barchart.show( 'QV01' );
    } );

     

    Note that you can combine string and object syntax and use the string syntax for some dimensions and measures and the object syntax for others.

     

    Using predefined Dimensions and Measure

    You can also use the predefined Dimensions and Measures in the app, available for the user in the assets panel. This is useful if you want to allow the user to select dimensions and measures from a list. To do this you need the id for the dimension or measure, and include that as qLibraryId. You also need to provide qType (‘measure’ or ‘dimension’) to tell whether you want a dimension or measure. An example:

    app.visualization.create( 'gauge',
        [{qLibraryId: "eqZjE",qType:"measure"}]

    ).then( function ( gauge) {
      gauge.show( 'QV05' );
    } );

     

     

     

    More information

     

    You find more information on the Visualization API in Qlik Sense Developer help for version 2.2, here. There is also documentation for properties for the built-in visualizations and lots of examples.

     

    A previous version of this document was published at Qlik Branch.