Componente visual fonte de dados
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 Cronapp MVC (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
Para facilitar a comunicação nesta documentação, utilizaremos a expressão "fonte de dados" (minúsculo) para se referir ao componente visual fonte de dados (recurso cliente) e "Fonte de dados" (maiúsculo) para se referir ao elemento Fonte de Dados do servidor da aplicação.
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
Não é recomendado utilizar o mesmo componente visual fonte de dados para dois componentes na mesma tela, para esses casos, utilize um segundo componente 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
Aba de Propriedades
Na tabela abaixo estão descritas as principais propriedades do componente visual fonte de dados.
Nome | Propriedade | Função |
|---|---|---|
entity | Abre a janela Lista de Fonte de dados (Figura 2) para vincular a uma Entidade (classe do diagrama) ou uma das 4 fontes de dados personalizadas: Bloco de programação, Consulta a Entidades, SQL Nativo ou Web Service. | |
Nome | name | Nome do componente fonte de dados, utilizado como identificador único desse componente na página. O nome deve possuir apenas caracteres alfanuméricos maiúsculos e minúsculos. |
Chaves | keys | Define os atributos de chave primária da entidade atribuída à fonte de dados. Esse recurso é utilizado, por exemplo, nas requisições que necessitam desses atributos, como delete ou update. Por padrão, esse campo já vem preenchido com o atributo virtual " |
condition | Permite alimentar os parâmetros definidos na aba Filtro da Fonte de dados e incluir novos filtros que serão passados na requisição do componente visual fonte de dados até a Fonte de dados vinculada. | |
Estratégia em Cláusula Nula | parameters-null-strategy | Define como o sistema deve tratar parâmetros nulos do campo "Filtros e Parâmetros" da fonte de dados;
|
parameters | Permite relacionar um ou mais atributos (normalmente chaves) entre duas ou mais fontes de dados. Dessa forma, ao selecionar um registro da fonte de dados Mestre, ocorrerá um filtro no carregamento da fonte de dados Detalhe. Essa configuração precisa ser feita na fonte de dados Detalhe. | |
Estratégia para Carregar Dados | load-data-strategy | Escolhe as condições de carregamento dos dados, que são:
|
order-by | Define um ou mais campos para a ordenação dos registros, essa informação será passada na requisição do componente visual fonte de dados até a Fonte de dados vinculada. | |
Postergar Carga | lazy | Carrega a fonte de dados somente após uma ação do usuário. Essa propriedade pode ser utilizada junto com o campo Estratégia para Carregar Dados. Opções:
Obs.: Mesmo com a opção "Sim", alguns componentes visuais como Grade e Lista Avançada forçam automaticamente o carregamento da fonte de dados durante o carregamento da página. |
Validar Campos Requeridos | checkrequired | Insere ou atualiza os dados somente se todos os campos marcados como requeridos estiverem preenchidos. |
headers | Permite adicionar um ou mais cabeçalhos para serem enviados na requisição. | |
Atualizar Automaticamente (ms) | auto-refresh | Define um intervalo de tempo, em milissegundos, para forçar a fonte de dados a realizar uma nova consulta. Esse recurso costuma ser utilizado em aplicações que necessitam de atualizações constantes, como chat e thread de fórum colaborativo. |
Carregar quando visível | fetch-on-visible | A fonte de dados carregará os dados sempre que o ícone do componente estiver em um local visível na tela. Em uma tela que possua um modal com uma fonte de dados e essa propriedade configurada, sempre que o modal for aberto na tela, a fonte de dados fará uma requisição. Obs.: A propriedade Postergar Carga poderá influenciar no resultado dessa propriedade. |
Dependente de salvamento | dependent-lazy-post | Vincula uma fonte de dados para servir como dependente da fonte de dados atual - ou seja, o salvamento da fonte de dados atual dependerá de uma ação na fonte de dados selecionada. Essa opção será automaticamente preenchida na fonte de dados "detalhe" após a configuração da propriedade Mestre Detalhe. |
Linhas por página | rows-per-page | Define a quantidade de registros por página. Essa informação será passada na requisição do componente visual fonte de dados até a Fonte de dados vinculada. O valor definido por padrão é 100. |
offline | Recurso disponível apenas nos componentes visuais fonte de dados das aplicações mobile. Permite utilizar a fonte de dados mesmo sem conexão com a internet. Uma vez esses registros carregados no banco de dados local, cada ação realizada (inserir, atualizar e deletar) é salva em banco de dados local e, assim que a conexão com a internet for reestabelecida, essas ações serão sincronizadas com o servidor da aplicação automaticamente. |
Aba de 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).
Nome | Propriedade | Função |
|---|---|---|
Ao mudar de Status | on-change-status | Executa uma ação toda vez que a fonte de dados mudar seu status (leitura, edição ou inserção). O tratamento do status (modo) pode ser feito a partir de diversos blocos de programação: |
Antes de Atualizar | on-before-update | Executa uma ação antes de um dado ser atualizado. |
Antes de Criar | on-before-create | Executa uma ação antes de um dado ser criado. |
Antes de Deletar | on-before-delete | Executa uma ação antes de um dado ser excluído. |
Ao Errar | on-error | Executa uma ação quando ocorrer um erro. |
Após Deletar | on-after-delete | Executa uma ação após um dado ser excluído. |
Após atualizar | on-after-update | Executa uma ação após um dado ser atualizado. |
Após criar | on-after-create | Executa uma ação após um dado ser criado. |
Após preencher | on-after-fill | Executa uma ação após o carregamento dos dados. |
Para Atualizar Dados | on-put | Substitui a ação padrão de atualizar os dados da fonte de dados, pela ação definida no evento. |
Para Inserir Dados | on-post | Substitui a ação padrão de inserir os dados da fonte de dados, pela ação definida no evento. |
Para Obter Dados | on-get | Substitui a ação padrão de obter os dados da fonte de dados, pela ação definida no evento. Esse evento espera receber uma lista de objetos (JSON) contendo os mesmos atributos da entidade definida na Fonte de dados vinculada. |
Para Remover Dados | on-delete | Substitui a ação padrão de deletar os dados da fonte de dados, pela ação definida no evento. |
Aba de 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
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.
Nome do parâmetro: esse campo exibirá os mesmos campos contidos na aba Filtro da Fonte de dados.
Comparativo: a opção igual (
=) é a única disponível para esse campo.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).Valor: campo para informar o valor estático ou dinâmico.
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.
Limpar: apaga as configurações do parâmetro selecionado.
Expressão: inclui uma ou mais regras no padrão OData na requisição da Fonte de dados.
Grupo: informa o condicional AND (e) ou OR (ou) para o grupo de regras selecionado.
Adicionar regra: inclui nova linha de regra dentro desse grupo.
Adicionar grupo: inclui novo grupo de condicional para o novo conjunto de regras filho.
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.
Campo da regra: lista de campos vinculados a Fonte de dados.
Comparativo: opções de comparativo: Menor igual (
<=), Contém (⊃), Diferente (<>), Menor (<) , Igual (=), Maior (>) e Maior igual (>=).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).Valor: campo para informar o valor estático ou dinâmico.
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.
Remover: apaga a linha de regra selecionada.
Ao configurar um filtro, é importante observar os seguintes aspectos:
O valor do dado (destaques 1.d e 2.h da figura 3) deve ser do mesmo tipo e formato do atributo comparado (destaques 1.a e 2.e da figura 3), principalmente em atributos dos tipos data e data e hora.
Alguns comparadores (destaque 2.f da figura 3) podem ser incompatíveis com determinados tipos de dados. Por exemplo, o comparador "contém" (⊃) não deve ser usado com tipos de dados como data e data e hora. Para atributos booleanos, é aconselhável utilizar apenas os comparadores "igual" (=) ou "diferente" (<>).
Não é possível criar filtros a partir de Campos calculados, já que os campos calculados não são persistidos. Ao realizar um filtro, as requisições são encaminhadas ao banco de dados ou a outro recurso que alimenta a Fonte de dados e lá, os Campos calculados não existem. (veja mais detalhes no tópico "Campos calculados" em Fonte de dados)
Exceção a regra: quando o componente fonte de dados mobile está configurado com suporte a dados offline e a aplicação está sendo executada sem acesso à internet, as requisições deixam de ser encaminhadas ao banco de dados ou a outro recurso que alimenta a Fonte de dados e passam a filtrar o conteúdo em cache, local em que os Campos calculados existem.
Por se tratar de uma situação que restringe muito o uso do filtro, não recomendamos.
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
Adicionar campo de ordenação: inclui um campo na lista.
Campo: seleciona um dos campos vinculados a Fonte de dados.
Ordenação: define se a ordenação será ASCendente ou DESCendente.
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:
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)
A Grade possui funcionalidades próprias para tratar esse recurso, acesse o tópico "Mestre e detalhe" da documentação Grade para mais informações.
A ligação Mestre Detalhe funciona bem e de forma automática para os tipos de Fonte de dados vinculadas diretamente ao banco de dados: Entidade, Consulta a Entidades e SQL Nativo.
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
Mestre Detalhe
Adicionar Ligação: inclui uma linha para a seleção dos campos.
Campo detalhe: lista os campos da fonte de dados Detalhe. Selecione o campo que representa a entidade Mestre (atributo de chave estrangeira).
Comparativo: a opção igual (
=) é a única disponível para esse campo.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>.
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.
Remover: apaga a linha selecionada.
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).