cluster-qlik-connection
v0.0.6
Published
Cluster library with Vite, Typescript and React.js
Readme
Descrição
Este documento tem o objetivo de fornecer uma descrição completa e detalhada da "libzinha" da Cluster, incluindo uma descrição de todos os recursos com instruções de utilização.
Índice
Configurações de Instalação
Gerar um token para instalação da lib:
- No perfil do github clique em "profile > settings > developer settings > personal access tokens > tokens (classic) > generate new token > generate new token (classic)
- Informe para o que é o token, exemplo: "cluster lib"
- Selecionar o tempo para expiração do token
- Selecionar a opção "write packages"
- Clicar em "Generate token";
Na pasta raiz do projeto criar um arquivo .npmrc com o seguinte conteúdo, substituindo o trecho em negrito pelo token gerado no passo 1.:
@cluster-data-experience:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=TOKEN_GERADO_NO_GITHUB- Instalar a biblioteca via terminal ou arquivo package.json. Verificar a última versão.
npm install @cluster-data-experience/cluster-qlik-connection@latest "@cluster-data-experience/cluster-qlik-connection": "latest"Estrutura da Biblioteca
A biblioteca foi estruturada de forma que a context "ConfigProvider" trabalha com a conexão qlik, autenticação de usuários, etc., exceto a parte de conexão com algum App específico, que é feita pela context "QlikAppProvider".
É importante destacar que por enquanto não deve ser utilizado React.StrictMode, até que sejam corrigidos os erros apontados.
ConfigProvider
A context QlikProvider recebe uma prop "connectionConfig" que deve ter as configurações padrão de conexão qlik, e a context deve envolver o código conforme a necessidade do projeto. Exemplos:
const config = {
useQlikDefault: false,
environment: 'saas',
useQlikDefault: false,
environment: 'saas',
host: 'cluster.us.qlikcloud.com',
prefix: '/',
port: 443,
isSecure: true,
webIntegrationId: 'f-pW61I6iRHS0UUocC1bGLtuFD7_Wjym'
};
//caso utilizar o StrictMode, posicionar aninhado à context QlikProvider
<QlikProvider connectionConfig={config}>
<React.StrictMode>
<QlikAppProvider appId="987654321">
<App />
</QlikAppProvider>
<QlikAppProvider appId="abcdefg">
<OtherApp />
</QlikAppProvider>
</React.StrictMode>
</QlikProvider>;QlikAppProvider
A context de QlikAppProvider recebe uma prop "appId" que deve ser o ID do aplicativo a ser utilizado. Exemplo:
<QlikAppProvider appId="d6bf6de3">
<KPI objectId={'7bcb8cf6'} />
<QlikAppProvider>Uma context de app pode ser aninhada dentro de outra, porém o app da context pai não poderá ser acessado. Exemplo:
<QlikAppProvider appId="app1">
<div>...</div>
<QlikAppProvider appId="app2">
<KPI objectId={'KPI do app 1'} /> //não é possível acessar
<KPI objectId={'KPI do app 2'} />
</QlikAppProvider>
</QlikAppProvider>Neste exemplo, o kpi do app 1 não será carregado, pois dentro da QlikAppProvider com app2 não é possível acessar o app1 ou seus objetos.
Visualization
Nesta seção são descritos os objetos de visualização: KPI, Linechart, Barchart, Table e NativeObject.
KPI
O componente de kpi pode receber as seguintes propriedades: objectId, style, className, primary, secondary e loader, sendo que nenhuma delas é obrigatória. Ou seja, é possível renderizar um componente de kpi apenas fornecendo os valores, ou fornecendo apenas o objectId.
objectId
A prop objectId deve receber uma string que é o ID do objeto no qvf.
style e className
A propriedade style deve receber um objeto com propriedades CSS, exemplo:
{
display: 'flex',
flexDirection: 'column'
}O componente de kpi é estruturado da seguinte forma:
<div
style={{ width: '100%', height: '100%', display: 'flex', ...style }}
className={`custom-table ${className ? className : ''}`}
>
{_primary?.value != null && (
<span>
<p>{_primary.title}</p>
<p style={{ color: colortemp }}>
{numeral(_primary.value).format(primary?.format)}
</p>
</span>
)}
{_secondary?.value != null && (
<span>
<p>{_secondary.title}</p>
<p style={{ color: colortemp2 }}>
{numeral(_secondary.value).format(secondary?.format)}
</p>
</span>
)}
</div>Dessa forma o estilo do KPI pode ser desenvolvido através de css, passando classNames para o componente KPI, ou através de styled componentes endereçando a árvore de componentes. Exemplo:
const Kpi2Container = styled.div`
div {
span:nth-of-type(1) {
background-color: 'lightgray";
p:nth-of-type(1) {
color: blue;
}
p:nth-of-type(2) {
text-decoration: underline;
color: green;
font-size: 40px;
}
}
}
`;primary e secondary
As propriedades primary e secondary contam com as seguintes propriedades: title, value, format e style.
title:
A propriedade title irá sobrescrever o título do kpi vindo do qvf.
value
A propriedade value irá sobrescrever o valor do kpi vindo do qvf.
format
A propriedade format é um método da biblioteca numeral.js, e deve receber uma string conforme os padrões da biblioteca; Essa propriedade sobrescreve o formato do valor do kpi
loader
A prop loader deve receber um React.Node com um loader personalizado. Caso essa prop não seja utilizada, será exibido um loader padrão.
Sugestões de loaders para utilizar como base:
Linechart
O componente de linechart recebe as propriedades: objectId, style, className, options, reference e loader, sendo que nenhuma delas é obrigatória, ou seja, é possível renderizar linecharts apenas fornecendo as options conforme padrão do echarts, ou apenas fornecendo o objectId.
objectId
A prop objectId deve receber uma string que é o ID do objeto no qvf.
style e className
A propriedade style deve receber um objeto com propriedades CSS inline. Além disso, o componente pode ser estilizado através de css, utilizando classNames, ou ainda utilizando styled componentes endereçando a árvore de componentes.
options
As options são propriedades de configuração de gráficos. No caso do componente Linechart as options padrão são:
{
title: {},
tooltip: {},
xAxis: {
type: 'category',
data: xAxisData
},
yAxis: {
type: 'value',
axisLabel:{}
},
series: finalSeries,
grid: {
top: '10%',
left: '3%',
right: '4%',
bottom: '3%',
containLabel: true
}
}
As options passadas via prop no componente irão sobrescrever as configurações padrão.
As possibilidades de configurações via options são as mesmas do echarts. Consultar a documentação.
reference
A prop reference pode receber as propriedades labelFormat, labelFormatter, tooltipFormat, tooltipFormatter e axisFormat
As propriedades Formatter devem receber funções de formatação conforme padrão no echarts. Consultar a documentação.
As propriedades **Format **são utilizadas via biblioteca numeral.js, e devem receber uma string conforme os padrões da biblioteca; Essa propriedade sobrescreve o formato do valor em questão, seja label, tooltip ou axis format.
loader
A prop loader deve receber um React.Node com um loader personalizado. Caso essa prop não seja utilizada, será exibido um loader padrão.
Sugestões de loaders para utilizar como base:
Barchart
O componente de barchart recebe as propriedades: objectId, style, className, options, reference,appearanceProp, enableScroll e loader, sendo que nenhuma delas é obrigatória, ou seja, é possível renderizar linecharts apenas fornecendo as options conforme padrão do echarts, ou apenas fornecendo o objectId.
objectId
A prop objectId deve receber uma string que é o ID do objeto no qvf.
style e className
A propriedade style deve receber um objeto com propriedades CSS inline. Além disso, o componente pode ser estilizado através de css, utilizando classNames, ou ainda utilizando styled componentes endereçando a árvore de componentes.
options
As options passadas via prop no componente irão sobrescrever as configurações padrão.
As possibilidades de configurações via options são as mesmas do echarts. Consultar a documentação.
reference
A prop reference pode receber as propriedades labelFormat, labelFormatter, tooltipFormat, tooltipFormatter, axisFormat.
As propriedades Formatter devem receber funções de formatação conforme padrão no echarts. Consultar a documentação.
As propriedades **Format **são utilizadas via biblioteca numeral.js, e devem receber uma string conforme os padrões da biblioteca; Essa propriedade sobrescreve o formato do valor em questão, seja label, tooltip ou axis format.
loader
A prop loader deve receber um React.Node com um loader personalizado. Caso essa prop não seja utilizada, será exibido um loader padrão.
Sugestões de loaders para utilizar como base:
Native Object
O componente NativeObject renderiza objetos nativos a partir do id do qvf. Ele pode receber as propriedades objectId (obrigatória), styles e loader.
objectId
A prop objectId deve receber uma string que é o ID do objeto no qvf.
style e className
A propriedade style deve receber um objeto com propriedades CSS inline. Além disso, o componente pode ser estilizado através de css, utilizando classNames, ou ainda utilizando styled componentes endereçando a árvore de componentes.
loader
A prop loader deve receber um React.Node com um loader personalizado. Caso essa prop não seja utilizada, será exibido um loader padrão.
Sugestões de loaders para utilizar como base:
Custom Table
O componente de CustomTable recebe as props objectId, styles, className, firstLoadRows, incrementRows e loader, sendo que a propriedade qlikid é obrigatória.
objectId
A prop objectId deve receber uma string que é o ID do objeto no qvf.
style e className
A propriedade style deve receber um objeto com propriedades CSS inline. Além disso, o componente pode ser estilizado através de css, utilizando classNames, ou ainda utilizando styled componentes endereçando a árvore de componentes.
firstLoadRows
A prop firstLoadRows deve receber um valor numérico inteiro, e representa o número de linhas que serão carregadas do qlik na primeira carga de dados. Não é uma propriedade obrigatório, e caso não seja fornecido nenhum valor, será utilizado 30.
incrementRows
A prop incrementRows deve receber um valor numérico inteiro, e representa a quantidade de linhas a serem carregadas quando o usuário rola até o final da tabela. Não é uma propriedade obrigatório, e caso não seja fornecido nenhum valor, será utilizado 5.
loader
A prop loader deve receber um React.Node com um loader personalizado. Caso essa prop não seja utilizada, será exibido um loader padrão.
Sugestões de loaders para utilizar como base:
Tipagem / Typing
As tipagens dos componentes devem ser atualizadas e incluídas no arquivo "types.d.ts", na pasta raiz do projeto, para que o build seja executado corretamente. Além disso, foram feitas algumas configurações nos arquivos para que os tipos fossem aplicados e gerados corretamente na instalação da biblioteca.
No arquivo types.d.ts é necessário criar uma interface com as propriedades do componente da biblioteca, e exportar uma função com as props tipadas para essa interface, e o tipo da funçao sendo JSX.Element.
A definiçao da interface e também a exportaçao da função devem ser declarados dentro do módulo '@cluster-data-experience/cluster-qlik-connection'.
Exemplo:
//types.d.ts
declare module '@cluster-data-experience/cluster-qlik-connection' {
export function NovoComponente(props: PropsNovoComponente): JSX.Element;
interface PropsNovoComponente {
objectId: string;
style?: React.CSSProperties;
className?: string;
loader?: React.ReactNode;
}
}tsconfig.json
Foi incluído o arquivo de tipos na opção "include" do arquivo tsconfig.json. No caso dessa biblioteca está inserido conforme a seguir:
//tsconfig.json
{
"compilerOptions": {"..."},
"include": ["./src", "./lib", "types.d.ts"],
}package.json
Foi incluído o arquivo de tipos na opçao "exports" do arquivo package.json, conforme a seguir:
//package.json
"exports": {
".": {
"import": "./dist/cluster-qlik-connection.es.js",
"require": "./dist/cluster-qlik-connection.umd.js",
"types": "./dist/types.d.ts" <--
}
},vite.config.ts
Foram incluídas algumas propriedades no arquivo vite.config.ts conforme a seguir:
//vite.config.ts
export default defineConfig((configEnv) => ({
plugins: [
[...]
dts({
include: ['types.d.ts'],
[...]
insertTypesEntry: true
})
],
[...]
})):handshake: Contributing
Contributions, issues and feature requests are welcome!Feel free to check issues page. You can also take a look at the contributing guide.