Getting started building custom components

Tip: The easiest way to get started building your custom components is to use Qlik Sense Desktop. This section assumes that Qlik Sense Desktop is being used.

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.

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 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.

Tip: Add additional properties to the QEXT file as it can provide helpful information about the custom component.

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.

Note: The name of the main script file must match the name of the QEXT file.

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.' );
        }
    };
} );
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. 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).

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:

Did this information help you?

Thanks for letting us know. Is there anything you'd like to tell us about this topic?

Can you tell us why it did not help you and how we can improve it?