Função

O componente visual fonte de dados é um recurso cliente utilizado exclusivamente no Editor de views para as páginas das aplicações web e mobile do Cronapp. Ele permite estabelecer uma conexão entre uma Fonte de Dados, criada no lado do servidor, e outros componentes visuais na tela, como Grade, Lista Avançada e vários outros.

Dessa forma, o componente visual fonte de dados necessita ser vinculado com uma Fonte de Dados no servidor (destaque 2 da figura 1) e, em seguida, o mesmo componente visual fonte de dados deve ser associado a um outro componente visual na tela, como a Grade (destaque 1 da figura 1). Todas as requisições de CRUD (criar, ler, atualizar ou deletar) feitas pelo usuário através da Grade serão enviadas ao componente visual fonte de dados por meio do Angular (destaque 1 da figura 1), logo em seguida será repassada para a Fonte de dados servidor via requisição RESTful (ODATA) (destaque 2 da figura 1). Após obter as informações solicitadas, os dados retornarão pelo mesmo caminho até atualizar a Grade.

O componente fonte de dados suporta os 4 tipos de Fonte de dados customizáveis no lado servidor (Bloco de programação, Consulta a Entidades, SQL Nativo e Web Service), além do tipo "Entidade", que não permite customização no lado servidor. Independentemente do tipo vinculado, o componente fonte de dados também oferece várias opções de personalização no lado cliente, como filtros, ordenação e paginação. Essas propriedades são incluídas nas requisições RESTful (ODATA) (destaque 2 da figura 1), permitindo controlar e refinar os resultados de acordo com as necessidades daquela página.

Figura 1 - Fluxo de dados do componente visual Fonte de dados

Uso

Para utilizar o componente fonte de dados no Editor de views, basta arrastá-lo da lista de componentes para a área de edição do formulário (destaque 1 da figura 2), em seguida, a janela Lista de Fontes de dados será aberta para selecionar a Fonte de dados que será vinculada. Nesse momento, o componente fonte de dados já está pronto e qualquer componente visual que utilize fonte de dados possui uma propriedade chamada "Fonte de dados" em que permite selecionar uma das fontes de dados adicionadas na área de edição da página.

Figura 2 - Vinculando uma Fonte de dados ao componente visual fonte de dados 

Em alguns componentes visuais, a fonte de dados é selecionada dentro da janela aberta pela propriedade Configuração, essa janela possui o campo Fonte de dados (destaque 1 da figura 2.1). O botão "+" do campo Fonte de dados (destaque 2 da figura 2.1) permite selecionar diretamente uma Fonte de dados servidor, isso fará com que o Cronapp crie automaticamente um componente visual fonte de dados e faça o vínculo entre o componente em configuração e a Fonte de dados selecionada.

Figura 2.1 - Vinculando um componente visual ao componente visual fonte de dados

O ícone do componente visual fonte de dados deve estar sempre acima do componente visual no qual ele está associado na área de edição da view. Por esse motivo, sempre que um novo componente fonte de dados for adicionado, ele será automaticamente arrastado para o topo da página. Assim, para diferenciar qual fonte de dados está associada a determinado componente, basta selecionar o componente visual na tela (destaque 1 da figura 2.2) e o ícone da fonte de dados associada ficará em destaque (2 da figura 2.2). 

Utilize a opção Exibir elementos não visuais (destaque 3 da figura 2.2) para ocultar ou exibir os ícones dos componentes fonte de dados, melhorando a visualização da página (WYSIWYG).

Figura 2.2 - Destaque dos ícones das fontes de dados

Acesso as propriedades

Como qualquer componente visual, ao selecionar uma fonte de dados na área de edição, suas propriedades serão exibidas no menu lateral Propriedades (destaque 1 da figura 2.3). Porém, algumas dessas propriedades do componente fonte de dados também são acessíveis a partir da janela de Configuração (2) de alguns componentes, como é o caso da janela de Configuração do componente Caixa de seleção dinâmica (figura 2.3). Ao clicar nos botões Adicionar fonte de dados (+) ou Modificar fonte de dados (…) (destaque 3 e 4) do campo Fonte de dados da janela de configurações, será exibida a janela Configuração de Fonte de Dados (5), nela constam algumas das propriedades do componente fonte de dados selecionado. Acesse o tópico Principais propriedades para mais detalhes sobre esses campos.

Figura 2.3 - Acesso as propriedades da fonte de dados através da janela de configurações dos componentes

Principais propriedades

Propriedades

Na tabela abaixo estão descritas as principais propriedades do componente visual fonte de dados.

Eventos

Os eventos listados abaixo são executados pelo componente visual fonte de dados, são eventos clientes que executam em Javascript. Apesar disso, alguns eventos permitem a execução de funções de bloco de programação servidor, porém, a requisição sempre será feita no lado cliente.

Diferente dos eventos abaixo, a Fonte de dados (servidor) possui uma lista própria de eventos que são executados pela Fonte de dados no servidor da aplicação. Esses eventos só executam funções de bloco de programação servidor (acesse o tópico "Eventos" da documentação Fonte de dados para mais detalhes).

Estilos

O componente visual Fonte de dados só é visível em tempo de desenvolvimento, logo, não necessita de campos de estilo.

Filtros e Parâmetros

Através dessa janela é possível preencher os parâmetros presentes na aba Filtro na Fonte de Dados, além de adicionar novos filtros utilizando uma Expressão (destaque 2 da figura 3).

Esses dados serão passados via query string na requisição REST entre o componente visual fonte de dados e a Fonte de dados vinculada. Para cada Parâmetros (destaque 1 da figura 3) será incluída uma "chave=valor" na requisição, já as Expressões (destaque 2 da figura 3) são montadas dentro da chave OData $filter (veja mais detalhes dos parâmetros OData).

A requisição feita pela fonte de dados configurada na figura 3 teria o seguinte formato: 

<URI Fonte de dados>?applicationId=4e03d757-d27d-4e11-a0bc-bc156ce79a21&$filter=email+eq+%27js@email.com%27

As regras definidas na janela de Filtros e Parâmetros funcionam bem e de forma automática para os tipos de Fontes de dados vinculadas diretamente ao banco de dados: Entidade, Consulta a Entidades e SQL Nativo. Nesses casos, será utilizado o condicional E (AND) entre as regras definidas na área de Parâmetros (destaque 1 da figura 3) e Expressão (2 da figura 3).

Os demais tipos possuem características específicas:

• Fonte de dados do tipo Bloco de programação requer o uso do bloco Obter parâmetro da query string com a opção "$filter" na função que alimenta a Fonte de dados para obter as regras definidas na área Expressão (2 da figura 3). Ver mais detalhes no tópico "Parâmetros de Query String" da documentação Fonte de Dados.
• As regras definidas na área Expressão (2 da figura 3) funcionarão para as Fontes de dados do tipo Web Services desde que o recurso que alimenta a Fonte de dados também utilize o padrão OData. Caso contrário, será necessário configurar as ações da Fonte de dados e utilizar, por exemplo, as constantes queryFilter, simpleFilter ou queryParameters (ver mais detalhes no tópico "Constantes" da documentação Fonte de Dados). 

Figura 3 - Janela da propriedade Filtros e Parâmetros

1. Parâmetros: filtros vindos da Fonte de dados. Caso o filtro não seja configurado, o mesmo não será incluído na requisição para a Fonte de dados.
   1. Nome do parâmetro: esse campo exibirá os mesmos campos contidos na aba Filtro da Fonte de dados.
   2. Comparativo: a opção igual ( = ) é a única disponível para esse campo.
   3. Tipo do valor: define o tipo do valor a ser informado no campo 1d da Figura 3. Além dos tipos primários (Texto, Numérico, Lógico...), também é possível escolher a opção "Expressão", nela é possível informar o valor nulo (NULL), qualquer Valor da tela (ng-model) ou uma expressão FTL (veja mais detalhes no tópico "Expressão" em Fonte de Dados).
   4. Valor: campo para informar o valor estático ou dinâmico.
   5. Janela de seleção: abre uma janela com mais opções para selecionar o valor: Expressões, Campos de tela, Bloco de programação e Funções.
   6. Limpar: apaga as configurações do parâmetro selecionado.
