⚡ Instalação

Utilizando pnpm

pnpm install @znap/components-vue2

Utilizando npm

npm install @znap/components-vue2

No arquivo main.js do Vue.

import Vue from "vue";
import * as ZnapComponents from '@znap/components-vue2';

// -- Configuraçoes do Hands on Table (Opcional)
import { registerAllModules } from "handsontable/registry";
import { registerLanguageDictionary, ptBR } from "handsontable/i18n";
import numbro from "numbro";
import numbroptBR from "numbro/dist/languages/pt-BR.min.js";

numbro.registerLanguage(numbroptBR);
numbro.setLanguage("pt-BR");
registerAllModules();
registerLanguageDictionary(ptBR);
// -- Fim

Vue.use(ZnapComponents.plugin, {
  licenseKey: HOT_TABLE_LICENSE_KEY // CHAVE DE UTILIZAÇAO DO HANDS ON TABLE
})

Estrutura de importação da lib:

import * as ZnapComponents from '@znap/components-vue2';

ZnapComponents.plugin: Plugin de instalaçao global de todos com componentes para utilizaçao sem importaçao no template vue.

ZnapComponents.components: Retorna todos os componentes exportados pela lib

ZnapComponents.utils: Retorna todas as funçoes uteis exportadas pela lib

Utilização do ZnapBaseCrudView

<template>
  <ZnapBaseCrudView
    v-if="viewSettings"
    ref="baseCrudViewRef"
    v-bind="viewSettings"
    :onReload="onReload"
    :onExport="onExportFile"
    :onImport="onImportFile"
    :onSave="onSave"
    :onDelete="onDelete"
    @update:rows-changed="updateRowsChanged"
    @update:row="updateRow"
  >
  <template v-slot:footer-prepend>
    Slot para adicionar elementos do lado esquerdo dos componentes de paginação.
  </template>
  </ZnapBaseCrudView>
</template>

<script>
import Vue from "vue";
import { utils as ZnapUtils } from "@znap/components-vue2";

export default {
  data: () => ({
    viewSettings: null,
    viewMethods: null,
  }),

  async created() {
    const { CrudViewConfigs } = ZnapUtils; // Importar a classe CrudViewConfigs da utils para gerar o template de dados da tela.

    const crudViewConfigs = new CrudViewConfigs({
      viewTitle: "Titulo da página",
      viewIcon: "icone_da_pagina",
      primaryKey: "chave_primaria_da_tela",
      endpoint: CrudViewConfigs.generateEndpoint(
        "URL", {} // parametros
      ),
      useServerSidePagination?: false, // Habilita a paginação do lado do servidor, por padrão vem desabilitado. (Se habilitado, a busca também passa a acontecer do lado do servidor)
      useServerSideSearch?: false, // Habilita busca do lado do servidor por padrão que vem desabilitado.
    });

    crudViewConfigs
      .addPrimaryFilter({
        column: "coluna_que_ira_buscar", 
        filterComponent: "v-autocomplete", // componentes disponíveis: v-autocomplete, v-checkbox, date-picker
        itemsArray?: [] // Array de dados iniciais.
        initialValue?: null // Valor inicial.
        endpoint?: CrudViewConfigs.generateEndpoint(
         "URL", {} // parâmetros
        ),
        componentProps: {
          label: "Grupo empresarial",
          clearable?: true,
          required?: true // Se o valor for true, ele devera ser preenchido e, caso não for preenchido, irá exibir mensagem na tela.
          multiple?: false // Se for um v-autocomplete permite selecionar vários itens
          range?: false // Se for um date-picker permite selecionar um range de data.
        }, // Props que será passada para o componente.
         dependsOn?: '' // Filtro primário que possui dependência
         hooks?: {
          afterChange: () => {
            // Hook que será disparado após a mudança do valor.

            // * Pode ser utilizado para alterar os dados de outros filtros, ou então realizar chamadas assíncronas para atualizar o array de dados.
          }
        },
         ignoreOnFetchFunction?: false // Se o valor for true, será ignorado na função de fetch genérica, por padrão o valor é false.
      })

    crudViewConfigs
      .addSecondaryFilter({
        column: "coluna_que_ira_buscar",
        filterComponent: "v-autocomplete", // componentes disponíveis: v-autocomplete, v-checkbox, date-picker
        itemsArray?: [] // Array de dados iniciais.
        initialValue?: null // Valor inicial.
        endpoint?: CrudViewConfigs.generateEndpoint(
         "URL", {} // parametros
        ),
        componentProps: {
          label: "Empresa",
          clearable?: true,
          multiple?: false // Se for um v-autocomplete permite selecionar vários itens.
          range?: false // Se for um date-picker permite selecionar um range de data.
        }, // Props que sera passada para o componente
        dependsOn?: '' // Filtro secundario que possui dependencia
        hooks?: {
          afterChange: () => {
            // Hook que será disparado após a mudança do valor.
            
            // * Pode ser utilizado para alterar os dados de outros filtros, ou então realizar chamadas assíncronas para atualizar o array de dados.
          }
        },
         ignoreOnFetchFunction?: false // Se o valor for true, será ignorado na funçao de fetch generica, por padrao o valor é false.
      })
     
    crudViewConfigs
      .addTableOption({
        column: "chave_que_recebera_as_options",
        itemsArray?: [] // Array com dados iniciais.
        endpoint?: CrudViewConfigs.generateEndpoint(
         "URL", {
          // parâmetros
         }
        ),
        formatter?: (value) => {
          // Logica para formatar o dado quando for exibido na tabela, sem alterar o dado original.
        }
        filterFunction?: () => {
          // Logica para filtrar os dados que serão exibidos, se for passada uma filterFunction o array de itens será ignorado e o retorno será o retorno da filterFunction.

          // Deve sempre retornar um array
        },
        ignoreOnFetchFunction?: false // Se o valor for true, será ignorado na função de fetch genérica, por padrão o valor é false.
      })
    

    crudViewConfigs
      .addFormOption({
        column: "chave_que_recebera_as_options",
        dependsOn?: 'chave_que_dependa_que_tenha_valor'
        itemsArray?: [] // Array de itens iniciais.
        endpoint?: CrudViewConfigs.generateEndpoint(
         "URL", {} // parâmetros
        ),
        hooks?: {
          afterChange: (item) =>{
            // Logica que irá disparar após o valor ser alterado.

            // * Pode ser utilizado para alterar os dados ou então realizar chamadas assíncronas para atualizar o array de dados.
          }
          beforeChange: (item) => {
            // Logica que irá disparar antes do valor ser alterado.
            
            // * Pode ser utilizado para alterar os dados ou então realizar chamadas assíncronas para atualizar o array de dados.
          }
        },
         ignoreOnFetchFunction?: false // Se o valor for true, será ignorado na função de fetch genérica, por padrão o valor é false.
      })
    
    crudViewConfigs.setFormModel({
      // Modelo inicial do formulário.
    });

    this.viewSettings = crudViewConfigs.viewConfigs; // Retorna o objeto de configuraçoes da classe (Se tornará o state do componente)
    this.viewMethods = crudViewConfigs.viewMethods; // Retorna os métodos pre prontos disponíveis da classe.

   
    // Pode usar os métodos das classe CrudViewConfigs ou então criar os próprios conforme a necessidade.
    await Promise.all([
      this.viewMethods.fetchFiltersData(this.viewSettings.filters, this.$http),
      this.viewMethods.fetchTableOptionsData(
        this.viewSettings.tableOptions,
        this.$http
      ),
      this.viewMethods.fetchFormOptionsData(
        this.viewSettings.formSettings.formOptions,
        this.$http
      ),
    ]);

    this.fetchData()
  },
  methods: {
    updateRowsChanged() {
       this.viewSettings.rowsChanged = new Set(this.viewSettings.rowsChanged); // Importante para o Vue detectar que o rowsChanged alterou e exibir o elemento em destaque na tabela.
    }
    updateRow() {
      this.$set(this.viewSettings.apiData, rowIndex, data); // Importante para o vue detectar que teve alteração no elemento da tabela.
    }
    async onReload() {
      // Logica de como será tratado o evento de reload.
    }
    async onExportFile() {
       // Logica de como será tratado o evento de exportação de arquivo.
    }
    async onImportFile(
      event // evento contendo o elemento do input de arquivo.
      ) {
      // Logica de como será tratado o evento de importação de arquivo.
    }
    async onSave({
    reload = true, // variável retornada do componente para verificar se deve ou não realizar o reload (Fica a cargo do desenvolvedor)
    itemData = null  // Se for um item proveniente da modal (Criação/Edição) os dados virão aqui.
    }) {
      // Logica de como será tratado o evento de salvamento de registro(s)
    }
    async onDelete(
      rows // Array com as linhas que devem ser excluídas.
    ) {
      // Logica de como será tratado o evento de exclusão de registro(s)
    }
    async fetchData() {
      // Logica de busca de dados principais.
    }
  }
}
</script>

Utilização da Classe Auxiliar CrudViewConfigs

O intuito dessa classe é fornecer ao desenvolvedor uma interface padronizada de criação de telas, tornando o processo padronizado e de fácil aprendizado.

A classe retorna métodos e um objeto padrão de estado para ser utilizado para manipular o componente ZnapBaseCrudView por meio dos getters viewConfigs e viewMethods, além disso, possui diversos métodos/interfaces para o desenvolvedor adicionar elementos na tela de maneira padronizada evitando refazer a roda toda vez que for construir uma nova tela.

Objeto de Estado (viewConfigs):

type AvalibleFilterComponents = "v-autocomplete" | "v-checkbox" | "date-picker"
type AvalibleFormOptionHooks = "afterChange" | "beforeChange"
type AvalibleFilterOptionHooks = "afterChange"
type AvalibleFormHooks = "beforeSetItem" | "afterSetItem"
type Endpoint = [string, {[key: string]: any}]
type ComponentProps = {
  required?: boolean
  multiple?: boolean
  label: string
  range?: string
  [key: string] : any
}

interface FiltersInterface {
  column: string
  filterComponent: AvalibleFilterComponents
  itemsArray: any[]
  initialValue: any
  endpoint: Endpoint
  componentProps: ComponentProps
  hooks: AvalibleFilterOptionHooks
  dependsOn: string
  ignoreOnFetchFunction: boolean
}

interface TableOptionsInterface {
  column: string
  itemsArray: any[]
  endpoint: Endpoint
  formatter: (value: any) => any
  filterFunction: () => any[]
  ignoreOnFetchFunction: boolean
}

interface FormOptionsInterface {
  column: string
  itemsArray: any[]
  dependsOn: any
  endpoint: Endpoint
  hooks: AvalibleFormOptionHooks
  ignoreOnFetchFunction: boolean
}

const viewConfigs = {
    tableName: string,
    tableIcon: string,
    headers: [],
    columns: [],
    apiData: any[],
    useServerSidePagination: boolean,
    useServerSideSearch: boolean,
    paginationSettings: {
      page: number,
      itemsPerPage: number,
      itemsPerPageOptions: number[],
      serverItemsLength: number | null
    },
    searchColums: string[],
    primaryKey: string,
    loading: boolean,
    rowsChanged: Set<number>,
    filters: {
      primary: FiltersInterface[]
      secondary: FiltersInterface[]
      search: ''
    },
    currentFilters: {
      primary: any[]
      secondary: any[]
      search: ''
    },
    tableOptions: TableOptionsInterface[],
    formSettings: {
      baseModel: {
        [string]: any
      },
      formOptions: FormOptionsInterface[],
      hooks: {
        beforeSetItem: (item: any) => any | Promise<any>,
        afterSetItem: (item: any) => any | Promise<any>,
      },
      loading: false,
    },
    endpoint: Endpoint,
    hasFetch: boolean,
}

• tableName: O texto que será exibido como título da página.

• tableIcon: O ícone que será exibido ao lado do título da página.

• headers: Array de headers que é retornado do back-end.

• columns: Array de colunas retornado do back-end.

• apiData: Array de dados que será exibido na tabela.

• endpoint: Tupla/Array de 2 posições onde a primeira é a URL do endpoint principal da página e a segunda os parâmetros que serão passados para esse endpoint.

• hasFetch: Booleano que indica que já ocorreu o fetch de dados da página.

• useServerSidePagination: Booleano para controlar a paginação do lado servidor.

• useServerSideSearch: Booleano para controlar a busca do lado servidor. Se useServerSidePagination for True, essa opção deve ser True também.

• paginationSettings: Objeto de configuração de paginação.

  • page: Pagina atual.
  • itemsPerPage: Quantidade de itens por pagina.
  • serverItemsLength: Quantidade total de itens para paginar Se estiver utilizando paginação do lado servidor, essa informação deve ser atribuída, caso contrario, a paginação irá quebrar.
  • itemsPerPageOptions: Array com as opções de itemsPerPage: Para ter a opçao Todos o valor -1 deve ser atribuído no Array.

• searchColums: Array com as colunas que serão utilizadas na busca por texto.

• primaryKey: Chave primária da tela.

• loading: Booleano que controla o estado de loading da tela.

• rowsChanged: Set contendo os índices físicos das linhas que foram alterados.

• filters: Objeto de filtros.

  • primary: Array contendo todos os filtros primários
  • secondary: Array contendo todos os filtros secundários
  • search: String que será utilizada em busca por texto.

• currentFilters: Objeto contendo os filtros que realmente estão selecionados após o fetch de dados.

  • primary: Array contendo os valores selecionados nos filtros primários.
  • secondary: Array contendo os valores selecionados nos filtros secundários.
  • search: String contendo o filtro de texto selecionado.

• tableOptions: Array contendo as opções das colunas da tabela.

• formSettings: Objeto de configurações do formulário:

  • baseModel: Objeto contendo a estrutura inicial do objeto do item a ser criado/editado.
  • formOptions: Array contendo as opçoes dos campos do formulário.
  • hooks: Objeto contendo as funçoes de hooks do formulário:
    • beforeSetItem: Função a ser executada antes do item ser atribuído ao formulário.
    • afterSetItem: Função a ser executada após o item ser atribuído ao formulário.

Objeto de métodos (viewMethods)

type KeysToValidate = 'search' | 'primary' | 'secondary'
type FetcherReturn = {data: {rows: any[]}, [key: string]: any}
type HttpFetcher = {
  post: (url: string, params: {[key: string] : any}) => Promise<FetcherReturn>,
  get: (url: string) => Promise<FetcherReturn>,
  delete: (url: string) => Promise<FetcherReturn>,
}

const viewMethods = {
  getFilters: (filters, searchColums) => void,
  fetchTableOptionsData: (tableOptions, httpFetcher: HttpFetcher) => void,
  fetchFormOptionsData: (formOptions, httpFetcher: HttpFetcher) => void,
  fetchFiltersData: (filters, httpFetcher: HttpFetcher) => void,
  setCurrentFilters: (filters) => void,
  validateFiltersKeyHaveChange: (filters, currentFilters, keysToValidate: KeysToValidate[] ) => boolean,
}

• getFilters: função responsável por retornar o array de condições de todos os filtros de maneira formatada para atribuir aos endpoints.

  • Parâmetros:
    • Objeto de filtros.
    • Array de searchColums

• fetchTableOptionsData: função genérica responsável por realizar o fetch de todos os dados do Array de tableOptions.

• fetchFormOptionsData: função genérica responsável por realizar o fetch de todos os dados do Array de formOptions.

• fetchFiltersData: função genérica responsável por realizar o fetch de todos os dados do Array de filtros.

• setCurrentFilters: função que retorna os valores dos filtros selecionados.

  • Parâmetros:
    • Array de filtros.

• validateFiltersKeyHaveChange: função para validar se os filtros selecionados na tela possuem diferença com os filtros que de fato estão selecionados.

  • Parâmetros:
    • Objeto de filtros.
    • Objeto de currentFilters
    • Array com as chaves dos filtros que deseja comparar.

Métodos de geração do Estado inicial:

A classe possui diversos métodos para gerar o objeto inicial de estado (viewConfigs), esses métodos são interfaces padrões para facilitar e padronizar a estrutura de dados que será passada para o componente.

• Métodos Estáticos:

  • generateEndpoint: Retorna o Array/Tupla de endpoint.

    CrudViewConfigs.generateEndpoint(url: string, parâmetros?: {}): [string, {}]

• Métodos da instância:

  • addPrimaryFilter: Adiciona um filtro primário no array de filtros.

    crudViewConfigs.addPrimaryFilter({
      column: string,
      filterComponent: "v-autocomplete" | "v-checkbox" | "date-picker",
      itemsArray?: any[],
      initialValue?: any | null,
      endpoint?: [string, {}],
      componentProps: {
        label: string,
        required?: boolean,
        [string]: any
      },
      dependsOn?: string,
      ignoreOnFetchFunction?: boolean 
    }): this

  • setPrimaryFilters: Permite atribuir de maneira manual todo o Array de filtros primários.

    crudViewConfigs.setPrimaryFilters([
      {
        column: string,
        filterComponent: "v-autocomplete" | "v-checkbox" | "date-picker",
        itemsArray?: any[],
        initialValue?: any | null,
        endpoint?: [string, {}],
        componentProps: {
          label: string,
          required?: boolean,
          multiple?: boolean,
          range?: boolean,
          [string]: any
        },
        dependsOn?: string,
        ignoreOnFetchFunction?: boolean 
      }...
    ]): this

  • addSecondaryFilter: Adiciona um filtro secundário no array de filtro secundário.

    crudViewConfigs.addSecondaryFilter({
      column: string,
      filterComponent: "v-autocomplete" | "v-checkbox" | "date-picker",
      itemsArray?: any[],
      initialValue?: any | null,
      endpoint?: [string, {}],
      componentProps: {
        label: string,
        [string]: any
      },
      dependsOn?: string,
      ignoreOnFetchFunction?: boolean 
    }): this

  • setSecondaryFilters: Permite atribuir de maneira manual todo o Array de filtro secundário.

    crudViewConfigs.setSecondaryFilters([
      {
        column: string,
        filterComponent: "v-autocomplete" | "v-checkbox" | "date-picker",
        itemsArray?: any[],
        initialValue?: any | null,
        endpoint?: [string, {}],
        componentProps: {
          label: string,
          [string]: any
        },
        dependsOn?: string,
        ignoreOnFetchFunction?: boolean 
      }...
    ]) : this

  • addTableOption: Adiciona uma opção referente a uma coluna na tabela principal no Array de tableOptions.

    crudViewConfigs.addTableOption({
      column: string,
      itemsArray?: any[],
      endpoint?: [string, {}],
      formatter?: (value: any) => any
      filterFunction?: () => any[]
      ignoreOnFetchFunction?: boolean 
    }): this

  • setTableOptions: Permite atribuir de maneira manual todo o Array de tableOptions.

    crudViewConfigs.setTableOptions([
      {
        column: string,
        itemsArray?: any[],
        endpoint?: [string, {}],
        formatter?: (value: any) => any
        filterFunction?: () => any[]
        ignoreOnFetchFunction?: boolean 
      }...
    ]): this

  • setFormModel: Adiciona o modelo base de dados do formulário.

    crudViewConfigs.setFormModel(any{}): this

  • addFormOption: Adiciona uma opção referente a uma coluna do formulario no Array de formOptions.

    crudViewConfigs.addFormOption({
      column: string,
      itemsArray?: any[],
      dependsOn?: string,
      endpoint?: [string, {}],
      ignoreOnFetchFunction?: boolean,
      hooks?: {
        afterChange?: (item: any) => any
        beforeChange?: (item: any) => any
      } 
    }): this

  • setFormOptions: Permite atribuir de maneira manual todo o Array de formOptions.

    crudViewConfigs.setFormOptions([{
        column: string,
        itemsArray?: any[],
        dependsOn?: string,
        endpoint?: [string, {}],
        ignoreOnFetchFunction?: boolean,
        hooks?: {
          afterChange?: (item) =>  any,
          beforeChange?: (item) => any
        }}]): this

  • setFormHooks: Permite atribuir de maneira manual todos os hooks do formulário.

    crudViewConfigs.setFormHooks({
      beforeSetItem?: (item: any) => any | Promise<any>,
      afterSetItem?: (item: any) => any | Promise<any>
    }): this

  • addFormHook: Permite atribuir de maneira manual todos os hooks do formulário.

    crudViewConfigs.addFormHook(key: 'beforeSetItem' | 'afterSetItem', (item: any) => any | Promise<any> ): this

  • setPaginationSettings: Permite atribuir de maneira manual o objeto paginationSettings.

    crudViewConfigs.setPaginationSettings({
      page: number,
      itemsPerPage: number,
      itemsPerPageOption?: number[],
      serverItemsLength?: number | null,
    }): this