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:

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:

1. Open Qlik Sense Desktop.
2. Open Dev Hub.

3. Create a new widget in the Widget editor.

   Add css-boilerplate as a dependency.

4. Reference the ccs-boilerplate custom component in the HTML code.

   <ccs-boilerplate></ccs-boilerplate>

5. Select an app to be able to see a preview of your widget containing the custom component. It should look like this: