Cluster-qlik-connection NPM

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:
1. No perfil do github clique em "profile > settings > developer settings > personal access tokens > tokens (classic) > generate new token > generate new token (classic)
2. Informe para o que é o token, exemplo: "cluster lib"
3. Selecionar o tempo para expiração do token
4. Selecionar a opção "write packages"
5. 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

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.

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

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

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.

qlik react typescript vite

react-router-dom zod zustand

0.0.6

5 months ago

0.0.1

5 months ago