Introduction to Generic Object

    Behind all visualizations in Qlik Sense lies the Generic Object. This is a very powerful object which allows you to use Engine functionality. When you add your extension to an app, a Generic Object will be created for you, with the initial properties you have specified. This Generic Object will be persisted in the app and called up when the user opens the sheet it is on.

     

    Also when you are working with the Mashup API you create Generic Objects: the app calls createGenericObject, createList, createCube, getList and getAppObjectList will all create a Generic Object and set up a subscription so that your callback function will be called whenever data in the GenericObject changes. But Generic Object created with these Mashup API calls will not be persisted in the app and so will not be visible in the Qlik Sense client.

     

    Properties and Layout

    The GenericObject has properties, in a structure you define yourself. There are two kind of properties:

    • user defined. Qlik only persists those and include them as-is in the layout, it is up to your code to use them for something
    • defined by Qlik Engine. These are validated by the Engine, and replaced in Engine output, the layout, by the calculated counterparts. A qHyperCubeDef containing definitions for dimensions and measures is replaced by a qHyperCube containing the calculated values

    All properties defined by Engine start with a q, so it is good programming practice to let your own properties start with some other letter. The properties defined by Engine are documented here and the corresponding out data is documented here.

     

    For an extension you set up the properties in initialProperties. An example from PeopleChart:

    initialProperties : {
                version: 1.0,
                qHyperCubeDef : {
                    qDimensions : [],
                    qMeasures : [],
                    qInitialDataFetch : [{
                        qWidth : 2,
                        qHeight : 50
                    }]
                }
            }
    
    
    
    
    
    
    
    
    
    
    

    This will create a Hypercube at root level, which is the most common setup for extensions, so in your paint method you know where to find your data. It will also create a custom property called 'version'. Engine will only persist this, so when you create version 1.1 of your extension, you can check layout.version to detect of the actual visualization object was created with your version 1.0 and act accordingly.

     

    Using a qListObject

    In QlikView all extensions are based on one (and only one) hypercube. Qlik Sense is far more flexible. You can make an extension without properties and so without any Hypercube at all (the Hello World example has no properties) or you can use the other predefined properties, like qListObject, the object behind listboxes and the most suitable if you want to simple list all values form a field. The Horizontal listbox uses a qListObject and some user defined properties:

    initialProperties : {
                version : 1.0,
                qListObjectDef : {
                    qShowAlternatives : true,
                    qFrequencyMode : "V",
                    qSortCriterias : {
                        qSortByState : 1
                    },
                    qInitialDataFetch : [{
                        qWidth : 2,
                        qHeight : 50
                    }]
                },
                fixed: true,
                width: 25,
                percent: true,
                selectionMode: "CONFIRM"
    }
    
    
    
    
    
    
    
    
    
    
    

     

    Multiple HyperCubes

    It is also possible to have several Hypercubes in your properties. Just remember that you need to put them at different paths in your structure. An example:

    
    initialProperties : {
                qHyperCubeDef : {
                            qDimensions : [],
                            qMeasures : [],
                            qInitialDataFetch : [{
                                        qWidth : 10,
                                        qHeight : 50
                            }]
                  },
              second:{
                  qHyperCubeDef : {
                                    qDimensions : [],
                                    qMeasures : [],    ,    
                                    qInitialDataFetch : [{
                                            qWidth : 10,
                                            qHeight : 50
                                      }]
                  }
              }
    }
    
    
    
    
    
    
    
    
    
    

     

    Current Selections

    If you need to have access to the current selections in your extension you can add a qSelectionDef to your properties:

    initialProperties :{
         qSelectionObjectDef: {}
    
    
    
    

    This will give you data about the current selections in layout.qSelectionObject. Note that this also means that your extension will be notified, and your paint method called, every time selections change.

    Other options

    There are also other predefined properties you could use. If you want just an expression to be evaluated you can use qStringExpression or qValueExpression.

    version : {
              qStringExpression : "=QlikViewVersion ()"
            },
    fields : {
              qValueExpression : "=Count(DISTINCT $Field)"
    },
    user: {
              qStringExpression : "=OSUser()" 
    }
    
    
    
    
    
    
    

    This will give you the result of the calculations in fields in your layout, in this case in layout.version, layout.user and layout.fields.


     

    Mashups

    Mashups also use Generic Objects. But unlike extensions they are not persisted in the app. Instead the mashup API creates them as session objects, meaning that they will will be recreated every time you open the mashup and connect to an app.

     

    The createGenericObject method will create a generic object just as the framework does for an extension (except it's not persisted). The same things you can do in initialProperties in your extension can be made in the first definition parameter. The second parameter is a callback function that will be called whenever the data in your Generic Object changes, the same way the paint method will be called in an extension. It is important to realize that your callback function will not be called only once, but in most cases repeatedly.

     

    Other methods in the Mashup API (createCube, createList and getList ) are just wrappers around createGenericObject, to simplify your work. They work the same way, and the callback function might be called repeatedly.

     

    You will find more info on this in my blog: genericObject – Extending Qlik