ag-server-grid

This library was generated with Angular CLI version 17.0.0.

Code scaffolding

Run ng generate component component-name --project ag-server-grid to generate a new component. You can also use ng generate directive|pipe|service|class|guard|interface|enum|module --project ag-server-grid.

Note: Don't forget to add --project ag-server-grid or else it will be added to the default project in your angular.json file.

Build

Run ng build ag-server-grid to build the project. The build artifacts will be stored in the dist/ directory.

Publishing

After building your library with ng build ag-server-grid, go to the dist folder cd dist/ag-server-grid and run npm publish.

Running unit tests

Run ng test ag-server-grid to execute the unit tests via Karma.

Further help

To get more help on the Angular CLI use ng help or go check out the Angular CLI Overview and Command Reference page.

License

See the LICENSE file for more info.

Instruções para usar o ag-serve-grid:

No template inicial de cada projeto está sendo disponibilizado de exemplo de como usar o ag-server-grid

Tag para chamar o componente ag-server-grid no HTML:

Configurações necessárias para que a tabela seja renderizada corretamente:

1- Headers

• Para definir os nomes nas colunas que irá aparecer no Header da sua tabela, faça o import da interface ColDef:

• Depois de importar a interface ColDef, declare a váriavel tipando com a interface ColDef e siga o exemplo:

• Declare a váriavel columnDefs dentro da tag <datatable-server></datatable-server>:

  

Resultado depois de configurar o Headers:

2- Body Table

Para renderizar o tbody do ag-server-grid é necessário realizar os seguintes passos:

• Implemente a interface igualando os campos com os campos que vem do back-end:

  

• Declare uma váriavel com o tipo de interface que acabamos de criar:

  

• Chame essa váriavel dentro da tag <datatable-server></datatable-server>:

  

• Dentro da váriavel columnDefs que declaramos anteriormente, declare os campos em field para que os valores que vem do backend sejam reconhecidos pelo componente:

  

Resultado depois de fazer a configuração do tbody:

3 - Ativação do Botão "Editar" ou "Excluir" registros

• Dentro da tag <datatable-server></datatable-server> acrescente o [editable]="true" ou [deletable]="true" para habilitar o botão de editar/excluir na tabela:

Resultado depois de ativar a configuração [editable]="true" ou [deletable]="true" :

• Para editar ou excluir, basta você selecionar a linha e apertar no botão desejado:

  

• Para pegar a linha selecionada com ação editar, coloque na tag <datatable-server></datatable-server> a propriedade (getRowEdit)="editar($event)"

  

  

Resultado depois de fazer a configuração:

• Para pegar a linha para excluir, basta seleciona a linha desejada e apertar excluir:

• Para pegar a linha selecionada com ação excluir, coloque na tag <datatable-server></datatable-server> a propriedade (getRowExcluir)="excluir($event)"

Resultado depois de fazer a configuração:

• Caso deseje selecionar uma lista para excluir basta clicar Ctrl + click nas linhas desejadas

• Ou apertar Ctrl + Shift + click e marcar até a linha atual:

• Para pegar a lista de itens selecionados coloque na tag <datatable-server></datatable-server> a propriedade (getListExcluir)="listExcluir($event)"

  

  

  Resultado depois de fazer a configuração:

  

4 - Pegar linhas selecionadas na tabela:

• Caso necessite pegar 1 uma linha selecionada para fazer outro tipo de ação, basta colocar na tag <datatable-server></datatable-server> (getRowSelect)="getRow($event)" o evento será disparado assim que as linha for selecionada com double click:

Resultado depois de fazer a configuração:

• Caso necessite pegar uma lista selecionada para fazer outro tipo de ação, basta colocar na tag <datatable-server></datatable-server> (getListSelect)="getList($event)" o evento será disparado assim que as linha forem selecionadas:

  

  

Resultado depois de fazer a configuração:

5 - Tradução do Header da tabela ag-server-grid com ngx-translate de acordo com o idioma escolhido:

• Faça a importação do TranslateModule e do TranslateService no componente:

  

• Declare TranslateModule em imports dentro do componente:

  

