Getting started building custom components
Custom components contains the following elements:
- A definition (QEXT) file.
- A main JavaScript file.
- Optional assets, such as JavaScript libraries, images, and fonts.
Creating the container
Create a folder that will contain your assets. The folder should be created in the following location: C:\Users\[UserName]\Documents\Qlik\Sense\Extensions\.
Example:
C:\Users\[UserName]\Documents\Qlik\Sense\Extensions\ccs-boilerplate
Creating the definition file
The definition file defines how custom components are loaded in Qlik Sense.
JSON validator: JSONLint
The following properties are mandatory for a valid custom component definition file:
Property | Description |
---|---|
name |
The name of the extension. A custom component is a type of extension. |
description |
Optional. 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 |
Optional. Author of the custom component. |
dependencies |
Optional. Defines the dependencies the custom component might have. |
Example:
Create a QEXT file in the folder we just created and name it ccs-boilerplate.qext.
It should contain the following information:
{
"name": "ccs-boilerplate",
"description": "Boilerplate for a custom component.",
"type": "component",
"version": "1.0.0",
"author": "Qlik",
"dependencies":{}
}
Creating the main script file
Custom components are basically AngularJS directives. The purpose of the JavaScript file is to return the signature of an AngularJS directive.
Example:
Create the main script file and place in the same folder as the QEXT file and then name it ccs-boilerplate.js. Paste the following code into the script file and then save it:
define( [], function () {
'use strict';
return {
componentName: "ccsBoilerplate",
restrict: 'E',
link: function ( scope, element, attrs ) {
element.html( 'OK, we have a custom component.' );
console.log( 'OK, we have a custom component.' );
}
};
} );
Naming conventions
It is best practice for the componentName property in the JavaScript file to match the name property in the QEXT file. You can however notice a difference in implementation In the ccs-boilerplate example above. This because AngularJS follow the camelCase principle:
- name property in the QEXT file: ccs-boilerplate
-
componentName property in the JavaScript file: ccsBoilerplate
componentName property was added in version 3.2.
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
Prefixing custom components
The ccs-boilerplate example above uses the prefix ccs (Custom Component Sample). Prefix your custom components to prevent conflicts with custom components created by other developers.
Testing the custom component
Now is a good time to test your custom component.
Do the following:
- Open Qlik Sense Desktop.
- Open Dev Hub.
-
Create a new widget in the Widget editor.
Add css-boilerplate as a dependency.
-
Reference the ccs-boilerplate custom component in the HTML code.
<ccs-boilerplate></ccs-boilerplate>
-
Select an app to be able to see a preview of your widget containing the custom component. It should look like this: