Содержание урока по Qlik Sense
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 была создана по трем основным причинам.
- обеспечить лучшую поддержку для компиляции javascript следующего поколения
- упростить процесс развертывания расширений в средах qlik sense
- сделать инициализацию новых проектов расширений более воспроизводимой с помощью стандартных шаблонов кода
JavaScript следующего поколения
скрипт, который вы видели на предыдущей странице (и javascript, который вы увидите во многих расширениях qlik), написан на ванильном javascript, который обычно можно использовать в большинстве современных веб-браузеров. это отличное начало для многих, кто начинает знакомиться с javascript, но многие разработчики хотят использовать более новые версии и возможности javascript, включая импорт модулей, функции стрелок и многое другое.
существует множество инструментов, помогающих преобразовывать новый код javascript в обратно совместимые форматы. qExt использует babel в координации с webpack для компиляции всего кода в формат, который может использоваться современными браузерами.
Оптимизация развертывания
в последнем разделе упоминался процесс развертывания расширений в наших средах qlik. если вы выполняете серьезную работу по разработке проекта, ручное решение по удалению и повторному импорту кода проекта каждый раз, когда вносятся изменения, вероятно, не подходит. именно поэтому мы встроили интеграцию развертывания в qExt. инструмент может установить прямое соединение с вашим сервером qlik и автоматически удалить старое расширение и развернуть обновленное за считанные секунды с помощью API qrs
Шаблоны
в примере кода с предыдущей страницы использовался только один из многих методов, доступных в расширениях qlik. обычно при разработке расширений мы используем другие объекты и методы, такие как initialProperties, шаблон, контроллер и другие, чтобы полностью использовать настройки наших расширений. мы обнаружили, что многие из них довольно часто используются в проектах, и вместо того, чтобы переопределять их каждый раз, когда мы создаем новое расширение, мы определили их в шаблонных проектах, которые можно использовать для создания новых проектов расширений из
Введение в qExt Packages (Пакеты qExt)
библиотека qExt на самом деле состоит из двух разных пакетов, которые помогают нам в разработке расширений.
- qext-scripts — инструмент, который запускается в нашей среде разработки расширений для компиляции кода и развертывания его в средах qlik sense.
- 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, используемый для определения любых стилей для нашего объекта расширения. обратите внимание, что все классы должны быть предварительно выбраны с именем класса объекта расширения, которое будет в формате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 можно увидеть в $element
dom, который передается функциям рисования и изменения размера.
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 |
Использованные источники
- https://opensrc.axisgroup.com/qext/
- https://medium.com/@jbellizzi/new-qext-277121a59b93
- https://github.com/axisgroup/qExt