Custom Component API
Getting started
Learn how to build custom components.
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.
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. |
Main script file
Custom components are basically AngularJS directives. The purpose of the JavaScript file is to return the signature of an AngularJS directive.
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
Use Qlik API Insights to see the version history for Qlik APIs and to compare API changes between versions.
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: