/xGridV2

grid like grid delphi

Primary LanguageJavaScript

xGrid v2.0

O xGrid é um grid robusto, possui inúmeras funcionalidades, com uma alta performance. É um componente desenvolvido apenas com javascript sem uso de bibliotecas externas.

Principais Funcionalidades

  • Carregar os dados através de um objeto JSON.
  • Pesquisar com mecanismo de paginação.
  • Redimensionar tamanho das colunas.
  • Vincular campos do formulário com os dados do grid.
  • Ordenação dos dados.
  • Diversas possibilidade de filtragem dos dados.
  • Totalizar valores de uma coluna.
  • É possível vincular botões (inserir,alterar,deletar,salvar, cancelar, entre outros).
  • Fácil inserção, alteração e remoção de dados
  • Dentre outras funcionalidades...

Instalação

Clone o repositório em um diretório local.

    git clone git@github.com:dffrancisco/xGridV2.git

Importando

Em seu html declare o css:

    <link rel="stylesheet" href="./xGridV2.css">

Para usar o xGrid você deve chamá-lo em seu arquivo .js através de import.

    import xGridV2 from './xGridV2';

Modo de Uso

É necessário um elemento no seu html com um id ou classe para usar na instância do xGrid.

    <!DOCTYPE html>
    <html lang="pt-BR">
    <head>
        <title>xGrid v2.0</title>
        <link rel="stylesheet" href="./xGridV2.css">
    </head>
    <body>
        <div id="pnGrid"></div>
        <script src="./xGridV2.js"></script>
        <script src="example.js" type="module"></script>
    </body>
    </html>

No javascript iremos instanciar o objeto da seguinte forma:

Create

    const grid = new xGridV2.create({
        el: '#pnGrid'
    })

    grid.source(json);

Temas

O xGrid vem com 4 estilos de temas que podem ser informado dentro do create, os temas são:

Gray Dark
x-grayV2 x-darkV2
Opacity White
x-opaciteV2 x-whiteV2

Parâmetro Create

Create é responsável por instanciar o xGrid. Recebe um objeto como parâmetro que pode ter as seguintes propriedades passadas:

Propriedade Descrição Tipo Default
el Id ou classe do elemento onde será instanciado o xGrid. (Obrigatório) String
source Dados que irão popular o grid. Array of Object (JSON) [empty]
width Largura do grid. Numeric
height Altura do grid. Numeric
heightLine Altura da linha do grid. Numeric 30
setFocus Inicia o grid focado na linha informada. Numeric
theme Informe a classe do tema que deseja utilizar. Lista de temas disponíves acima. String x-grayV2
title Visibilidade da barra de título Boolean true
count Visibilidade do contador/índice na primeira coluna. Boolean false
multiSelect Possibilita a seleção de múltiplas colunas ao segurar a tecla CTRL. Boolean false
onSelectLine Define uma função que será executada ao selecionar alguma linha.
Callback retorna os dados da linha selecionada. 		Function
(Callback)
click Define uma função que será executada ao clicar em alguma linha.
Callback retorna os dados da linha selecionada. 		Function
(Callback)
dblClick Define uma função que será executada ao dar um duplo clique em alguma linha.
Callback retorna os dados da linha selecionada. 		Function
(Callback)
enter Define uma função que será executada ao pressionar enter em alguma linha.
Callback retorna os dados da linha selecionada. 		Function
(Callback)
keySelectUp Define um array com teclas que ao serem pressionadas (individualmente) irão selecionar uma linha acima. Array of Integer
keySelectDown Define um array com teclas que ao serem pressionadas (individualmente) irão selecionar uma linha abaixo. Array of Integer

onKeyDown Armazena funções que executam determinada ação ao pressionar uma tecla desejada na linha do grid.
As funções possuem dois parâmetros de callback:
O primeiro retorna todos os campos e valores daquela linha.
O segundo retorna o evento keydown do DOM. 		Object 
    const grid = new xGridV2.create({
        onKeyDown: {
            70: (ln,e) => {
                alert('Letra F pressionada');
            },
            'ctrl+13': (ln,e) => {
                alert('CTRL + Enter pressionado');
            },
        },
    })
A chave do objeto deve ser o keyCode da tecla que deseja monitorar.
Pode combinar as palavras ctrl, alt e shift com um sinal de '+' .

Compare Armazena funções que serão utilizadas em uma ou mais colunas para editar seu conteúdo.
As funções possuem um parâmetro de callback que retorna todas as colunas e seus valores, e uma propriedade value que retorna o valor da coluna que está sendo executada a função. 		Object 
    const grid = new xGridV2.create({
        compare: {
            'joinName': (r) => {
                return r.firstName + r.lastName;
            },
        },
        columns: {
            'name' : {dataField: 'firstName', compare: 'joinName'},
        }
    })

Columns Define as colunas que serão apresentadas no grid e como será personalizado os dados daquela coluna.
Caso não seja informado o componente irá considerar todas as colunas que vierem nos dados que serão adicionados ao grid.		 Object 
           const grid = new xGridV2.create({
                columns: {
                    'First Name': { propriedades },
                    'Last Name': { propriedades }
                }
            })
             
            columns: {Name: {dataField: 'NAME', width: '100%'},}
A chave das columns serão usadas como título das colunas no grid.
Propriedade Descrição Tipo Default
dataField Nome da chave que representa aquela coluna no objeto de dados. String
width Tamanho da coluna em porcentagem. ex.: '15%' String
class Adiciona a(s) classe(s) na coluna. ex.: 'classA classB' String
style Adiciona um estilo na coluna. ex.: '{color: red; font-size: "16px"}' String
center Centraliza o texto da coluna. Boolean False
right Alinha o texto da coluna à direita. Boolean False
render Recebe uma função com um parâmetro callback (valor da coluna), processa o valor e o return da função é mostrado.
columns: {
    'Data': {dataField: 'DATA', render: formatDateBR},
        }
 Function
(Callback)
compare Informa o nome da função fornecida em compare do create que deseja aplicar a esta coluna. 
grid = new xGridV2.create({
    columns: {'Name': {dataField: 'NAME', compare: 'reverse'},},
    compare: {'reverse': (r)=>{
        return r.value.split('').reverse().join('');
    }}
})
 String

Filter Define regras que serão utilizadas no filtro interno do grid quando executar o método filter. Object 
   grid = new xGridV2.create({
            filter: {
                filterBegin: false,
                fieldByField: {conditional: 'OR'},
                concat: {
                    fields: [],
                    conditional: 'OR'
                }
            },
        })
Propriedade Descrição Tipo Default
filterBegin O texto pesquisado tem que ser igual ao texto inicial da(s) coluna(s) Boolean False
fields Array com o nome das colunas (dataField) em que deseja que a pesquisa seja realizada.
Se não for informado irá pesquisar em todas as colunas. 		Array [ ]
conditional Operador que determina se a pesquisa deve atender todas as colunas informadas ('AND') ou se deve atender pelo menos uma das colunas ('OR')
 String 'OR'

