Skip to main content

Creating a custom hello world component

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.

In this section you will learn some of the basic concepts of the Custom Component API as you create a custom component that writes "hello world".

Creating the container

Create a folder that will contain your assets. Create the folder in the following location: C:\Users\[UserName]\Documents\Qlik\Sense\Extensions\.

Example:  

C:\Users\[UserName]\Documents\Qlik\Sense\Extensions\ccs-hello-world

Creating the QEXT file

The next step is to create a QEXT file in the folder you just created and name it ccs-hello-world.qext.

Add the following to the file:

{
  "name": "ccs-hello-world",
  "description": "Boilerplate for a custom component.",
  "type": "component",
  "version": "1.0.0",
  "author": "Qlik",
  "dependencies":{}
}

Creating the main script file

Now create the main script file. also place this file in the same folder as the QEXT file and we name it ccs-hello-world.js. Paste the following code into the script file and then save it:

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

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

Testing the custom component

Now 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 ccs-hello-world as a dependency.

  4. Reference the ccs-hello-world custom component in the HTML code.

    <ccs-hello-world></ccs-hello-world>
  5. Select an app to be able to see a preview of your widget containing the custom component. It should look like this:

Let us review the basic concepts of this example:

  • As mentioned in the previous section, the signature of an AngularJS directive is returned in the custom component.
  • The componentName property defines the name of the component, using the camelCase concept.
  • The restrict property, with value E, declares that the component can be used like a native HTML element. Other options are available, read more about them in the AngularJS documentation.
  • The link function provides low-level access to manipulate the Document Object Model (DOM). It overrides access to the following objects:
    • scope: the AngularJS scope.
    • element: the jqLite-wrapped element that this directive matches.
    • attrs: a hash object with key-value pairs of normalized attribute names and their corresponding attribute values.
  • As the link function provides access to the element and therefore the html method, the HTML content of the custom component is manipulated with element.html('Hello world.');.

Customizing the message

In this section you will learn the basics of scope.message.

The scope is one of the core AngularJS concepts. The scope is the connecting piece between your HTML and your JavaScript-based component. The scope can be seen as a container of objects with properties and values. These objects are used for data-binding, that is bringing your pieces of HTML together with what you have defined in your component.

Example:  

Add an one-way attribute message to the scope of your component:

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

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

Define the message within a widget:

<ccs-hello-world message="My custom message."></ccs-hello-world>

Result:

Binding properties

Binding of scope properties is powerful but can be complicated. To simplify, think of the one-way binding as follows:

  • You define the properties in a widget.
  • You use the values of the properties in a custom component.
  • You want to prevent that property values are propagated outside the boundaries of a custom component, for example the entire client.

Example:  

In this section you will learn how to allow definition of the message within a widget. You will:

  • Define a property called message in the component.
  • Set the message property in the widget using the message attribute.
  • Use the property within the component using scope.message.

In the Widget editor, at the bottom of the properties panel builder, click @ to gedit. From the available components panel, add a new Header section to the Appearance accordion. The new header section is labeled Settings by default. From the Available components panel, add a new input field to the Settings section. Click V on the input field component. Change the label to Message and the reference to message.

Click Done when ready to close the dialog and then click m at the bottom of the properties panel builder to apply your changes and close the available components panel.

The next step is to bind the newly-created settings.message property to the css-hello-world component. Remove My custom message. in the following code:

<ccs-hello-world message="My custom message."></ccs-hello-world>

Click Insert and then select {{...}}. Select the message property from the list and click Insert with curly braces. You should now have the following code:

<ccs-hello-world message="{{settings.message}}"></ccs-hello-world>

Type something in the newly-added input field in the properties panel builder to test the new property. It should look something like this:

In the example above, you defined the message property in your component. You then set the property in the widget using the message attribute. Lastly, you used the property within the component using scope.message.