Skip to end of metadata
Go to start of metadata

Função

Alimenta os componentes visuais (mobile ou web) com dados de uma consulta personalizada de banco de dados, OData ou bloco de programação. A fonte de dados também permite adicionar filtros, permissões de acesso, adicionar novos campos, tratamento de erros e outras funcionalidades.

Uso

Todo componente que necessita de uma fonte de dados possui uma propriedade Origem dos dados ou Configurações onde é possível selecionar uma fonte de dados já existente ou criar uma nova. Uma mesma Fonte de dados pode ser usada por um ou mais componentes ao mesmo tempo  Na Figura 1.1 temos o componente Caixa de seleção múltipla (2) e o ícone da Fonte de dados (1) que alimenta a lista da caixa de seleção.

Dica

O ícone da fonte de dados deve estar sempre acima do(s) componente(s) visual(is) no(s) qual(is) ele está associado na tela de edição da view, podendo cada fonte de dados estar logo acima do componente (exemplo Imagem abaixo) ou todos juntos no inicio da view.


O ícone de fonte de dados só é exibido no momento de edição da view, caso não queira visualizar esses ícones no momento da edição, basta clicar no botão Exibir elementos não visuais (3) para ocultar ou exibir.

Figura 1.1 - Ícone fonte de dados (1) na tela de edição da view

 

Nem sempre é necessário arrastar o componente Fonte de dados para a janela de edição da view, ao definir uma fonte de dado nas propriedades Origem dos Dados ou Configuração de algum outro componente, o ícone é criado automaticamente acima do componente editado na janela de edição da view.

Acesso as propriedades

As propriedades de configuração de uma fonte de dados podem ser acessadas através do menu lateral ao selecionar o componente na tela de edição da view, como na Figura 1.2, ou nos casos de componentes que possuem janelas de configurações próprias, é possível acessar essas propriedades diretamente através dessas configurações. Veja o exemplo das configurações da fonte Cidade nas Opções da Grade na Figura 1.3.

Figura 1.2 - Acesso as propriedades através do menu lateral da janela de edição do formulário



Figura 1.3 - Acesso as propriedades através da janela de configurações do componente Grade

Principais propriedades e eventos 

NomePropriedadeFunção
Filtros e Parâmetros

condition

Cria filtros para a fonte de dados.
Depende dedependent-byVincula a fonte de dados principal com outras fontes de dados. Ao usar algumas propriedades (ex: Mestre Detalhe), esse campo é preenchido automaticamente.
NomenameNome do componente fonte de dados na view.
Postergar CargalazySó alimenta a fonte de dados após uma ação do usuário.
Mestre DetalheparametersVincula um ou mais atributos da fontes de dados com outra fonte.
Origem dos DadosentityDefine a origem dos dados: Entidade ou consulta personalizada.
Ordenaçãoorder-byOrdena o conteúdo da fonte de dados.

Dependente de salvamento

dependent-lazy-postAguarda a seleção da fonte de dados selecionada nessa propriedade para realizar a ação da fonte de dados principal.
Linhas por páginarows-per-pageRetorna a quantidade de dados informada para realizar paginação na exibição dos dados.

Validar Campos Requeridos

checkrequiredSó insere ou atualiza os dados se todos os campos marcados como requeridos estiverem preenchidos.
ChaveskeysExibe as chaves primárias de todas as entidades atribuídas na fonte de dados.

Estratégia em Cláusula Nula

parameters-null-strategyDefine como o sistema deve tratar parâmetros nulos da fonte de dados;

Filtros e Parâmetros

Com o Filtros e Parâmetros é possível adicionar grupos de regras e agrupá-los com outros grupos usando conectivos lógicos (e / ou). Regras podem ser criadas a partir de expressões, campos da tela, conteúdo estático ou blocos de programações.


