Extensões são componentes do Qlik Sense feitos com HTML, CSS e JavaScript, destinados a serem usados dentro de QVFs ou Mashups.
Elas servem a uma infinidade de propósitos, como criar gráficos personalizados, botões, tabelas, comentários, e assim por diante.
Este pequeno post mostrará como criar uma extensão do zero. Será um gráfico de linha personalizado usando a biblioteca ECharts.
O resultado final será a imagem abaixo, e você pode usá-la em suas aplicações e criar novos recursos como quiser!
Ferramentas necessárias
– Qlik Sense Desktop
– Um editor de texto (eu uso o Visual Studio Code)
– Biblioteca ECharts (https://echarts.apache.org/)
– Conhecimento básico de HTML e JS
– Navegador (acessaremos o Qlik Sense por meio deste endereço: http://localhost:4848/hub)
Construindo a estrutura básica de arquivos
Depois de ter o Qlik Sense Desktop funcionando, criaremos um arquivo chamado ClusterLineChart dentro da pasta /Extensions/. Geralmente está localizada em Documents/Qlik/Sense/Extensions/.
– ClusterLinechart.qext
– ClusterLinechart.js
O arquivo QEXT é responsável por informar ao Qlik Sense o que o conjunto de arquivos acima representa. Nesse caso, o tipo será “visualization”.
Conteúdo do arquivo ClusterLinechart.qext
{
"name" : "Cluster Line Chart",
"description" : "Minha primeira extensão!",
"icon" : "extension",
"type" : "visualization",
"version": "0.1",
"author": "Thomas Pessato" }E a estrutura básica do arquivo Javascript:
Conteúdo do arquivo ClusterLinechart.js
define( [
'jquery'
],
function ( $ , echarts) {
'use strict';
return {
paint: function ( $element, layout ) {
$element.append("teste");
//deverá aparecer escrito 'teste' ao inserir a extensão
}
};
} );Feito isso, agora podemos acessar nossa extensão pela aba “objetos personalizados” dentro de um QVF.
Nota 1: A variável $element é a caixa que contém nossa extensão. Ou seja, tudo o que colocarmos dentro desse elemento aparecerá na tela. Isso inclui texto ou qualquer elemento html.
Nota 2: O método paint é executado toda vez que uma ação ocorre na tela, seja um redimensionamento da janela, redimensionamento do objeto da planilha, um filtro aplicado, etc. Esse método é responsável por “pintar” o objeto na tela.
Para fins de teste, incluiremos o texto “teste” dentro da nossa extensão. Ao inserirmos a extensão em uma planilha, o texto “teste” deve estar visível:
Ótimo! Agora temos uma extensão que podemos incluir dentro de um QVF, e ela já traz informações!
Agora devemos garantir que todas as nossas dependências estejam incluídas em nossa extensão. Nesse caso, significa incluir a biblioteca ECharts.
define( [
'jquery',
'https://cdnjs.cloudflare.com/ajax/libs/echarts/4.2.1/echarts.min.js'
],
function ( $ , echarts) {
//repare na variável echarts, logo depois de $.
…
} );Neste ponto devemos conseguir “imprimir” a variável “echarts” dentro da nossa extensão e verificar que ela existe no console (pressione F12 no navegador). Nota: para isso funcionar, devemos inserir a extensão dentro de uma planilha.
Em outras palavras, agora podemos usar a biblioteca ECharts e começar a construir nossas visualizações!
Agora precisamos definir quais propriedades/dados queremos que o Sense Engine retorne. Isso significa os dados, título, subtítulo e opções de rodapé do objeto, e assim por diante. Para que isso funcione, devemos declarar algumas propriedades dentro do nosso código JavaScript, que trataremos dentro do nosso “return” no trecho de código abaixo.
define( [
'jquery',
'https://cdnjs.cloudflare.com/ajax/libs/echarts/4.2.1/echarts.min.js'
],
function ( $, echarts ) {
'use strict';
return {
initialProperties: {
qHyperCubeDef : {
qDimensions : [],
qMeasures : [],
qInitialDataFetch : [{
qWidth : 2,
qHeight : 50
}]
}
},
definition: {
type: "items",
component: "accordion",
items: {
data: {
uses: "data",
dimensions: {
uses: "dimensions"
},
measures: {
uses: "measures"
}
},
sorting: {
uses: "sorting"
},
appearance: {
uses: "settings",
}
}
},
paint: function ( $element, layout ) {
…
};
} );Para mais informações sobre o significado de cada propriedade: Construindo um painel de propriedades para sua extensão
De qualquer forma, agora podemos ir para o trabalho de verdade. Com essas propriedades, quando inserirmos a extensão em uma planilha, aparecerá a opção “Adicionar dimensão” e “Adicionar medida”, como geralmente aparece nas extensões nativas do Qlik.
Ao escolher os dados que queremos incluir (uma medida e uma dimensão), o engine do Qlik retornará os dados e metadados dentro da variável chamada “layout”, que está dentro da função “paint”. A saber: function ($element, layout) {…}.
paint: function ( $element, layout ) {
var data = layout.qHyperCube.qDataPages[0].qMatrix;
console.log(data);
}Adicionando esse trecho de código e percorrendo o objeto layout do JavaScript, encontraremos a propriedade qMatrix, que tem todos os dados. Podemos verificar pelo console do navegador quais dados estão sendo retornados. Nota: para visualizar os dados como mostrado abaixo, você deve selecionar uma dimensão e uma medida para a extensão.
O que precisamos fazer agora é converter esses dados do console em uma visualização mais amigável no navegador principal.
Para estruturar os dados que obtivemos do Qlik Engine, sabemos que a posição 0 do array corresponde à dimensão, e a posição 1 à medida. Vamos agora separar esses dados em strings diferentes.
var dimensions = layout.qHyperCube.qDataPages[0].qMatrix.map((item) => { return item[0].qText;
});
var measures = layout.qHyperCube.qDataPages[0].qMatrix.map((item) => {
return {
value: item[1].qNum,
itemStyle: {
color: "red"
}
}
});Usei o método map para otimizar o código. Esse código resultará em dois arrays, um contendo o texto da dimensão (qText), e o segundo conterá 2 variáveis: value (qNum) e itemStyle. O array value corresponderá ao valor da medida, e o array itemStyle corresponderá a personalizações pertinentes da linha. Nesse caso, decidi apenas colocar uma variável “color” com o valor “red”, que será usada para renderizar o gráfico do ECharts. Poderíamos inserir estilos para a linha, como espessura, tipos de linha, e assim por diante.
Por último, mas não menos importante, agora passaremos os dados para a biblioteca gráfica e retornaremos o elemento a ser exibido em nossa extensão.
paint: function ( $element, layout ) {
var dimensions = layout.qHyperCube.qDataPages[0].qMatrix.map((item) => {
return item[0].qText;
});
var measures = layout.qHyperCube.qDataPages[0].qMatrix.map((item) => {
return {
value: item[1].qNum,
itemStyle: {
color: "red"
}
}
});
var myChart = echarts.init($element[0]);
//inicializando o gráfico na caixa da extensão. Como $element é um elemento jQuery, acessamos pelo índice 0.
// Aqui passamos todas as variáveis para o objeto de configuração do gráfico, de acordo com a documentação do Echarts. xAxis para dimensões, e depois passando as medidas na chamada série "data"
var option = {
legend: {
data:[layout.qHyperCube.qMeasureInfo[0].qFallbackTitle]
},
xAxis: {
data: dimensions // variável 'dimensions', declarada no início
},
yAxis: {},
series: [{
lineStyle: {
normal: {
color: "red",
width: 3,
type: "solid"
}
},
name: 'Sales',
type: 'line',
data: measures // variável 'measure', declarada no início
}]
}; // o que define isso como um gráfico de linha é a propriedade chamada "type"
myChart.setOption(option);
myChart.resize(); //sempre que uma ação é tomada, o gráfico deve ser redimensionado via resize(). Este é um método do eCharts.
}Para mais personalizações (há MUITAS), você pode consultar a documentação do ECharts e testar suas inúmeras opções (https://echarts.apache.org/en/option.html).
O resultado final, usando o próprio Consumer Sales.qvf do Qlik e usando a dimensão City junto com “Avg Sales”.
Observe que, neste momento, o painel de personalização funciona, com suas configurações básicas:
Há várias personalizações e implementações adicionais a serem feitas, como:
- filtros de gráfico;
- opções de zoom;
- opções de exportação de dados;
- personalizações de cores;
- adição de linhas de referência;
- personalizações de ponto de entrada;
- tooltip com valores; e mais.
No entanto, esses serão abordados em posts subsequentes. Esperamos que este post tenha sido útil! Para mais detalhes sobre extensões e gráficos personalizados, entre em contato conosco!
