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 <TODO: link>, criada no lado do servidor, e outros componentes visuais na tela, como Grade, Lista Avançada e outros.

Após configurado, um componente visual executa alguma ação de CRUD (criar, ler, atualizar ou deletar) para um ou mais registros e se comunica, via Angular, com o componente visual fonte de dados associado. Ele então encaminha essa requisição RESTful (ODATA) para a Fonte de Dados <TODO: link> (servidor) vinculada, fornecendo os dados necessários, como campos, parâmetros e filtros (Figura 1).

O componente fonte de dados suporta os 4 tipos de Fonte de dados (Bloco de programação, Entidade, SQL Nativo e Web Service) criados e customizados do lado servidor e mais o tipo Classe, em que uma classe do Diagrama é selecionada e os filtros são configurados diretamente nas propriedades do componente visual fonte de dados. Essas propriedades adicionam parâmetros query string às requisições, possibilitando customizar ainda mais a comunicação com a Fonte de dados. Além das propriedades, o componente visual também possui eventos próprios, que são executados do lado cliente (javascript).

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), a janela Lista de Fontes de dados será aberta para permitir o vínculo com a Fonte de dados desejada.

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

Em geral, os componente visuais que utilizam a fonte de dados possuem a propriedade Configuração, após abrir a sua janela, selecione uma das fontes de dados contidas na tela (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á associado 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 o componente fonte de dados na área de edição, suas propriedades serão exibidas no menu lateral Propriedades. Porém, algumas dessas propriedades também são exibidas ao clicar nos botões Adicionar fonte de dados (+) e Modificar fonte de dados (…) (destaque 1 da figura 2.2) do campo Fonte de dados da janela de configurações dos componentes visuais. Acesse o tópico Principais propriedades <TODO: link âncora> 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

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 <TODO: link>, 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 funciona bem e de forma automática para os tipos de Fontes de dados vinculadas diretamente ao banco de dados: Classe, Entidade 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 necessitará utilizar 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 <TODO: link>.
• 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 <TODO: link>). 

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 <TODO: link>).
   4. Valor: campo para informar o valor estático ou dinâmico.
   5. Bloco de programação: permite a seleção de uma função de bloco de programação.
   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 <TODO: link>).
   8. Valor: campo para informar o valor estático ou dinâmico.
   9. Bloco de programação: permite a seleção de uma função de bloco de programação.
   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: Classe, Entidade 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 <TODO: link>.
• A ordenação nas Fontes de dados do tipo Web Services irão 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 <TODO: link>). 

Image Added

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