Working with Qlik Sense selections

Introduction

Qlik Sense allows users to make selections on field values in an app, which can be used to filter data in visualizations. You can use qlik-embed to manage selections in your Qlik Sense app.

A complete example is available at the end of this guide.

Prerequisites

To use the example page in this guide, ensure that you have the following:

An existing app ID and sheet ID to embed. This example uses this demo app that you can freely download and use.
A SPA OAuth2 client configured.

Variable substitution and vocabulary

Throughout this tutorial, variables will be used to communicate value placement. The variable substitution format is VARIABLE_NAME or <VARIABLE_NAME>. Here is a list of variables that appear in the sample code.

Variable	Description
`QLIK_TENANT_URL`	The domain for the tenant you are accessing. Equivalent to `tenant.region.qlikcloud.com`.
`QLIK_REDIRECT_URI`	The Redirect URL for the OAuth2 client to provide an access token.
`QLIK_OAUTH_CLIENT_ID`	The clientId of the OAuth SPA you configured.
`QLIK_APP_ID`	The unique identifier of the application.
`QLIK_SHEET_ID`	The unique identifier of the sheet.

This example loads these values from process.env, which you can set in a .env file and reference when running the example with node.js 20+ using node --env-file=.env server.js.

You must connect to the Qlik Sense app before manipulating fields or selection. You do this with the qix.openAppSession method.

import { auth, qix } from "https://cdn.jsdelivr.net/npm/@qlik/api/index.js";

// Retrieve settings from environment
const QLIK_TENANT_URL = process.env.QLIK_TENANT_URL;
const QLIK_OAUTH_CLIENT_ID = process.env.QLIK_OAUTH_CLIENT_ID;
const QLIK_APP_ID = process.env.QLIK_APP_ID;
const QLIK_REDIRECT_URI = process.env.QLIK_REDIRECT_URI;


// OAuth authentication settings
const hostConfig = {
    host: QLIK_TENANT_URL,
    authType: "oauth2",
    clientId: QLIK_OAUTH_CLIENT_ID,
    redirectUri: QLIK_REDIRECT_URI
};

auth.setDefaultHostConfig(hostConfig);

let app;

async function initQlik() {
    try {
        const session = await qix.openAppSession(QLIK_APP_ID);
        app = await session.getDoc();
    } catch (error) {
        console.error("Error initializing Qlik:", error);
    }
}

Examples of use

Learn what you can do with the Field and Selection APIs.

Select values in a field

Use the app.field.select method to select specific values in a field.

async function selectValue(value) {
    if (!app) {
        console.error("App is not initialized");
    }
    try {
        console.log("Select value " + value);
        const field = await app.getField("title");
        await field.select(`${value}`);
    } catch (error) {
        console.error("could not select values", error);
    }
}

Clear field selections

Use the app.field.clear method to clear a field selection.

async function removeSelections() {
    if (!app) {
        console.error("App is not initialized");
        return;
    }
    try {
        const field = await app.getField("title");
        await field.clear();
    } catch (error) {
        console.error("Error removing selections", error);
    }
}

Full code example

Below is an example built using qlik-api and qlik-embed web components.

Style sheet: web-component-field-selection.css

body,
html {
    margin: 0;
    padding: 0;
    font-family: sans-serif;
    font-size: 14px;
    background-color: #f5f5f5;
    color: #333;
    height: 100%;
    width: 100%;
}

div.flex-container {
    display: flex;
    flex-wrap: wrap;
    margin: 0 45px 45px 0;
    flex-direction: column;
    height: 50%;
}

.qvobject {
    flex: 1 1 auto;
    height: 300px;
    min-width: 400px;
    margin: 45px 0 0 45px;
}

.buttons-container {
    /*position: fixed;*/
    top: 10px;
    left: 10px;
    z-index: 1000;
}

button {
    margin-right: 10px;
}

div.list-container {
    flex: 1 1 auto;
    border: 1px solid;
    border-color: black;
    background-color: white;
    margin: 45px 0 0 45px;
    padding: 20px;
}

.viz {
    height: 600px;
    border: 1px solid #bbb;
    box-shadow: 1px 1px 10px rgba(0, 0, 0, 0.2);
}

JavaScript: web-component-field-selection.js

import { auth, qix } from "https://cdn.jsdelivr.net/npm/@qlik/api/index.js";

// Retrieve settings from environment
const QLIK_TENANT_URL = process.env.QLIK_TENANT_URL;
const QLIK_OAUTH_CLIENT_ID = process.env.QLIK_OAUTH_CLIENT_ID;
const QLIK_APP_ID = process.env.QLIK_APP_ID;
const QLIK_REDIRECT_URI = process.env.QLIK_REDIRECT_URI;


// OAuth authentication settings
const hostConfig = {
    host: QLIK_TENANT_URL,
    authType: "oauth2",
    clientId: QLIK_OAUTH_CLIENT_ID,
    redirectUri: QLIK_REDIRECT_URI
};

auth.setDefaultHostConfig(hostConfig);

let app;

async function initQlik() {
    try {
        const session = await qix.openAppSession(QLIK_APP_ID);
        app = await session.getDoc();
    } catch (error) {
        console.error("Error initializing Qlik:", error);
    }
}

async function getSelectedField() {
    if (!app) {
        console.error("App is not initialized");
    }
    document.getElementById("selectionsList").innerHTML = "";
    const selectionObj = await app.createSessionObject({
        qInfo: {
            qId: "CurrentSelections",
            qType: "CurrentSelections",
        },
        qSelectionObjectDef: {},
    });
    const layout = await selectionObj.getLayout();
    const selectedValues = layout.qSelectionObject.qSelections[0].qTextSearch;
    if (selectedValues) {
        var item = document.createElement("li");
        item.appendChild(document.createTextNode(selectedValues));
        document.getElementById("selectionsList").appendChild(item);
    }
}

async function selectValue(value) {
    if (!app) {
        console.error("App is not initialized");
    }
    try {
        console.log("Select value " + value);
        const field = await app.getField("title");
        await field.select(`${value}`);
    } catch (error) {
        console.error("could not select values", error);
    }
}

async function removeSelections() {
    if (!app) {
        console.error("App is not initialized");
        return;
    }
    try {
        const field = await app.getField("title");
        await field.clear();
    } catch (error) {
        console.error("Error removing selections", error);
    }
}

document.addEventListener("DOMContentLoaded", async () => {
    await initQlik();
    document.getElementById("SelectDimAvatar").addEventListener("click", () => {
        selectValue("Avatar");
    });
    document.getElementById("SelectDimTitanic").addEventListener("click", () => {
        selectValue("Titanic");
    });
    document.getElementById("SelectDimFrozen").addEventListener("click", () => {
        selectValue("Frozen");
    });
    document.getElementById("removeSelections").addEventListener("click", removeSelections);
    document.getElementById("selectionState").addEventListener("click", getSelectedField);
});

HTML: web-component-field-selection.html

<!doctype html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <link rel="stylesheet" href="web-component-field-selection.css" />
  <script src="https://cdn.jsdelivr.net/npm/@qlik/embed-web-components@1/dist/index.min.js"></script>
  <script type="module" src="web-component-field-selection.js"></script>
</head>

<body>
  <div class="buttons-container">
    <button id="SelectDimAvatar">Select Avatar</button>
    <button id="SelectDimTitanic">Select Titanic</button>
    <button id="SelectDimFrozen">Select Frozen</button>
    <button id="removeSelections">Remove Selections</button>
    <button id="selectionState">Selection state</button>
  </div>
  <div class="viz">
    <qlik-embed ui="analytics/chart" app-id="%QLIK_APP_ID%" object-id="%QLIK_SHEET_ID%" />
  </div>
  <div class="list-container">
    <h3>Selection state</h3>
    <ul id="selectionsList"></ul>
  </div>
</body>

</html>

Introduction
Prerequisites
Variable substitution and vocabulary
Examples of use
- Select values in a field
- Clear field selections
Full code example