Figura 2.1 - Janela de Filtros e Parâmetros

  1. Configuração do Grupo: define o condicional entre suas regras e outros grupos; 
  2. Campo de seleção de condicional (e / ou) do grupo;
  3. Adicionar nova regra a esse grupo;
  4. Adicionar novo grupo filho;
  5. Excluir grupo (não é possível excluir o primeiro grupo da hierarquia);
  6. Configuração da Regra: define um elemento de comparação entre um atributo da fonte de dados e outro elemento;
  7. Selecionar o atributo da fonte de dados;
  8. Selecionar o operador de comparação (=; ≠; <; >; <= ou >=);
  9. Selecionar o tipo do que será comparado: expressão, booleano, String e outros;
  10. Campo para informar o que será comparado: expressões, data, String, bloco de programação ou outros;
  11. Abre uma nova janela para informar uma expressão, selecionar um bloco de programação ou um campo na tela que será exibido no campo 10;
  12. Excluir regra;

Figura 2.2 - Exemplo de uso da propriedade Filtros e Parâmetros


No exemplo da Figura 2.2, a sintaxe de comparação pode ser lida da seguinte forma:

Sintaxe da Figura 2.2
(email = 'pedro.porto@email.com') AND ((name = cronapi.client('js.blockly.BlocoCliente.Funcao').attr().run()) OR (login = 'pedro.porto'))

A expressão cronapi.client('js.blockly.BlocoCliente.Funcao').attr().run() se trata do retorno de uma função de bloco de programação, ao selecionar essa função no botão (11) da Figura 2.1, o sistema preenche o endereço e a chamada da função.

Ordenação

A ordenação ocorre selecionando um ou mais campos da fonte de dados e definindo a ordem (acedente ou descendente).


Figura 2.3 - Ordenação do campo 'name' em ordem crescente.

  1. Adiciona uma nova ordenação;
  2. Seleciona o campo da fonte de dados que será o ordenador;
  3. Define se a ordenação será ASCendente ou DESCendente.

Mestre Detalhe

A propriedade Mestre detalhe gera uma ligação entre um ou mais parâmetros da fonte de dados com outra fonte, como: expressões, campos na tela ou bloco de programação.


Figura 2.4 - Ligação entre o atributo id da fonte de dados e o id de outra fonte de dados da view


  1. Adiciona uma nova ligação;
  2. Seleciona o atributo da fonte de dados principal;
  3. operador de comparação igual (único possível);
  4. Selecionar o tipo do que será comparado: expressão, booleano, String e outros;
  5. Atributo da fonte filho, que pode ser: expressões, bloco de programação, campo da tela ou outros;
  6. Abre uma nova janela para informar uma expressão, selecionar um bloco de programação ou um campo na tela. A seleção será exibida no campo (5);
  7. Excluir a ligação.

Origem dos Dados

A propriedade Origem dos Dados seleciona uma fonte de dados editável ou um OData de uma entidade do sistema. Edições só são possíveis em fonte de dados, OData não são editáveis.

É possível criar uma nova fonte de dados através do botão Nova fonte de dados ou através do menu do sistema, ver em Criar ou editar consultas de Fonte de dados.

 

Figura 2.5 - Seleção de uma fonte de dados ou entidade

  1. Cria uma nova Fonte de Dados;
  2. Nomes das fontes de dados ou entidades;
  3. Tipo da fonte de dados;
  4. Abre janela de edição para os tipos Fonte de dados.

Criar ou editar consultas de Fonte de dados

Existem duas formas de criar uma nova fonte de dados ou editar uma já existente: através da propriedade Origem dos dados de algum componente que utiliza fontes de dados ou pelo menu do sistema, acessando Projeto > Fonte de dados (Figura 3.1). 

Uma mesma fonte de dados pode ser usada por diversos componentes em telas distintas do sistema.

 
Figura 3.1 - Acesso as fontes de dados pelo menu do sistema

Edição da Fonte de dados

Na janela de edição da fonte de dados são inseridos identificadores, a origem da fonte e várias configurações de personalização da fonte de dados.

