qExt v2.0 Tutorial

qExt — это инструмент, помогающий автоматизировать создание и развертывание расширений визуализации Qlik Sense. Он может настроить вас на стандартные среды разработки расширений и более простой метод импорта скомпилированного кода на ваш сервер Qlik, чтобы вам не приходилось каждый раз вручную удалять и импортировать расширение.

Посмотреть проект на GitHub

Qlik Sense Extensions – Расширения Qlik Sense

Анатомия Qlik Extension

Расширения Qlik Sense позволяют создавать собственные объекты визуализации и функциональные объекты в приложении Qlik Sense. Расширения обычно используются для расширения возможностей визуализации Qlik для пользователей, использующих приложения Qlik в режиме самообслуживания. Дополнительные сведения об объектах расширения qlik sense можно найти на сайте Qlik здесь .

все файлы расширения должны храниться в одной папке проекта и, как минимум, должны включать файл qext и основной файл сценария.

файл qext

файл qext в проекте расширения содержит объект json, который определяет метаданные объекта расширения. Имя файла — это уникальное имя, которое Qlik будет использовать для идентификации расширения, и оно должно совпадать с именем файла сценария.

как минимум, файл qext должен включать свойства имени и типа. (полные свойства qext можно найти здесь )

пример файла qext:

// hello-world.qext
{
    "name": "Hello World",
    "description": "Hello world example",
    "type": "visualization",
    "version": "1.0.0",
    "author": "john bellizzi"
}

Script File

файл сценария в проекте расширения — это файл javascript, содержащий всю логику работы вашего расширения. он определяет, как данные поступают в объект, что отображается в объекте, свойства, которые можно установить для объекта, и многое другое. имя файла должно соответствовать вашему файлу qext

существует множество параметров конфигурации файла скрипта, и большинство из них можно найти в руководстве здесь . базовый сценарий использует функцию определения для загрузки любых необходимых ресурсов и возвращает объект javascript, содержащий функции, которые контролируют данные, проходящие через расширение.

наиболее распространенным методом, используемым в расширении, является paintметод, который запускается каждый раз, когда происходит изменение состояния приложения или изменение размера, чтобы мы могли отображать обновления в контейнере объекта расширения. 

Вот пример файла скрипта

define(["jquery"], function($) {
    return {
        paint: function($element, layout) {
            var $helloWorld = $(document.createElement("div"))
            $helloWorld.html('Hello World from the extension "SimpleHelloWorld"<br/>')
            $element.append($helloWorld)

            // layout contains the properties and calculated data of our object
            console.log(layout)
        },
    }
})

Deployment (Развертывание)

при развертывании расширения на сервере qlik правильным методом является сжатие всего каталога расширения в zip-файл, а затем переход к разделу расширений qmc и импорт заархивированного файла расширения. если расширение с таким именем уже развернуто, его необходимо предварительно удалить с сервера с помощью кнопки удаления в разделе расширений qmc

в qlik sense desktop проект расширения просто необходимо поместить в папку C:\Users\[UserName]\Documents\Qlik\Sense\Extensions\. любые изменения в файлах расширения будут отражены в расширении при перезагрузке страницы приложения.

ознакомьтесь со следующим разделом , чтобы узнать, как qExt помогает в настройке этих проектов и автоматизации развертывания.

Для чего нужно qExt?

Библиотека qExt была создана по трем основным причинам.

1. обеспечить лучшую поддержку для компиляции javascript следующего поколения
2. упростить процесс развертывания расширений в средах qlik sense
3. сделать инициализацию новых проектов расширений более воспроизводимой с помощью стандартных шаблонов кода

JavaScript следующего поколения

скрипт, который вы видели на предыдущей странице (и javascript, который вы увидите во многих расширениях qlik), написан на ванильном javascript, который обычно можно использовать в большинстве современных веб-браузеров. это отличное начало для многих, кто начинает знакомиться с javascript, но многие разработчики хотят использовать более новые версии и возможности javascript, включая импорт модулей, функции стрелок и многое другое.

существует множество инструментов, помогающих преобразовывать новый код javascript в обратно совместимые форматы. qExt использует babel в координации с webpack для компиляции всего кода в формат, который может использоваться современными браузерами.

Оптимизация развертывания

в последнем разделе упоминался процесс развертывания расширений в наших средах qlik. если вы выполняете серьезную работу по разработке проекта, ручное решение по удалению и повторному импорту кода проекта каждый раз, когда вносятся изменения, вероятно, не подходит. именно поэтому мы встроили интеграцию развертывания в qExt. инструмент может установить прямое соединение с вашим сервером qlik и автоматически удалить старое расширение и развернуть обновленное за считанные секунды с помощью API qrs

Шаблоны

в примере кода с предыдущей страницы использовался только один из многих методов, доступных в расширениях qlik. обычно при разработке расширений мы используем другие объекты и методы, такие как initialProperties, шаблон, контроллер и другие, чтобы полностью использовать настройки наших расширений. мы обнаружили, что многие из них довольно часто используются в проектах, и вместо того, чтобы переопределять их каждый раз, когда мы создаем новое расширение, мы определили их в шаблонных проектах, которые можно использовать для создания новых проектов расширений из

Введение в qExt Packages (Пакеты qExt)

библиотека qExt на самом деле состоит из двух разных пакетов, которые помогают нам в разработке расширений.

1. qext-scripts — инструмент, который запускается в нашей среде разработки расширений для компиляции кода и развертывания его в средах qlik sense.
2. qext — инструмент cli, который позволяет нам создать новый проект расширения с определенным шаблоном.

qext-скрипты

если мы оглянемся назад на 3 проблемы, которые qExt решает в разделе почему qExt , qext-скрипты в основном помогают нам решить первые 2 проблемы. он поддерживает разработку javascript следующего поколения, компилируя наш код в обратно совместимый формат, и упрощает процесс развертывания, автоматически архивируя скомпилированный код и отправляя его в среды, которые нам нужно обновить.

если у вас уже настроена среда разработки расширений, вы можете легко включить в нее qext-скрипты, установив ее из npm в свой проект расширения.

$ npm install --save-dev qext-scripts

qext

библиотека qext помогает нам решить третью проблему, которую мы задали в вопросе, почему именно qExt, реализуя шаблоны шаблонного кода. это в первую очередь интерфейс командной строки, который мы можем запускать глобально для создания проекта с указанным шаблоном каталога. он также автоматически установит зависимость qext-scripts

qext лучше всего устанавливать глобально, чтобы проекты можно было настраивать, откуда бы вы его ни вызывали.

$ npm install -g qext

 

Использование

Быстрый старт

прочитайте это, чтобы быстро установить инструменты qext и настроить новый проект

Установить QExt

установить основной инструмент qext глобально

npm install -g qext

Создать новое расширение

откройте окно терминала, в котором вы хотите разместить свой проект, и используйте инструмент qext cli для создания и установки нового проекта расширения.

qext --create-extension my-extension --install
cd my-extension

по умолчанию qext установит starterшаблон проекта. другие шаблоны могут быть переданы через флаг шаблона. доступные шаблоны можно найти здесь

Build extension (сборка экстеншена)

обновите исходные файлы расширения по мере необходимости, затем запустите

npm run build

проект расширения будет скомпилирован и заархивирован в выходной каталог

Просмотр экстеншена

запустите команду qext watch

npm run watch

любые изменения, которые вы делаете и сохраняете в своих исходных файлах, будут автоматически перестроены в ваш выходной каталог.

Deploy extension

добавьте следующую конфигурацию развертывания в файл qext.config.json

{
    ...,
    "serverDeploy": {
        "host": "hostname",
        "isSecure": true,
        "windowsAuth": true
    }
}

затем запустите

npm run deploy

окно терминала запросит ваши учетные данные. предоставить учетные данные для пользователя с доступом на запись к расширениям qlik sense, и новое расширение будет развернуто на сервере

конфигурация serverDeploy может потребовать другие параметры в зависимости от конфигурации сервера. проверьте qExt config для полных настроек конфигурации

в качестве альтернативы вы можете аутентифицироваться с использованием аутентификации заголовка. проверить использование раздела аутентификации заголовка для получения дополнительной информации

Templates (Шаблоны)

Шаблоны позволяют вам устанавливать предварительно определенные каталоги проектов и настройки при использовании инструмента qext cli. имя используемого шаблона может быть передано через -t, --template [type]флаг. ниже приведены шаблоны, которые вы можете выбрать

• vanilla-base — самый простой проект, настроенный для проектов, которые будут написаны с использованием vanilla javascript.
• base — базовый каталог проекта, который устанавливает минимальные исходные файлы, которые будут скомпилированы с использованием webpack и babel.
• starter — начальный шаблон, включая общие методы расширения и файлы конфигурации

