Versões comparadas

Versão antiga 83

changes.mady.by.user Igor Andrade

Gravado em

comparado com

Nova versão 84

changes.mady.by.user Igor Andrade

Gravado em

Chave

  • Esta linha foi adicionada.
  • Esta linha foi removida.
  • A formatação mudou.

Função

Com a fonte de dados do Cronapp é possível alimentar os componentes visuais, relatórios e gerar requisições REST dentro ou fora da aplicação. Os dados são obtidos por meio de uma consulta personalizada de banco de dados - através de OData, do bloco de programação ou de uma API, garantindo a interoperabilidade do sistema e permitindo a integração entre as camadas do sistema.

É possível adicionar filtros, inserir permissões de acesso, adicionar novos campos, incluir tratamento de erros e outras funcionalidades na fonte de dados.

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 Fonte de dados (destaque 1 da Figura 1.1) que alimenta a lista do componente  Caixa de seleção múltipla (destaque 2).

Informações
titleDica

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 (Figura 1.1) ou todos juntos no início 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 exibi-lo novamente.


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 área de edição da view - como na Figura 1.2, ou através das janelas de configurações de outros componentes - como mostrado 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

Âncora
PrincipaisPropriedades
PrincipaisPropriedades

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.
Postergar CargalazyAlimenta a fonte de dados somente após uma ação do usuário.
Mestre DetalheparametersVincula um ou mais atributos de uma fonte de dados com outra fonte de dados.
Estratégia para Carregar Dadosload-data-strategy

Escolhe as condições de carregamento dos dados, que são:

  • Padrão: comportamento atual da fonte de dados;
  • Todos os Filtros Preenchidos: carrega automaticamente quando todos os filtros forem preenchidos;
  • No mínimo um Filtro Preenchido: carrega automaticamente quando pelo menos um dos filtros forem preenchidos;
  • Ao Pressionar Botão: carrega apenas ao click de botão que tenha como ação um bloco de programação chamando a função "Carregar fonte de dados".
Atualizar Automaticamente (ms)auto-refreshDefine o tempo, em milissegundos, que o datasource atualizará automaticamente. Exemplo de uso: chat e thread de fórum colaborativo.
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-postVincula uma fonte de dados para servir como dependente da fonte de dados principal - ou seja, o salvamento da fonte de dados principal dependerá de uma ação na fonte de dados dependente.
Linhas por páginarows-per-pageRetorna a quantidade de dados informada para realizar paginação na exibição dos dados.

Validar Campos Requeridos

checkrequiredInsere ou atualiza os dados somente 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;

Âncora
linkFiltroParametro
linkFiltroParametro

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. Adiciona nova regra a esse grupo;
  4. Adiciona novo grupo filho;
  5. Exclui 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. Seleciona o atributo da fonte de dados;
  8. Seleciona o operador de comparação (=; ≠; <; >; <= ou >=);
  9. Seleciona 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. Exclui 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:

Bloco de código
languagedelphi
themeConfluence
titleSintaxe 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 "..." (destaque 11 da Figura 2.1), o sistema preenche o endereço e a chamada da função.

Âncora
LinkOrdenacao
LinkOrdenacao

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.

Âncora
LinkMestreDetalhe
LinkMestreDetalhe

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. Seleciona 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. Exclui a ligação.

Âncora
LinkSource
LinkSource

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 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.

Âncora
EdicaoSource
EdicaoSource

Consultas da Fonte de dados

É possível criar ou editar uma fonte de dados 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 (web ou mobile) do sistema ou em outras partes - como relatórios e BPMN, 


 
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 / ). O trecho de endereço (URN) ao lado é o endereço de requisições REST da fonte de dados, permitindo gerar uma API, garantindo a interoperabilidade entre os módulos do sistema ou fora dele.
  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 um 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 dos 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: altera o valor de cada campo e dá permissões diferenciada aos permissionáveis.
  10. Aba Campo calculados: adiciona novos campos ao mapa retornado da fonte de dados.
  11. Aba Tratamento de erros: adiciona mensagens de erros personalizadas, permite internacionalização dessas mensagens.


Informações
titleDica

O endereço na Lateral do identificador (destaque 1 da Figura 3.2) é um URI REST e possui sintaxes diferentes dependendo do que está alimentando a fonte de dados: Entidade ou Bloco de programação (3 da figura 3.2): 

  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>/

Âncora
abaFiltro
abaFiltro

Filtro

Essa aba é responsável por determinar o conjunto de dados que a fonte de dados 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, e 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 (habilitado somente quando a fonte está vinculada a uma entidade);
  2. Editar: abre uma janela para a criação de consulta JPQL em modo visual (habilitado somente 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 bloco de programação e uma função;
  7. Limpar: apaga a dado informado no campo;

Âncora
abaPermissoes
abaPermissoes

Permissões

Na aba permissões é possível definir a execução de algum método ao requisitar algum verbo HTTP (get, post, put, delete), filtrar ou contar. Na Figura 3.4 será executado a função Metodo2 no lugar do get da Entidade base User.

Só é possível definir métodos para realizar o tratamento dos verbos (destaque 2 da Figura 3.4) quando a fonte de dados está vinculada a um bloco de programação e o campo Entidade base selecionado. Fonte de dados vinculadas a uma entidade só permitem definir as permissões (3 da Figura 3.4) dos verbos. O verbo contar é usado internamente para paginar os registros retornados, porém, para funcionar, os campos Permitir Obter e Permitir Contar devem ter o mesmo método selecionado.



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 HTTP;
  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 quais permissionáveis podem executar esses verbos.


Âncora
abaEventos
abaEventos

Eventos

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

Utilize os campos Antes de inserir e Antes de atualizar para validar campos como CPF ou e-mail em um formulário, por exemplo.



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


  1. Ações: informa quando 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.

Ações

  • Antes, Depois de Inserir: realiza o evento antes ou após a inserção de alguma informação no banco de dados;
  • Antes, Depois de Deletar: realiza o evento antes ou após deletar alguma informação no banco de dados;
  • Antes, Depois de Atualizar: realiza o evento antes ou após a atualização de alguma informação no banco de dados;
  • Ao navegar: executa a ação ao abrir e ao navegar entre os elementos da fonte;
  • Ao Obter Dados: executa a ação ao obter os dados do banco ou bloco de programação;
  • Ao Gerar Erro: tratamento de erros de qualquer natureza durante o processo de manipulação de dados de uma Fonte de Dados.

Para entender mais sobre quais argumentos utilizar dentro dos seus eventos, acesse o tópico Parâmetros.

Âncora
abaCampos
abaCampos

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 novos campos para fontes de dados do tipo Entidade, também não são exibidas as configurações de banco de dados, colunas (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 bloco de programação e uma função;
  11. Permissões: define restrições aos permissionáveis cadastrados no sistema;
  12. Limpar: apaga a cadastrada no campo;
  13. Excluir: exclui o campo.

Âncora
abaCampoCalculados
abaCampoCalculados

Campo calculados

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

Exemplo de uso: Em uma fonte de dados vinculada a entidade usuários, podemos criar um campo calculado idade, que chama uma função Servidor que obtém o campo data de nascimento do usuário e retorna a sua idade baseado na data atual. Dessa forma, sempre que precisar exibir a idade atual dos usuários, basta chamar o campo idade da fonte de dados para realizar o cálculo automaticamente.   


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 restrições aos permissionáveis cadastrados no sistema;
  10. Limpar: apaga os dados fornecidos para o campo;
  11. Excluir: exclui o campo.


Além disso, a aba campos calculados permitem referenciar atributos da própria entidade ou os atributos de outras entidades relacionadas. 

Um exemplo de uso seria o relacionamento entre as entidades Cidade. Estado e País, no qual a fonte de dados com a entidade Cidade pode ter acesso a qualquer atributo da entidade Estado ou País. Na Figura 3.8, a fonte de dados tem acesso ao atributo região da entidade Estado e ao atributo nome da entidade País. O termo this representa a própria entidade.

Como não existem limites de relacionamentos que podem ser feitos em um banco de dados, por isso o Cronapp limita a lista de atributos até o terceiro relacionamento. Porém, é possível inserir manualmente relacionamentos maiores - Exemplo: this.estado.pais.continente.planeta.distanciaSol.


Figura 3.8 - Campos calculados referenciando atributos de outras entidades relacionadas


Âncora
abaTratamentoErros
abaTratamentoErros

Tratamento de erros

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

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


Figura 3.9 - 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.

Âncora
Parametros
Parametros

Parâmetros

As abas Filtro, Eventos, Campos e Campos calculados permitem que selecionemos um bloco de programação para alimentar filtros, eventos e campos. Caso a função do bloco de programação receba argumentos, é possível passar valores fixos ou dinâmicos, quando selecionamos o Valor do campo como Expressão.


Figura 3.10 - Selecionando argumento para um função de um campo da aba Eventos


Os seguintes parâmetros dinâmicos podem ser passados:

  • NULL: valor nulo;
  • primaryKey: primeira chave primária da fonte;
  • primaryKeys: lista com todas as chaves primárias da fonte;
  • entityName: nome da entidade;
  • eventName: nome do evento (onError);
  • data: objeto da entidade manipulado;

Exclusivos do campo Ao gerar Erro (1 da figura 3.10) da aba Eventos:

  • exception: objeto da exceção;
  • exceptionMessage: mensagem da exceção.

Campo Ao gerar Erro

Podemos usar o campo Ao Gerar Erro da aba Eventos para informar a mensagem da opção exceptionMessage, para que assim, caso ocorra um erro na fonte de dados, o evento Ao Gerar Erro será executado passando a mensagem da exceção para a função (Figura 3.11).


Figura 3.11 - Função usada no campo Ao Gerar Erro da aba Eventos da Fonte de dados

Nome em inglês

Datasource

Nessa página

Índice

Compatibilidade

  • Formulário web
  • Formulário mobile
  • Relatório
  • Web service
  • BPMN

Botão do Componente


Imagem no Editor Visual



...