Figura 3.2 - Janela de edição da fonte de dados


  1. Identificador: identificador da fonte de dados no sistema. Essa consulta da fonte de dados ficará armazenada no arquivo customQuery.json (localizado em Código Fonte / Principal / Código Fonte Servidor / META-INF / ) utilizando esse identificador;
  2. Nome da consulta: nome que identifica a consulta para o programador no momento da seleção das fontes de dados;
  3. Tipo da fonte: define se a fonte de dados estará vinculada a uma Entidade ou Bloco de programação;
  4. Origem da fonte: seleção de um bloco de programação ou entidade OData;
    • campo: exibe a entidade ou bloco de programação selecionado;
    • "…": abre janela de seleção de entidade ou bloco de programação;
    • Novo Bloco de programação: Abre uma janela para a criação de bloco de programação;
    • Excluir: limpa a seleção do bloco de programação ou entidade;
  5. Entidade base: Esse campo só é ativo para fontes do tipo Bloco de programação e é necessário para definir o mapa da entidade;
  6. Aba Filtro: define uma consulta JPQL ou parâmetros da função do blocos de programação;
  7. Aba Permissões: define permissões para os verbos HTTP;
  8. Aba Eventos: chama ações em diversos momentos da execução da fonte de dados;
  9. Aba Campos: alterar o valor de cada campo e dá permissões diferenciada a grupos;
  10. Aba Campo calculados: adiciona novos campos ao mapa retornado da fonte de dados;
  11. Aba Tratamento de erros: adicionar mensagens de erros personalizadas, permite internacionalização dessas mensagens.

 

Dica

O endereço na Lateral do identificador, (1) da Figura 3.2, é um URI REST e possui sintaxes diferentes dependendo do tipo de fonte: 

  1. Entidade: <domínio_do_sistema>/api/cronapi/odata/v2/<Identificador>/<parametro1>/.../<parametroN>/
  2. Bloco de programação: <domínio_do_sistema>/api/cronapi/query/<Identificador>/<parametro1>/.../<parametroN>/

Filtro

Essa aba é responsável por determinar o conjunto de dados que o DataSource irá retornar. Em fontes do tipo entidade é possível filtrar por consultas JPQL (1), essa opção fica desabilitada para blocos de programação, que apenas exibirá o nome dos parâmetros do bloco, caso tenha.

No exemplo da Figura 3.3 a fonte de dados retornará todos os usuários que possuem e-mails de um servidor específico selecionado pelo usuário, a função de bloco de programação ObterValorDropdownEmail retorna o conteúdo informado pelo usuário na tela.

Figura 3.3 - Exemplo de filtro para uma entidade

 

  1. Consulta JPQL: exibe a consulta JPQL criada (Só habilitado quando a fonte está vinculado a uma entidade);
  2. Editar: abre uma janela para a criação de consulta JPQL em modo visual (Só habilitado quando a fonte está vinculado a uma entidade);
  3. Nome do parâmetro: nome do parâmetro gerado por uma regra de consulta JPQL ou parâmetros do Bloco de programação;
  4. Valor do Parâmetro: define o valor através de uma String ou retorno de um bloco de programação, por exemplo a obtenção do conteúdo de um campo na tela;
  5. "…": seleciona uma função de bloco para ser a fonte desse campo;
  6. Novo bloco: cria novo bloco de programação e uma função;
  7. Limpar: apaga a dado informado no campo;

Permissões

Em permissões é possível definir algum método para executar no lugar dos verbo HTML padrões (get, post, put, delete) da entidade base. Na Figura 3.4 será executado a função Metodo2 no lugar do get da Entidade base User.

Fontes do tipo Entidade não podem selecionar uma função de bloco para realizar esse tratamento, apenas definir permissões para os grupos.


Figura 3.4 - Aba Permissões configurada para chamar um evento na ação get


  1. Permissão do verbo: ativa ou desativa cada um dos verbos HTML;
  2. Método do bloco a utilizar: seleciona uma função de bloco de programação que será executado no momento de execução de um dos verbos (disponível apenas para fonte de dados do tipo bloco de programação);
  3. Permissão: define os grupos de acesso com permissões a executar esses verbos.