2. Expressão: inclui uma ou mais regras no padrão OData na requisição da Fonte de dados.
   1. Grupo: informa o condicional AND (e) ou OR (ou) para o grupo de regras selecionado.
   2. Adicionar regra: inclui nova linha de regra dentro desse grupo.
   3. Adicionar grupo: inclui novo grupo de condicional para o novo conjunto de regras filho.
   4. Remover grupo: apaga a linha do condicional selecionado. Não é possível excluir o primeiro grupo de condicional, se não possuir nenhuma regra vinculada, a expressão será desconsiderada da requisição.
   5. Campo da regra: lista de campos vinculados a Fonte de dados.
   6. Comparativo: opções de comparativo: Menor igual ( <= ), Contém ( ⊃ ), Diferente ( <> ), Menor ( < ) , Igual ( = ), Maior ( > ) e Maior igual ( >= ). 
   7. Tipo do valor: define o tipo do valor a ser informado no campo 2h da Figura 3. Além dos tipos primários (Texto, Numérico, Lógico...), também é possível escolher a opção "Expressão", nela é possível informar o valor nulo (NULL), qualquer Valor da tela (ng-model) ou uma expressão FTL (veja mais detalhes no tópico "Expressão" em Fonte de Dados).
   8. Valor: campo para informar o valor estático ou dinâmico.
   9. Janela de seleção: abre uma janela com mais opções para selecionar o valor: Expressões, Campos de tela, Bloco de programação e Funções.
   10. Remover: apaga a linha de regra selecionada.

A janela exibirá apenas a Expressão (destaque 2 da figura 3) caso a Fonte de dados vinculada não possua parâmetros na aba Filtro. A figura 3.1 apresenta um exemplo de expressão com diversas regras.

Figura 3.1 - Exemplo de expressão da Janela Filtros e Parâmetros

A sintaxe pode ser lida da seguinte forma:

(email = 'pedro.porto@email.com') AND ((name = cronapi.client('js.blockly.Bloco.getName').attr().run() OR (userName = 'pedro.porto'))

* A expressão cronapi.client('js.blockly.Bloco.getName').attr().run() representa a chamada de uma função de bloco de programação cliente.

Ordenação

A janela de ordenação permite definir como os dados serão ordenados a partir de um ou mais campos.

Esses parâmetros serão passados via query string na requisição REST entre o componente visual fonte de dados e a Fonte de dados vinculada e são montados dentro da chave OData $orderby (veja mais detalhes dos parâmetros OData).

A requisição feita pela fonte de dados configurada na figura 3.2 teria o seguinte formato: 

<URI Fonte de dados>?$orderby=theme+asc,userName+desc

As regras definidas na janela de Ordenação funciona bem e de forma automática para os tipos de Fontes de dados vinculadas diretamente ao banco de dados: Entidade, Consulta a Entidades e SQL Nativo.

Os demais tipos possuem características específicas:

• Fonte de dados do tipo Bloco de programação requer o uso do bloco Obter parâmetro da query string com a opção "$orderby" na função que alimenta a Fonte de dados. Ver mais detalhes no tópico "Parâmetros de Query String" da documentação Fonte de Dados.
• A ordenação nas Fontes de dados do tipo Web Services funcionará desde que o recurso que alimenta a Fonte de dados também utilize o padrão OData. Caso contrário, será necessário configurar as ações da Fonte de dados e utilizar, por exemplo, as constantes querySort e querySortOrder (ver mais detalhes no tópico "Constantes" da documentação Fonte de Dados). 

Figura 3.2 - Janela da propriedade Ordenação

1. Adicionar campo de ordenação: inclui um campo na lista.
2. Campo: seleciona um dos campos vinculados a Fonte de dados.
3. Ordenação: define se a ordenação será ASCendente ou DESCendente.
4. Limpar: para limpar a configuração da janela, utilize o ícone Limpar da propriedade.

Mestre Detalhe

Essa propriedade permite fazer a comunicação entre 2 fontes de dados, normalmente vinculadas a 2 entidade diferentes, mas que possuem relacionamento 1 (Master) para N (Detalhe). Isso permite a aplicação de filtros automáticos, de modo que ao selecionar um registro na fonte de dados Mestre, a fonte de dados Detalhe será filtrada automaticamente, exibindo apenas os registros relacionados.

Além disso, o recurso de envio em lote (batch) pode ser utilizado para manipulação de registros. Quando as fontes de dados estão utilizando Grades com a opção Salvar em lote ativada, todas as modificações nos registros dentro da hierarquia do Mestre-Detalhe (por exemplo, entidades como "pai", "filho" e "neto") são armazenadas localmente e enviadas em uma única requisição, realizada pela Grade que representa a fonte de dados Mestre. Isso mantém a unidade das operações e garante a integridade das informações no banco de dados.

O Mestre Detalhe é um recurso do componente visual fonte de dados, dessa forma, é possível representar as fontes de dados envolvidas utilizando diversos componentes visuais diferentes, exemplos:

• Grade (Master) - Grade (Detalhe)
• Caixa de Seleção Dinâmica (Master) - Grade (Detalhe)
• Caixa de Seleção Dinâmica (Master) - Texto Simples (Detalhe)
• Caixa de Seleção Dinâmica - mobile (Master) - Lista Avançada (Detalhe)

O diagrama abaixo apresenta 2 classes, uma trata das Pessoas cadastradas no sistema e outra trata das doações realizadas por essas pessoas. Uma relação de 1 (Pessoa) para N (Doacao).

Figura 3.3 - Exemplo de relacionamento entre entidades

No editor de views, a configuração do Mestre Detalhe é feita a partir da fonte de dados Detalhe. 

Figura 3.4 - Exemplo de relacionamento entre entidades

1. Mestre Detalhe
   1. Adicionar Ligação: inclui uma linha para a seleção dos campos.
   2. Campo detalhe: lista os campos da fonte de dados Detalhe. Selecione o campo que representa a entidade Mestre (atributo de chave estrangeira).
   3. Comparativo: a opção igual ( = ) é a única disponível para esse campo.
   4. Campo valor master: possui 2 campos para definir o tipo e o valor do atributo Master. O campo2 irá se adequar a partir da opção selecionada no campo1.
      A fonte de dados Detalhe será filtrada a partir do identificador informado nesses campos.
      
      • Campo1: selecione um dos tipos (Texto, Numérico, Data e Hora, Hora, Lógico) para informar valores estáticos ou "Expressão", para obter o identificador da fonte de dados Mestre ou a partir do valor (ng-model) de algum componente visual em tela.
      • Campo2: identificador obtido da fonte de dados Mestre <fonteDados.active.id> ou campo em tela <vars.campo>.
   5. Janela de seleção: abre uma janela com mais opções para selecionar o identificador do master: Expressões, Campos de tela, Bloco de programação e Funções.
   6. Remover: apaga a linha selecionada.
2. Dependente de salvamento: essa propriedade será automaticamente preenchida após a configuração da propriedade Mestre Detalhe. O envio dos registros modificados da fonte de dados Detalhe só ocorrerá após uma ação na fonte de dados dependente (Master).

Cabeçalho

Essa janela permite incluir cabeçalhos e os seus valores para serem enviados pela requisição.

Esse recurso pode ser muito útil ao utilizar com Fonte de dados do tipo Web Services ou Bloco de programação que necessitam de cabeçalhos de autenticação, por exemplo. 

Os parâmetros configurados serão passados via cabeçalho na requisição REST entre o componente visual fonte de dados e a Fonte de dados vinculada e, durante a requisição, podem ser obtidos com o uso dos blocos de programação Obter cabeçalho da requisição ou Obter cabeçalhos da requisição.

Figura 3.5 - Janela da propriedade Cabeçalhos

1. Nova propriedade: nome do novo cabeçalho.
2. "+": inclui o cabeçalho informado na lista.
3. Lista: lista de cabeçalhos.
   1. Propriedade: coluna com o nome dos cabeçalhos. Esse campo permite edição.
   2. Valor: possui 2 campos para definir o tipo e o valor do cabeçalho. O campo2 irá se adequar a partir da opção selecionada no campo1.
      • Campo1: selecione um dos tipos (Texto, Numérico, Data e Hora, Hora, Lógico) para informar valores estáticos ou "Bloco" e "Expressão" para valores dinâmicos.
      • Campo2: aceita o valor com base no tipo selecionado no campo1. Ao selecionar a opção "Expressão", selecionar um campo de qualquer fonte de dados na tela <fonteDados.active.id> ou campo em tela <vars.campo>.
   3. Excluir: remove o cabeçalho selecionado.

Suporte a dados offline (mobile)

Essa propriedade permite que os dados sejam carregados localmente, em cache, e fiquem armazenados no dispositivo. Dessa forma, ao ficar offline, esses registros ainda poderão ser visualizados e editados. Enquanto a aplicação estiver com acesso à internet, as requisições CRUD serão feitas diretamente com a Fonte de dados (servidor), porém, ao perder a conexão com a internet, o componente visual fonte de dados passa a se comunicar com o cache local, suportando, inclusive, pesquisas.

Toda modificação (atualização, deleção e inserção) feita nos registros sem acesso à internet são visualizadas em tempo real na aplicação mobile, como se estivesse online. Porém, essas requisições são armazenadas em uma fila ordenada e, assim que a internet for reestabelecida, todo o conteúdo é disparado em ordem, sincronizando essas modificações com o banco de dados remoto. 

Para evitar requisições desnecessárias na fila, caso ocorra a exclusão de um registro que já possua requisições na fila, essas requisições serão removidas. Todo o processo de controle da fila e sincronização é automático.

O tempo de sincronização dos dados pode variar em torno de 15 a 30 segundos para ser finalizado após a identificação da conexão pela aplicação.

Para que os dados sejam armazenados em cache, é necessário que o usuário acesse (ainda online) a tela que contém a fonte de dados configurada. A medida que os dados vão sendo requisitados (paginados), mais registros serão automaticamente incluídos no cache da aplicação, ou atualizados, caso já existam em cache. O cache respeitará o filtro da fonte de dados, armazenando apenas o que a fonte de dados trouxer.

O cache local não pode ser limpo, ele se manterá atualizado sempre que o componente fonte de dados fizer novas requisições.

Exemplo

Para demonstrar o uso do recurso de suporte a dados offline, geramos uma tela CRUD no Diagrama de dados a partir de uma classe chamada "Pets", contendo os atributos: id, nome e espécie.

Após abrir a página gerada com o Editor de Views, selecionamos o componente visual fonte de dados e alteramos a propriedade Suporte a dados offline para "Sim" (Figura 4).

Figura 4 - Habilitando o recurso de acesso a dados offline em uma fonte de dados

Após isso, compilamos, exportamos a aplicação mobile (mais detalhes no tópico "Compilar" em Menu Dispositivos Móveis) e instalamos no smartphone.

A figura 4.1 mostra que foram criados 3 registros enquanto a aplicação estava online (destaque 1).

Figura 4.1 - Acesso e cadastro dos primeiros registros

Desativamos os dados móveis da operadora (4G e 5G) e WI-FI do smartphone (destaque 1 da figura 4.2), Em seguida, manipulamos alguns registros: o registro 2 não foi modificado, o registro 3 sofreu edição, o registro 4 foi adicionado e um dos registros, o gato "Mingau", foi excluído da lista.

Figura 4.2 - Editando registros offline

Ao final, habilitamos novamente o WI-FI do smartphone e, após alguns segundos, consultamos os registros da tabela referenciada pela fonte de dados (Figura 4.3), demonstrando que a fila de cache offline da aplicação móvel tratou os dados conforme esperado.

Figura 4.3 - Registros modificados na tabela PETS do banco de dados