Getting started building widgets

Introduction

Widgets are simple app objects created using HTML and CSS. You create and edit widgets in the Widget editor and store them in widget libraries, which are then available from the assets panel in your apps.

Widgets are similar to visualization extensions, but widgets do not require JavaScript programming. This means you cannot create objects that require advanced calculations, or which use external libraries or files. Widgets are best suited for creating simple visualizations, such as KPI objects and tables. Widgets can also be used to add simple functionality to sheets, such as buttons to clear selections or take snapshots, or to add other visual elements.

Widget libraries

Widgets must belong to a widget library. There is a example widget library that comes with the Qlik Sense installation, which contain some standard widget templates.

You can organize widget libraries to suit your needs. For example, you can create your own widget library that contains all your personal widgets, or you can organize widgets by creating several widget libraries that contain widgets based on widget type, for example.

Widget libraries can be created from the Dev Hub start page.

Do the following:

  1. In the Widget libraries section of the Dev Hub start page, click P Create new widget library.
  2. In the Create new widget library dialog, fill in the details to identify your widget library:

    • Enter a name for the widget library.
    • If you wish, add a text description for the widget library.
  3. Click Create.

Widgets

Widgets are similar to visualization extensions, but widgets do not require JavaScript programming. Widgets are best suited for creating simple visualizations, such as KPI objects and tables. Widgets can also be used to add simple functionality to sheets, such as buttons to clear selections or take snapshots, or to add other visual elements.

If they are developed properly, you can handle widgets just like standard visualizations. They can be:

  • Added to a sheet using drag and drop.
  • Configured to use the same property panel as standard Qlik Sense visualizations, meaning that you can create widgets on top of the data of a Qlik Sense app.
  • Resized, copied, pasted, and positioned just like any other Qlik Sense visualization.
  • Added to and used in data storytelling.
  • Responsive and, therefore, work properly on any device.

Widgets can be created from the Dev Hub start page.

Do the following:

  1. In Dev Hub, click P, then select Create new widget.
  2. In the Create new widget dialog, fill in the details to identify your widget library:

    • Enter a name for the widget.
    • A widget must belong to a widget library. Select the appropriate widget library. If there are no existing widget libraries, you must create one.

      Widget libraries.

    • If applicable, designate a type. Other will be used if no type is defined.
    • If you intend to use a custom component in your widget, select the custom component from the list of available components. You can add a custom component dependency at a later stage, from the Settings dialog.

      Note: Referencing a custom component that is not listed as a dependency will not render the component as expected.
    • If you wish, add a text description and author for the widget.
  3. Click Create.

Uniqueness

When a widget is created in the Widget editor, an unique ID, a so-called Global Unique Identifier, is created. This unique ID will be kept regardless if you move or export the widget. It is also used to check for duplicate widgets when widget libraries are imported.

Warning: Although widget libraries can be imported from both QMC and Dev Hub, the uniqueness check of a widget is only performed when importing from Dev Hub. Therefore, it is strongly recommended to import all widget libraries from Dev Hub.

Best practices

A widget should be:

  • Generic
  • Responsive
  • Declarative only

Generic widgets

Do not hard-code values within widgets. Instead, define properties in the properties panel builder and bind to data.

Test your widgets using different Qlik Sense apps. They should work independently of the data model.

Responsive widgets

Test the responsiveness in the Widget editor by changing the preview size. Use the resize gripper in the Preview panel to test different object sizes.

Declarative widgets

Use only HTML and CSS/LESS in your widgets. If you must use JavaScript code to create your custom visualization object, build a visualization extension instead.

Example widgets

Qlik Sense comes with a example widget library, widget-examples, that contains a set of widgets. These are ready to use with little or no customization.

You can find the example widgets here:

  • Qlik Sense Desktop: ...\Users\<UserName>\Documents\Qlik\Examples\Extensions
  • Qlik Sense: ...\ProgramData\Qlik\Examples\Extensions

Using the examples

If you want to see or use the example widgets in Dev Hub you must first deploy them.

Do the following:

  1. In a Qlik Sense (server) environment: navigate to ...\ProgramData\Qlik\Examples\Extensions.

    In a Qlik Sense Desktop environment: navigate to ...\Users\<UserName>\Documents\Qlik\Examples\Extensions.

  2. Create a zipped file of the entire widget-examples folder .
  3. On the Dev Hub start page, click ú and select Import widget library.

  4. Locate the compressed file containing the widget library to import and then click Open.

    The widget library is being imported. The widget library was successfully imported is displayed when completed.

    The imported widget library can now be accessed from Dev Hub.

Widget example library

Dev Hub: Widget editor

The Widget editor is used to create and edit widgets. The graphical design of a widget is created in the Widget editor's HTML and CSS editors. These are not dependent on being associated with any app.

If you want to see a preview of the widget you are working on, you must associate it with an app. And if you want your widget to do calculations you must bind data using the Properties panel builder. If you want to see a preview of a widget bound to data, you must add the dimensions and measures it requires.

HTML editor

Enter and edit HTML used in the widget you are editing. The HTML editor contains a tool for inserting ready-made icons, code snippets, and references to widget component properties.

CSS editor

Enter and edit CSS rules used in the widget you are editing.

UI Components

Qlik Sense comes with a set of UI components that you can use in your widgets. These components can be accessed from the Insert option in the HTML editor.

Supported leonardo-ui components.

Preview

The preview panel is used to show a preview of the widget as it would be seen when added to an app. If you want to see a preview of the widget you are working on, you must associate it with an app. The widget uses the data from the app to display the preview. If you have not associated it with an app, the Preview panel will state that a preview is only available when you select an app. If an app is selected and the preview displays Incomplete visualization, you must complete the visualization by adding the dimensions and measures it requires.

Properties panel builder

The properties panel builder is used to add components to a widget. The components are then used for binding data with properties. You can also create your own components using the available items, such as Header, Input field, Checkbox, and Dropdown list.

Binding data with properties

Qlik Sense and widgets use the concept of AngularJS. To understand how data binding in widgets work, you must also understand the basics of data binding in AngularJS.

All data (dimensions and measures) and all properties are stored and exposed in the scope of your widget. You can use the entire scope and bind data to make widgets dynamic.

Qlik Sense automatically updates the scope when, for example, a selection is made while AngularJS, depending on your underlying scope, updates the UI.

Properties defined for a widget are stored in a JSON structure.

Binding data to widgets

Using your widgets in apps

If you have created your widgets and widget libraries in a Qlik Sense Desktop environment, they are immediately available to use inside the same Qlik Sense Desktop environment.

If you have created widgets and widget libraries in a development or test environment and want to make them available in a Qlik Sense production environment, the widget library needs to be imported to this environment.

Widget libraries are accessed in Qlik Sense and Qlik Sense Desktop from the custom objects section of the assets panel in your apps.

Note: Updating a widget in the Widget editor in Qlik Sense Desktop or in a Qlik Sense production environment causes it to be updated immediately in any app in which it is used.

Exporting and importing widget libraries

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?