query Configura o componente para uma pesquisa com paginação. Object 
grid = new xGridV2.create({
    query: {
        endScroll: 0.1,
        execute: async (r) => {
            let result = await fetch('https://www.googleapis.com/books/v1/volumes
            ?q=' + r.param.desc + '&startIndex=' + r.offset + '&maxResults=' + r.param.maxItem )
            .then(response => {
                return response.json();
            })
            grid.querySourceAdd(result.items);
        }
    }
})


grid.queryOpen({ desc: 'sherlock', maxItem: 20 })
** Ao usar o query iniciar a busca dos dados com o método queryOpen() .
A função chamada em execute quando processada tem que adicionar os dados no grid através do método querySourceAdd() .
Propriedade Descrição Tipo Default
endScroll Percentual correspondente a posição restante da barra de rolagem que buscará novos dados. Object 0.1
execute Função a ser executada para consultar novos dados, pode consumir um banco de dados, API, etc.

É executada sempre quando chegar no percentual da barra de rolagem determinada em endScroll.

A função possui um parâmetro callback que é um objeto contendo:
offset: A posição onde deve iniciar a pesquisa. O índice do primeiro item é 0.
page: A página onde será feita a pesquisa. O índice da primeira página é 1.
param: Objeto contendo informações adicionais para serem utilizadas na pesquisa. 		Function
(Callback)		 Undefined

sideBySide Possibilita vincular as colunas do grid com os elementos do formulário (input, checkbox, textarea, etc..). Object 
       const grid = new xGridV2({
                sideBySide: {
                    el: '#myForm'
                }
            })
            
O vínculo só é feito se o name dos elementos (input, etc..) for igual ao dataField de columns.
Propriedade Descrição Tipo Default
el (Obrigatório) Informe o id ou class do form ou div dos elementos de entrada. String Undefined
vModel Recebe um objeto com os campos que seram injetodos nos campos v-text do vuetify 
                    #exemplo do vue#
                    data() {
                        return {
                            fields: {
                                name: "",
                                cpf: ""
                            },
                        }
                    ###
                    vModel: this.fields,
Object
vRefs Os refs do vue onde o xgrid fará o controle do fields 
                     vRefs: this.$refs
Object
render Recebe um objeto, sendo a chave do objeto o 'name' do elemento e o valor uma função callback que recebe o valor do elemento e retorna um valor modificado pela função. 
... sideBySide: {
        el: '#myForm',
        render: {
            name: (value) => {return value.split('').reverse().join('')},
            money: (value) => formatMoney
        }
    },
Object
compare Recebe um objeto, sendo a chave do objeto o 'name' do elemento e o valor o nome da função fornecida em compare do create. 
grid = new xGridV2.create({
    compare: {'joinName': (r)=>{
        return r.firstName + ' ' + r.lastName;
    }},
    sideBySide: {
        el: '#myForm',
        compare: {
            firstName: 'joinName',
        }
    }
})
 Object
frame Possibilita a criação de botões que estarão vinculados com o formulário. Object 
            const grid = new xGridV2.create({
                sideBySide:{
                    frame: {
                        el: '#divButtons',
                        buttons: {
                            ...
                        }
                    }
                }
            })
Propriedade Descrição Tipo Default
el
(Obrigatório)		 Id ou classe do elemento onde serão criados os botões. String
class Informa uma classe para o container. String
style Informa uma css para o container. String
buttons Lista de objetos contendo os botões que serão criados. Object 
                    frame: {
                        el: '#divButtons',
                        buttons: {
                            insert: {
                                html: 'Incluir',
                                state: xGrid.state.insert,
                                class: 'btnInsert',
                                click: ()=>{ ... },
                            },
                            ...
                        }
                    }
Ao clicar nos botões com state (insert, update), os fields são habilitados e os botões com state (update, cancel) são desabilitados. O contrário também se aplica.
Propriedade Descrição Tipo Default
html Texto que será exibido no botão. String
state Propriedade para controlar qual o tipo do botão sendo utilizado.
state.insert, state.update, state.delete, state.save e state.cancel
 state
class Fornece uma classe para o botão. String
style Fornece uma estilo para o botão. String
click Recebe uma função que será executada ao clicar no botão. Possui um callback que retorna os dados da linha selecionada. Function
(callback)
duplicity Ao sair de um elemento verifica se o seu valor já está sendo utilizado em outro registro. Object 
 duplicity: {
            dataField: ['id'],
            execute: async (r) => {
                let result = await fetch('https://www.googleapis.com/books/v1/volumes?
                q=' + r.value + '&maxResults=1')
                    .then(response => {
                        return response.json();
                    })
                if (result.totalItems > 0) {
                    grid.showMessageDuplicity('O campo ' +r.text+ ' está com valor duplicado!')
                    grid.focusField(r.field);
                }
            }
        },
Propriedade Descrição Tipo Default
dataField Array contendo os nomes dos fields que deseja verificar se há duplicidade. Array of String
execute Função a ser executada para verificar se o dado está duplicado.
É executada sempre quando o elemento do formulário perde o foco.
Possui um parâmetro callback que retorna um objeto contendo:
field: Nome do dataField do campo.
value: Valor alterado no elemento.
text: Texto do elemento anterior ou placeholder. 		Function
(callback)

Métodos

Esses métodos serão utilizados no grid instanciado. Ex.:

    grid.deleteLine(1);
Método Parâmetro Descrição
source source: Array of Object Preenche o grid com os dados passados via parâmetro.
sourceAdd source: Array of Object Insere os dados passados via parâmetro no grid.
dataSource nenhum Retorna os dados da linha selecionada.
Caso nenhuma linha tenha sido selecionada, retorna false.
dataSource field: String Retorna o valor da coluna informada por parâmetro na linha selecionada.
dataSource field: String
value: String		 Altera o valor da coluna informada pelo valor passado, na linha selecionada.
data nenhum Retorna todos os dados armazenados no grid.
getColumns nenhum Retorna as informações da propriedade 'columns' do grid.
getCompare nenhum Retorna as informações da propriedade 'compare' do grid.
focus numLine: Integer Foca na linha informada. Primeira linha iniciada por 0.
disable callback: Function
(Optional)		 Desabilita o grid, executa a função callback caso tenha sido passada.
enable callback: Function
(Optional)		 Habilita o grid, executa a função callback caso tenha sido passada.
clear callback: Function
(Optional)		 Apaga os dados do grid (visual). Os dados permanecem armazendados no grid. Executa a função callback caso tenha sido passada.
load nenhum Mostra uma mensagem de loading no grid.
load text: String Mostra a mensagem fornecida como um loading no grid.
load text: String,
callback: Function 		Mostra a mensagem fornecida como um loading no grid. Executa a função callback fornecida.
closeLoad callback: Function
(Optional)		 Oculta a mensagem de loading do grid. Executa a função callback caso tenha sido passada.
getIndex nenhum Retorna o índice da linha atual. A primeira linha se inicia com 0.
deleteLine index: Integer
(Optional)		 Deleta a linha informada, caso não informe a linha, será deletado a linha selecionada.
Essa função tem como retorno os dados da linha deletada.
insertLine param: Object Insere uma linha com os dados passados no final do grid.
sumDataField field: String Retorna a soma total da coluna informada.
queryOpen param: Object,
callback: Function
(Optional) 		Faz uma consulta inicial com base na propriedade query. As demais consultas são feitas com paginação através da query. Executa uma função callback caso tenha sido fornecida. (query)
querySourceAdd source: Array of Object Adiciona os dados passados no grid. (query)
focusField name: String Foca em um campo específico do formulário. (sideBySide)
filter filter: String,
callback: Function (Optional) 		Pesquisa e filtra no grid o texto passado. A pesquisa obedece a condição informada na propriedade filter.
Executa uma função callback caso tenha sido fornecida, essa função callback têm como parâmetro de retorno a quantidade de linhas encontradas. (filter)
filter filter: Object,
callback: Function (Optional) 		Pesquisa nas colunas informadas os respectivos valores informados. Ex.:
grid.filter({name: 'Robert' lastName: 'Drummond'})
A pesquisa obedece a condição informada na propriedade filter.
Executa uma função callback caso tenha sido fornecida, essa função callback têm como parâmetro de retorno a quantidade de linhas encontradas. (filter)
setFilterBegin filterBegin: Boolean Altera a propriedade filterBegin do filter. (filter)
setFilterConditional conditional: String Altera a propriedade conditional do filter. (filter)
disableBtnsSaveCancel disable: Boolean Desabilita/Habilita os botões salvar e cancelar de acordo com a informação passada. (frame)
disableFieldsSideBySide disable: Boolean Desabilita/Habilita os campos do formulário. (sideBySide)
getElementSideBySideJson toUpperCase: Boolean,
empty: Boolean 		Retorna os valores dos campos do formulário no formato JSON. (sideBySide)
getDiffTwoJson toUpperCase: Boolean Retorna um objeto contendo os valores antigos e novos dos campos alterados no formulário.
{objOld: [name: 'Robert'], objNew: [name: 'Roberty']} (sideBySide)
clearElementSideBySide nenhum Limpa os campos do formulário. (sideBySide)
print headHTML: String (Optional) Imprime os dados do grid. É possível passar um cabeçalho para impressão via parâmetro.
getDuplicityAll nenhum Chama a função execute de duplicity dos fields informados. Essa função retorna uma Promise
showMessageDuplicity text: String Mostra uma mensagem de alerta!
setKeySelectUp keyCode: Integer Adiciona a opção de selecionar a linha acima com a tecla informada.
setKeySelectDown keyCode: Integer Adiciona a opção de selecionar a linha abaixo com a tecla informada.

Desenvolvedores

Francisco Alves
Guilherme Trindade