Skip to main content

Custom Component API

ON THIS PAGE

Custom Component API

Getting started

Learn how to build custom components.

Note: This functionality is not available in SaaS editions of Qlik Sense and Qlik Sense Enterprise on Kubernetes.

Getting started building custom components

Overview

Custom components contains the following elements:

  • A definition (QEXT) file.
  • A main JavaScript file.
  • Optional assets, such as JavaScript libraries, images, and fonts.

Definition file

The definition file defines how custom components are loaded in Qlik Sense.

Note: The QEXT file extension must be in lower case letters, as in ccs-boilerplate.qext.
Tip: Make sure your file meets the requirements of a valid JSON file when creating your QEXT file.

JSON validator: http://jsonlint.com

The following properties are mandatory for a valid custom component definition file:

Property Description
name The name of the custom component.
description Provides a meaningful description of your custom component.
type Extension type. Should always be component for custom components.
version Version of your custom component. Uses the semantic version concept.
author Author of the custom component.
Tip: Add additional properties to the QEXT file as it can provide helpful information about the custom component.

Main script file

Custom components are basically AngularJS directives. The purpose of the JavaScript file is to return the signature of an AngularJS directive.

Warning: You can, but you should not, register directives with qvangular.directive(...). The custom components concept may extend beyond AngularJS directives in the future.

Naming conventions

It is best practice for the componentName property in the JavaScript file to match the name property in the QEXT file. Because AngularJS follow the camelCase principle, there is a difference in implementation between the definition file and the script file:

Example:  

  • name property in the QEXT file: ccs-boilerplate
  • componentName property in the JavaScript file: ccsBoilerplate

Angular normalizes an element's tag and attribute name to determine which elements match which directives. Directives are typically referred to by their case-sensitive camelCase normalized name (for example ngModel). However, since HTML is case-insensitive, directives in the DOM are referred to by lower-case forms, typically using dash-delimited attributes on DOM elements (for example ng-model).

AngularJS documentation: Creating Custom Directives

Version history

Note:

Use Qlik API Insights to see the version history for Qlik APIs and to compare API changes between versions.

Qlik API Insights

Warning: DEPRECATED.

API Insights is deprecated and may be removed in a future release. See API change log instead.

The custom components feature was introduced as BETA in version 3.1.

Using Qlik Sense APIs in custom components

The following JavaScript libraries can be used in custom components:

  • Extension API
  • Backend API
  • Root API
  • App API
  • Bookmark API
  • Field API
  • Global API
  • Table API
  • Navigation API
  • Selection API
  • Variable API

Examples of use

Learn how to use the Custom Component API in your widgets.

Definition file

The properties used in the example below are mandatory for a valid custom component definition file.

ccs-hello-world.qext 

{
  "name": "ccs-hello-world",
  "description": "Hello world component for widgets",
  "type": "component",
  "version": "0.1.0",
  "author": "Qlik"
}

Main script file

The main script file should be placed in the same folder as the QEXT file. Note how the componentName property is using the camelCase concept in the script file.

ccs-hello-world.js 

define( [], function () {
    'use strict';

    return {
        componentName: "ccsHelloWorld",
        restrict: 'E',
        link: function ( scope, element, attrs ) {
            element.html( 'Hello world.' );
        }
    };
} );

Widget implementation

Custom components are declared in the Widget editor.

<ccs-hello-world></ccs-hello-world>

Result: