Esse bloco permite obter os registros de uma Fonte de dados dos tipos Classe ou Entidade (servidor) e carregá-los no cache da aplicação móvel, aumentando a quantidade de registros ou atualizando os registros já existentes localmente. Sendo muito útil para carregar e manter os registros que serão manipulados enquanto estiver offline.
Para funcionar, é necessário que o componente visual fonte de dados (cliente) esteja com a propriedade Suporte a dados offline marcada com a opção "Sim" e vinculada com a Fonte de dados (servidor) selecionada (veja mais detalhes no tópico "Suporte a dados offline (mobile)" na documentação Componente visual fonte de dados).
Figura 1 - Bloco Preencher cache da Fonte de Dados
O conteúdo em cache pode ser obtido através de paginação na tela que possui o componente fonte de dados configurado e, a cada nova requisição, mais registros são adicionados no cache local. O bloco Preencher cache da Fonte de Dados pode ser utilizado para obter todos os registros aceitos pelo filtro da Fonte de dados ou realizar um segundo filtro, em cima dos registros que já são aceitos pela Fonte de dados. O diagrama abaixo representa essa estrutura.
Figura 1.1 - Diagrama de Venn representando o universo em que o bloco atua
Compatibilidade
- Bloco cliente (mobile): cronapi.util.fillDatasource()
Retorno
Bloco sem retorno.
Parâmetros
Os parâmetros deste bloco são incluídos a partir dos filtros criados (destaque 2 da figura 2).
Característica do bloco
O bloco possui um botão engrenagem que abre uma janela parecida com o Assistente JPQL e SQL, porém, após a configuração ele irá montar uma expressão OData em cima das query strings $filter e $orderby.
Essa janela não permite definir os atributos dos objetos, a Fonte de dados selecionada é quem define automaticamente quais os atributos serão obtidos.
Figura 2 - Janela de configuração do bloco
- Entidade: permite selecionar apenas uma Fonte de dados dos tipos Classe ou Entidade.
- "...": abre a janela de seleção da Fonte de dados.
- Filtro: permite incluir uma ou mais regras utilizando o condicional E (AND). As regras são aplicadas em cima dos campos da Fonte de dados selecionada.
- valor: esse campo pode ser utilizado para informar exatamente o valor a ser passado na regra ou definir uma parâmetro para ser alimentado pelo bloco de programação (destaque 3 da figura 2). Para criar uma variável, basta informar o caractere dois pontos "
:" e informar o nome da variável. Ex.::minhaVar
- valor: esse campo pode ser utilizado para informar exatamente o valor a ser passado na regra ou definir uma parâmetro para ser alimentado pelo bloco de programação (destaque 3 da figura 2). Para criar uma variável, basta informar o caractere dois pontos "
- Parâmetro do bloco: parâmetro criado a partir do campo valor (destaque 2a da figura 2).
- Ordenar: permite incluir uma ou mais regras de ordenação. As regras são aplicadas em cima dos campos da Fonte de dados selecionada.
- Testar Consulta: executa a fonte de dados selecionada. Caso existam regras com parâmetros, uma pequena janela será exibida para informar os valores antes da consulta.
- Editar como Texto: permite editar a expressão OData gerada. Uma vez editado, não será possível retornar ao modo low-code.
- Visualizar como Texto: permite visualizar a expressão OData gerada (Figura 2.1).
Figura 2.1 - expressão OData gerado a partir da configuração da figura 2
Exemplo
Para demonstrar o uso do bloco, vamos configurar uma Fonte de dados e obter o cache local de duas formas distintas: via paginação, acessando a tela com a fonte de dados, e depois executando o bloco de programação.
Configuração
Neste exemplo estamos utilizando uma classe chamada "LetraAleatoria", contendo 1 identificador e 2 outros campos: numero, campo inteiro que possui números únicos em sequência , e letra, campo de texto que possui uma letra do alfabeto, escolhida randomicamente.
A figura 3 apresenta como a Fonte de dados do tipo Entidade foi configurada. Após abrir o Assistente de consulta (destaque 1 da figura 3), criamos uma consulta simples contendo um filtro sobre o atributo letra e informamos o valor "A" diretamente na consulta. Além disso, ordenamos essa consulta de forma decrescente a partir do campo numero.
Figura 3 - Consulta da Fonte de dados
Para simplificar os passos, vamos gerar uma página CRUD utilizando a própria Fonte de dados. Acesse o menu de contexto da Fonte de dados na árvore de recursos e selecione Ação > Criar visão para a entidade (Figura 3.1). Esse procedimento irá abrir a janela do Assistente de View, selecione o modelo Formulário CRUD Mobile, informe o nome da tela e um local na aplicação mobile, avance até finalizar.
Figura 3.1 - Criação do formulário a partir da Fonte de dados
Após abrir a tela no Editor de Views, selecione o componente visual fonte de dados (destaque 1 da figura 3.2) para alterar suas propriedades. Primeiro, defina com "2" a propriedade Linhas por página (destaque 2 da figura 3.2), isso garantirá que, enquanto a lista não preencher toda a tela do smartphone ou sempre que for deslizado para cima, uma nova requisição de 2 registros será feita. Em seguida, basta habilitar a propriedade Suporte a dados offline (3), responsável por criar o cache local dessa Fonte de dados.
Incluímos o componente Parágrafo (destaque 4 da figura 3.2) apenas para exibir a quantidade de registros obtidos pela fonte de dados naquele momento. Para atualizar esse componente, utilizamos uma função de bloco de programação que é chamado pelo evento Após preencher do componente visual fonte de dados. A função recebe por parâmetro a fonte de dados e utiliza os blocos Modificar conteúdo, tamanho de e Obter propriedade para obter a propriedade "data" do JSON da fonte de dados.
Não detalhamos a montagem desse bloco de programação neste exemplo, pois estamos utilizando o parágrafo apenas para demonstrar a quantidade de registros, não interferindo nos passos da fonte de dados offline.
Figura 3.2 - Criação do formulário a partir da Fonte de dados
O próximo passo será a criação da função cliente mobile que executará o bloco Preencher cache da Fonte de dados. Após abrir a janela Configurar Bloco de programação, selecione a Fonte de dados (destaque 1 da figura 3.3) e, em seguida, adicione 2 regras que serão alimentadas nos parâmetros do bloco. Nessa configuração, o bloco irá obter e salvar em cache todos os registros que possuem a letra "A" no campo letra e que o campo numero seja menor que 50 (destaques 2 da figura 3.3).
Importante lembrar que, como a Fonte de dados selecionada (1) já filtra os registros que possui a letra "A" (figura 3), não seria possível obter registros que possuem outras letras utilizando o bloco Preencher cache da Fonte de dados.
Figura 3.3 - Criação do formulário a partir da Fonte de dados
Na tela home (Localização: Formulário/Mobile/Autenticado/ ) arraste 2 botões. Configure um para executar a função com o bloco Preencher cache da Fonte de dados (Figura 3.3) e o outro para acessar a página CRUD criada na figura 3.2.
Figura 3.4 - Tela home da aplicação mobile
Teste
Esse teste pode ser executado de duas formas:
- Compilar a aplicação mobile (mais detalhes no tópico "Compilar" em Menu Dispositivos Móveis) e instalar no smartphone ou
- Utilizar o aplicativo Cronapp Browser para simular a execução da aplicação no smartphone (mais detalhes no tópico "Cronapp Browser" em Menu Dispositivos Móveis).
Abra o aplicativo no Smartphone, com a internet habilitada (destaque 1 da figura 3.5), e acesse a tela CRUD criada no exemplo. Os registros serão carregados (e armazenado em cache) de 2 em 2 até a lista ficar um pouco abaixo do final da tela.
A tabela do banco de dados usada no exemplo possui 1000 registros e a Fonte de dados foi configurada (figura 3) para obter os registros em ordem decrescente, logo, os atributos numero dos registros carregados estão próximos de "1000".
Veja a quantidade de registros carregados no parágrafo (2).
Figura 3.5 - Armazenamento em cache sendo feito a cada paginação
Retorne à tela inicial do aplicativo, onde adicionamos os botões (figura 3.6). Clique no botão configurado para executar a função com bloco de programação Preencher cache da Fonte de dados (1) e, em seguida, acesse as configurações do seu smartphone e desative os dados móvel da sua operadora (4G e 5G) e WI-FI (2).
Figura 3.6 - Armazenamento em cache sendo feito com o bloco de programação
Ao acessar novamente a tela CRUD criada no exemplo, podemos notar que a lista possui mais registros carregados, 11 ao invés de 8 (destaque 1 da figura 3.7). Também existem registros com o atributo numero de valor menor que "50", como configurado no bloco de programação (figura 3.3).
Figura 3.7 - Obtendo os registros armazenados em cache
Nesse momento é possível fechar e abrir o aplicativo no smartphone e acessar novamente essa tela para obter os mesmos registros. Caso acesse a tela com a internet habilitada, os dados serão obtidos do servidor da aplicação.
Nesta página