• Declare private translate: TranslateService dentro do construtor:

  

• Dentro da variável columnDefs que já declaramos nos passos anteriores, coloque a propriedade headerValueGetter e chame um método que vamos criar no próximo passo. como demonstrado no exemplo a seguir:

  

• crie o método localizeHeader() como na imagem:

• Declare dentro do arquivo de tradução as chaves field que tem no columnDefs:

• E passe o nome do JSON para que o serviço translate possa encontrar a tradução especifica e concatene com a varivel headerIdentifier como mostra no exemplo:

• Retorne o valor recuperado que está dentro da variavel headerIdentifier usando o this.translate.instant(headerIdentifier):

Resultado depois de fazer a configuração:

• Quando apertamos o botão para traduzir para o Português:

• Quando apertamos o botão para traduzir para o Inglês:

6 - Ordenação por coluna:

Na variável columnDef onde estão declarada as nossas colunas, basta colocar a propriedade sortBy:true na coluna que deseja ordenar ao carregar os dados:

7 - Largura das colunas:

Na variável columnDef onde estão declarada as nossas colunas, basta colocar a propriedade minWidth para determinar o mínimo de largura de uma coluna ou declarar maxWidth para declarar qual é o máximo de largura da coluna:

8 - Formatação de Datas:

Não é necessário fazer nenhuma configuração para formatar a data, pois o componente tem inteligência para identificar o formato de uma data e o formato de uma string. Sendo assim quando for identificado uma data, o componente irá formatar automaticamente:

9 - Exportar tabela para CSV:

Basta ir no HTML e acionar na tag <datatable-server></datatable-server> [exportCsv]="true" como demonstrado no exemplo abaixo:

** Resultado depois de fazer a configuração:**

Arquivo Gerado:

Obs: O botão Export CSV gera o arquivo apenas com as informações que estão na tela, caso precise gerar o arquivo com todos os registros da base de dados, opte sempre fazer pelo back-end.

10 - Paginação Server Side:

• Para ativar a paginação basta ir até a tag <datatable-server></datatable-server> e acrescentar o [paginationServer]="true"

• Implemente essa variáveis:

  public pager: any = {}; public totalCount!: number; public totalPages: number = 0; public recordsPerPage: number = 5; public currentPageNumber: number = 0; public totalRecordsCount: number = 0;

  Exemplo:

  

• Implemente o método next(event:number) e dentro do método chame seu método de listagem passando o valor recebido para ir para a página seguinte. Siga o exemplo:

  

  Chame o método next dentro da tag <datatable-server></datatable-server>:

  

• Implemente o método prev(event:number) e dentro do método chame seu método de listagem passando o valor recebido para ir para a página anterior. Siga o exemplo:

  

  Chame o método prev dentro da tag <datatable-server></datatable-server>:

  

• Declare o [pager]="pager" dentro da tag <datatable-server></datatable-server>

  

• Chame o (setPage)="pager = $event" dentro da tag <datatable-server></datatable-server>:

  

• Implemente o método getNumberPage(event:number) e dentro do método chame seu método de listagem passando o valor recebido para ir para a página escolhida. Siga o exemplo:

  

  Chame este método dentro da tag <datatable-server></datatable-server>

  

  Resultado do Funcionamento dos botões:

  

• Para que a paginação funcione corretamente, faça a importação das interface de configuração de paginação:

  

• Crie o método de configurações no código para passar ao componente para que seja possível processar a informação da página:

  configPag(): ConfigPagination {
    return {
      totalPages: this.totalPages,
      totalRecordsCount: this.totalRecordsCount,
      recordsPerPage: this.recordsPerPage,
      currentPageNumber: this.currentPageNumber
   }}
  

• Chame configPag dentro da tag <datatable-server></datatable-server> :

  

• Dentro do seu método listar, pegue as variáveis que declaramos nos passos anteriores e coloque as informações da paginação que vem da API:

  

Depois de fazer toda a configuração da paginação, você verá um resultado como esse:

11 - Campo de Pesquisa:

• Para ativar o campo de pesquisa, basta colocar no HTML um campo de texto com uma variável para guardar o texto digitado pelo usuário:

  

• Declare a variável usada no input no TypeScript com o tipo string:

  

  

• Passe a variável dentro da tag <datatable-server></datatable-server> com a propriedade [searchText]="searchText":

  

Obs: O campo de pesquisa só irá funcionar em registros renderizados na tela.

12 - Testes Unitários:

• Exemplo de teste unitário para testar os campos definidos no Header da tabela:

    it('should have expected column headers', () => {
       usersServiceSpy.listUsers.and.returnValue(of(listaDeUsers));
       component.listaUsuarios();
       fixture.detectChanges();
  
      const elm = fixture.nativeElement;
      const grid = elm.querySelector('datatable-server');
      const headers = grid.querySelectorAll('#cat-table-header tr th');
      const headerTexts = Array.from(headers).map((header: any) => header.textContent.trim());
  
      expect(headerTexts).toEqual(['ID', 'Nome' ,'Cliente', 'User ID' ,'Excluir']);
    });
  

• Exemplo de teste unitário para testar se os valores da tabela estão conforme o esperado e verificar se a tabela está sendo carregada corretamente:

    it('the grid cells should be as expected', async () => {
  
       usersServiceSpy.listUsers.and.returnValue(of(listaDeUsers));
       component.listaUsuarios();
       fixture.detectChanges();
  
      const cellElements = fixture.nativeElement.querySelectorAll('#cat-table-body tr td');
  
     expect(cellElements.length).toEqual(10);
  
     expect(cellElements[0].textContent).toEqual("012b576j-9211-25348-wr31-v52fh831880m5");
     expect(cellElements[1].textContent).toEqual("value_test");
     expect(cellElements[2].textContent).toEqual("012b576j-9211-25348-wr31-v52fh831880m5");
     expect(cellElements[3].textContent).toEqual('PAAAAAAAAAAAA');
     expect(cellElements[4].textContent).toEqual("Excluir");
     expect(cellElements[5].textContent).toEqual("012b576j-9211-25348-wr31-v52fh831880m5");
     expect(cellElements[6].textContent).toEqual("value_test");
     expect(cellElements[7].textContent).toEqual("012b576j-9211-25348-wr31-v52fh831880m5");
     expect(cellElements[8].textContent).toEqual('PAAAAAAAAAAAA');
     expect(cellElements[4].textContent).toEqual("Excluir");
    });
  

Obs: Estes valores são fictícios, trocar conforme a sua tabela e seu teste unitário.

13 - Botões na tabela:

• Dentro da variável colDef, basta você colocar showButton:true e colocar as configurações necessárias do botão para personalização, siga o exemplo a seguir:

  

Resultado depois de fazer a configuração:

obs: Para fazer a personalização dos botões você pode usar classes no bootstrap ou fazer a própria estilização e chamar a classe dentro da configuração class.

• Para recuperar a linha no click do botão dentro da tabela, basta colocar dentro da tag <datatable-server></datatable-server> (getRowBtn)="getValuesBtn($event)"

Resultado depois de fazer a configuração:

14 - Personalização dos botões:

• Para fazer as configurações dos botões que ficam acima da tabela, basta chamar as configurações abaixo dentro da tag <datatable-server></datatable-server> [configBtnEdit]="configBtnEdit()" [configBtnDelete]="configBtnDelete()" [configBtnCsv]="configBtnCsv()":

Exemplo de personalização:

    configBtnEdit():ConfigButton{
      return {
        text:'Editar',
        icon: 'bi bi-pencil-square',
        class: 'btn btn-warning'
      }
    }

    configBtnDelete():ConfigButton{
      return {
        text:'Deletar',
        icon: 'bi bi-x-circle',
        class: 'btn btn-danger'
      }
    }


    configBtnCsv():ConfigButton{
      return {
        icon: 'bi bi-filetype-csv',
        class: 'btn btn-ligh'
      }
    }

15 - Paginação Local:

• Para ativar a paginação local basta ir até a tag <datatable-server></datatable-server> e acrescentar o [pagination]="true"

Resultado depois de aplicar a configuração: