Função

A fonte de dados normalmente é utilizada para fazer a comunicação entre os dados persistidos (ex.: banco de dados) e a tela na qual o usuário realiza alguma interação. Ela permite tratar os dados em componentes visuais, relatórios, sistema BPM e gerar requisições REST dentro ou fora da aplicação. A fonte de dados utiliza a tecnologia OData para trafegar os dados e pode ser alimentada por uma consulta JPQL ou bloco de programação. Esses fatores garantem a interoperabilidade e integração entre as camadas do sistema.

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. 

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

Principais propriedades e eventos 

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:

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

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

Origem dos Dados

A propriedade Origem dos Dados permite selecionar uma entidade do sistema, criar ou selecionar uma fonte de dados existente. Não é possível personalizar uma consulta diretamente da entidade. Nesse caso, é necessário criar uma fonte de dados alimentada pela entidade desejada e personalizá-la.

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

1. Coluna nome: exibe os nomes das fontes de dados e entidades.
2. Coluna Tipo: informa se o item é uma fonte de dados ou entidade.
3. Erro: quando uma fonte de dados possui algum erro de configuração, um ícone de alerta é exibido. Posicione o cursor do mouse sobre o ícone para exibir um tooltip com informações do problema.
4. Editar: abre a janela de edição do item, disponível apenas para os tipos fonte de dados.
5. Manter compatibilidade com Cronapp 1.0: item destinado a manter a compatibilidade do projetos criados na versão 1.0 do Cronapp com a versão atual.

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 único da fonte de dados no sistema. 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. Copiar URL: copia o URN da fonte de dados.
3. Sinalização de Erro: ao detectar erro nas configurações da fonte de dados, um ícone de alerta é exibido. Posicione o curso do mouse sobre o ícone para exibir um tooltip com informações do problema.
4. Nome da consulta: nome que identifica a consulta para o programador no momento da seleção das fontes de dados.
5. Tipo da fonte: define se a fonte de dados estará vinculada a uma entidade ou um bloco de programação.
6. 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.
7. Entidade base: esse campo só é ativo para fontes do tipo Bloco de programação e é necessário para definir o mapa da entidade.
8. Auditoria em Log: habilita o sistema de auditoria para essa fonte de dados. Acesse a documentação Log de Auditoria para mais detalhes.
9. Aba Filtro: define uma consulta JPQL ou parâmetros da função dos blocos de programação.
10. Aba Permissões: define permissões para os verbos HTTP.
11. Aba Eventos: chama ações em diversos momentos da execução da fonte de dados.
12. Aba Campos: altera o valor de cada campo e dá permissões diferenciada aos permissionáveis.
13. Aba Campo calculados: adiciona novos campos ao mapa retornado da fonte de dados.
14. Aba Tratamento de erros: adiciona mensagens de erros personalizadas, permite internacionalização dessas mensagens.

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 de programação, 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;

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

Eventos

Com os eventos, é possível executar algum método antes ou após a fonte de dados executar uma ação. Existem alguns eventos parecidos, mas que se comportam de forma distintas. Veremos abaixo a diferença entre os eventos da fonte de dados e os eventos do componente visual fonte de dados.

Eventos da fonte de dados

Permite a execução de uma função ao realizar uma ação de CRUD e Filtro. Por exemplo, é possível utilizar os eventos Antes de inserir e Antes de atualizar para validar os campos CPF ou e-mail em um formulário.

Esses eventos estão localizados na aba Eventos (Figura 3.5) e serão executados independente que quem está requisitando a fonte de dados. Essa configuração é feita diretamente nas configurações da fonte de dados, no servidor do sistema, e só é possível selecionar funções do tipo servidor.

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 algum dado;
• Antes, Depois de Deletar: realiza o evento antes ou após deletar algum dado;
• Antes, Depois de Atualizar: realiza o evento antes ou após a atualização de algum dado;
• Ao navegar: executa a ação ao abrir e ao navegar entre os elementos da fonte;
• 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.

Eventos do componente visual fonte de dados

São eventos JavaScript relacionados apenas ao componente visual fonte de dados (mobile ou web) e aceitam funções cliente ou servidor. Esses eventos só serão executados se a requisição à fonte de dados for feita a partir do componente visual na tela. Dessa forma, uma fonte de dados configurada para gerar uma serviço REST não executará esses eventos. Eles são inseridos na aba lateral Eventos (Figura 3.6).

Figura 3.6 - Eventos do componente Fonte de dados

Na tabela abaixo é possível visualizar os principais eventos do componente visual fonte de dados. Para mais informações sobre outros eventos, acesse o tópico Eventos da fonte de dados em Eventos dos componentes visuais.

Lançar exceção

Os Eventos do menu lateral do componente fonte de dados (Figura 3.6) são eventos JavaScript e não podem ser interrompidos. Já os eventos internos da janela da fonte de dados (Figura 3.5) são eventos do Odata, o que significa que uma exceção pode ser adicionada para paralisar o processo. Essas exceções são eventos que quebram o fluxo normal das instruções. Ao lançar uma exceção será exibida uma mensagem na saída do console (Figura 3.7) uma notificação de erro na aplicação.

Na Figura 3.7, fizemos um exemplo onde um usuário que inserir uma data de nascimento indicando uma idade menor que 18 anos idade não poderá se cadastrar.

Figura 3.7 - Bloco para lançar exceção

Na Figura 3.8, lançamos a exceção no evento Antes de Inserir da nova fonte de dados Gerenciador de Participantes. Como o evento executa uma ação antes de inserir um dado na fonte de dados e a exceção paralisa o processo, o dado não será cadastrado.

Figura 3.8 - Lançando exceção no evento Antes de Inserir

Veja mais detalhes no tópico Parâmetros.

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.

Campo calculados

Adiciona novos campos a entidade da fonte de dados. Diferentemente da aba Campos, aqui 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

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.

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