Eventos

Permite a execução de um método no momento da execução de algum item de CRUD e Filtro.


Figura 3.5 - Seleção de uma fonte de dados ou entidade

  1. Ações: momentos em que os eventos serão executados;
  2. Campo: exibe as funções de blocos selecionada para cada etapa;
  3. "…": abre a janela para seleção da função;
  4. Criar bloco: cria novo bloco de programação com uma função;
  5. Limpar: exclui os dados do campo.

Campos

A aba Campos exibe todos os atributos (campos) da entidade base selecionada, permitindo tratar cada campo de forma individual, definindo valores estáticos ou dinâmicos, e adiciona novos campos ao mapa retornado. A adição de novos campos só é possível para fontes do tipo bloco de programação, fonte do tipo entidade só é possível alterar o valor dos campos existentes na entidade.

Não é permitido adicionar um novo campo para fontes de dados do tipo Entidade, este também não possui as configurações de banco de dados, itens (6), (7) e (8) da Figura 3.6. 


Figura 3.6 - Aba campos e as várias configurações para os campos da entidade base


  1. Nome do campo: nome do campo a ser adicionado (exclusivo para fonte de dados do tipo bloco de programação);
  2. Adicionar campo: insere um campo a mais em relação aos da entidade base (exclusivo para fonte de dados do tipo bloco de programação);
  3. Nome dos campos: coluna com o nome dos campos da entidade base e os novos adicionados;
  4. Tipo da fonte do campo: define o tipo que será gerado para o valor do campo;
  5. Valor do campo: fonte do valor do campo;
  6. Tipo do campo: define o tipo do campo que irá alimentar um banco de dado, por exemplo;
  7. Permite nulo: define se o campo poderá ter valores nulos;
  8. Chave primária: define se o campo é uma das chaves primárias da entidade;
  9. "…": seleciona uma função de bloco para ser a fonte desse campo;
  10. Novo bloco: cria novo bloco de programação e uma função;
  11. Permissões: define varias permissões a determinados grupos (perfis) cadastrado no sistema;
  12. Limpar: apaga a cadastrada no campo;
  13. Excluir: exclui o campo;

Campo calculados

Adiciona novos campos a entidade da fonte de dados. Diferente a aba Campos, nessa aba, os campos e seus valores não são persistidos, existem apenas para uso temporário na aplicação.

Figura 3.7 - Aba de campos calculados

 

  1. Nome do campo: nome do campo a ser adicionado;
  2. Adicionar campo: insere um campo;
  3. Nome dos campos: coluna com o nome dos campos calculados que foram adicionados;
  4. Tipo da fonte do campo: define o tipo que será gerado para o valor do campo;
  5. Valor do campo: fonte do valor do campo;
  6. Tipo do campo: tipo Java para o valor do campo;
  7. "…": seleciona uma função de bloco para ser a fonte desse campo;
  8. Novo bloco: cria novo bloco de programação e uma função;
  9. Permissões: define varias permissões a determinados grupos (perfis) cadastrados no sistema;
  10. Limpar: apaga os dados fornecidos para o campo;
  11. Excluir: exclui o campo;

Tratamento de erros

Se o sistema não encontrar algum item exibirá uma mensagem para o usuário, sendo possível internacionalizar essas mensagens.

Na Figura 3.7, o campo está com uma chave de internacionalização atendendo dois ou mais idiomas.

Figura 3.8 - Aba tratamento de erro

 

  1. Campo Erro de chave primária: mensagem informada ao usuário quando não for possível encontrar algum item no banco;
  2. Campo Erro de chave estrangeira: mensagem informada ao usuário quando não for possível encontrar algum item no banco através do uso da foreign key
  3. Internacionalização: Abre a janela de internacionalização da mensagem;
  4. Limpar: exclui o conteúdo preenchido no campo.


Nessa página

Compatibilidade

Formulário web

Formulário mobile
Botão do componente

Imagem no Editor Visual

 

  • No labels