Vanilla base

базовый шаблон vanilla — это самый простой шаблон, с которого вы можете начать, используя qExt.

Каталог проекта

├── src
│ ├── qext-template.qext
│ ├── qext-template.js
├── static
├── package.json
├── qext.config.json

каталог src

исходный каталог имеет 2 исходных файла qext-template.qextи qext-template.js. эти файлы следует переименовать в имя расширения, поскольку оно должно храниться в Qlik Sense (имя, которое вы видите при просмотре расширений в QMC).

qext.config.json

{
    "extension": "qext-template",
    "output": "./dist",
    "vanilla": {
        "entry": "./src",
        "static": "./static"
    }
}

файл конфигурации qext настроен с именем расширения, установленным на qext-template, и для сборки в ванильном режиме. когда проект построен, файлы будут скопированы из исходного кода в выходной каталог как есть

Base

базовый шаблон — это базовый шаблон, используемый для компиляции исходного кода расширения с помощью babel и webpack.

Каталог проекта

├── src
│ ├── index.qext
│ ├── index.js
├── static
├── package.json
├── qext.config.json

каталог src

исходный каталог имеет 2 исходных файла, index.qextиindex.js

qext.config.json

{
    "extension": "qext-template",
    "output": "./dist",
    "compile": {
        "entry": "./src/index.js",
        "qext": "./src/index.qext",
        "static": "./static"
    }
}

файл конфигурации qext настроен с именем расширения, установленным на qext-template, и для сборки в режиме компиляции. когда проект будет построен, webpack скомпилирует файлы через файл compile.entry и поместит скомпилированные файлы в выходной каталог. он также скопирует файл qext в выходной каталог

Starter

начальный шаблон устанавливает каталог вашего проекта с часто используемыми методами расширения

Каталог проекта

├── src
│ ├── index.qext
│ ├── index.js
│ ├── style.css
│ ├── methods
│ │ ├── controller.js
│ │ ├── definition.js
│ │ ├── index.js
│ │ ├── initial-properties.js
│ │ ├── paint.js
│ │ ├── resize.js
│ │ ├── template.html
├── static
├── package.json
├── qext.config.json

qext.config.json

{
    "extension": "qext-template",
    "output": "./dist",
    "compile": {
        "entry": "./src/index.js",
        "qext": "./src/index.qext",
        "static": "./static"
    }
}

файл конфигурации qext настроен с именем расширения, установленным на qext-template, и для сборки в режиме компиляции. когда проект будет построен, webpack скомпилирует файлы через файл compile.entry и поместит скомпилированные файлы в выходной каталог. он также скопирует файл qext в выходной каталог

src/index.qext

{
    "type": "visualization",
    "name": "qExt Template"
}

это метаданные расширения. свойство name должно быть обновлено до имени, которое видит конечный пользователь на панели объектов расширения приложения qlik. файл будет переименован в extensionзначение свойства вqext.config.json

src/index.js

import { initialProperties, template, definition, controller, paint, resize } from "./methods"
import "./style.css"

window.define([], function() {
    return {
        initialProperties,
        template,
        definition,
        controller,
        paint,
        resize,
    }
})

src/style.css

это файл css, используемый для определения любых стилей для нашего объекта расширения. обратите внимание, что все классы должны быть предварительно выбраны с именем класса объекта расширения, которое будет в формате-qv-объект. например, если вы хотите установить цвет фона элемента с классом containerв вашем объекте расширения, а имя вашего расширения — my-extension, ваш css должен выглядеть так:

.my-extension-qv-object .container {
    background-color: lightblue;
}

src/methods/initial-properties.js

export default {
    qHyperCubeDef: {
        qDimensions: [],
        qMeasures: [],
        qInitialDataFetch: [],
    },
}

Initial-properties определяет определение свойств объекта при его первом создании пользователем qlik sense. шаблон устанавливает свойства с помощью HyperCubeDef, но это можно изменить на другие определения qlik, такие как ListObjectDef, или пользовательские свойства

src/methods/definition.js

export default {
    type: "items",
    component: "accordion",
    items: {
        settings: {
            uses: "settings",
        },
    },
}

объект определения определяет конфигурацию панели свойств расширения. это основной способ, с помощью которого пользователь, добавляющий расширение на лист qlik, может настраивать и изменять параметры расширения, включая измерения, показатели, цвета и т. д.

больше о том, как настроить объект определения, можно найти здесь

src/methods/paint.js

export default function($element, layout) {
    // ..paint code here
}

функция рисования запускается каждый раз, когда происходит обновление макета нашего объекта расширения. это может быть вызвано изменением состояния выбора приложения qlik sense, а также изменением размера окна. это позволяет «перекрашивать» наше расширение при изменении, чтобы отображаемый вывод отображал самую последнюю версию данных, передаваемых в расширение. $elementсодержит ссылку элемента dom на объект расширения, который можно использовать для управления тем, что отображается в dom расширения, а layout содержит рассчитанный макет объекта расширения, включая любые выходные данные гиперкуба и настройки свойств.

src/methods/resize.js

export default function($element, layout) {
    // ..resize code here
}

методы изменения размера дают нам более точный контроль над тем, как наше расширение перерисовывается во время различных типов обновлений. в случаях, когда обновления, необходимые для изменения выбора и изменения размера, отличаются, мы можем разделить изменение размера на функцию метода изменения размера. важно отметить, что если возвращается метод изменения размера, в нашем src/index.jsфайле краска не будет запускаться при изменении размера окна.

src/methods/template.html

<div class="chart-container">qExt Template</div>

файл шаблона определяет исходный html, который отображается в нашем расширении. этот html можно увидеть в $elementdom, который передается функциям рисования и изменения размера.

src/methods/controller.js

export default [
    "$scope",
    "$element",
    function($scope, $element) {
        // ..controller code here
    },
]

функция контроллера запускается при инициализации расширения. это может быть полезно для настройки начальной конфигурации и потоков для расширения, когда оно инициализируется на экране.

src/methods/index.js

export { default as initialProperties } from "./initial-properties"
export { default as template } from "./template.html"
export { default as definition } from "./definition"
export { default as controller } from "./controller"
export { default as paint } from "./paint"
export { default as resize } from "./resize"

этот файл экспортирует все модули из methodsкаталога

Configuration

CLI Flags (Флаги командной строки)

Flag	Description	Required	Default
-c, --create-extension <name>	name of extension	Yes	N/A
-t, --template [type]	name template	No	starter
-i, --install	if provided, will install qext-scripts	No	N/A

qext Config

property	description	type	required
extension	name of extension object	string	yes
output	directory where output files will be placed	string	yes
vanilla	configuration of vanilla settings in running in vanilla mode	vanilla	yes if compile not defined
compile	configuration of compile settings in running in compile mode	compile	yes if vanilla not defined
serverDeploy	configuration of server deployment settings if deploying to server	serverDeploy	no
desktopDeploy	configuration of desktop deployment settings if deploying to desktop environment	desktopDeploy	no

vanilla

property	description	type	required
entry	source directory path to be copied into output	string	yes
static	static directory path to be copied into output	string	no

compile

property	description	type	required
entry	entry file path to build project from	string	yes
qext	qext file path to be copied into output directory	string	yes
static	static directory path to be copied into output	string	no
webpackComments	set to false to hide webpack compile comments when building	bool	no
altWebpackConfig	path to alternate webpack.config.js file that should override the default webpack config definition	string	no

serverDeploy

property	description	type	required
host	host name of qlik server	string	yes
port	port over which to access qlik server	number	no
prefix	prefix endpoint where resources are deployed. typically used with header authentication	string	no
isSecure	whether endpoint should be connected to over ssl	bool	no
allowSelfSignedSignature	allow connection to qlik server that has a self-signed certificate	bool	no
hdrAuthUser	name of user as defined in the header authentication virtual proxy	string	no
hdrAuthHeaderName	name of auth header property as defined in virtual proxy	string	no
windowsAuth	set to true to use windows authentication to deploy extension	bool	no
user	username associated with windowsAuth. if defined here, you will not be prompted for credentials in the terminal	string	no
password	password associated with windowsAuth. if defined here, you will not be prompted for credentials in the terminal	string	no

desktopDeploy

property	description	type	required
destination	destination of built extension files.	string	yes

Использованные источники

1. https://opensrc.axisgroup.com/qext/
2. https://medium.com/@jbellizzi/new-qext-277121a59b93
3. https://github.com/axisgroup/qExt