Função

O Sub Formulário possui o mesmo comportamento do componente Formulário, mas foi criado para ser utilizado dentro desse componente. Dessa forma, é possível vincular uma nova Fonte de dados ao Sub Formulário sem interferir na fonte de dados associada ao componente Formulário (principal). 

Animação 1 - Exemplo do componente rodando dentro do Formulário no browser

Principais propriedades

Na tabela abaixo estão descritas as principais propriedades para o funcionamento básico do componente.

Subcomponentes

Esse componente é formado por oito subcomponentes agrupados: seis botões e uma div. Cada um possui uma função que vem configurada no componente. Para selecionar um subcomponente basta clicar no que for desejado.

Exemplo de uso

Relacionamento

Crie um exemplo para filtrar o Status (entidade do Sub Formulário) de acordo com o pedido (entidade do Formulário). Para isso, é necessário configurar duas entidades com o relacionamento 1 para N entre elas para criar a chave estrangeira (FK).

Figura 1 - Relacionamento 1 para N

Inserir componentes

Após adicionar o componente Formulário e configurá-lo, insira o componente Grade. Arraste-o para a área de edição e solte-o logo depois do formulário.

Figura 2 - Inserindo a grade

Abrirá uma janela de configuração, siga os passos abaixo para configurar a Fonte de dados.

Figura 3 - Configurando fonte de dados da grade

1. Na janela Opções da Grade clique no ícone de + do campo Fonte de dados para adicionar uma nova fonte de dados;
2. Na próxima janela clique em "..." do campo Origem;
3. Escolha a fonte de dados na lista, clique em OK ao final e OK também na janela de Configuração da fonte;
4. Volte para a janela Opções da Grade e escolha no campo Editável a opção Pelo Datasource;

Em seguida, siga os passos abaixo para configurar as Colunas da Grade.

Figura 4 - Configurando colunas da grade

1. Ainda na janela Opções da Grade vá até a aba Colunas;
2. Na coluna Listagem marque um x apenas no campo status;
3. Também no campo data;
4. E deixe o campo Editar/Excluir também marcado na Listagem.

Em seguida, arraste o componente Sub Formulário para a área de edição abaixo da grade (Figura 5).

Figura 5 - Inserindo componente Sub Formulário

Vincular fonte de dados

Após configurar a fonte de dados, selecione o componente Sub Formulário e, na aba de Propriedades, vincule a fonte no campo Fonte de dados (Figura 6).

Figura 6 - Vinculando fonte de dados ao componente

Mestre detalhe

Selecione a fonte de dados do Sub Formulário, vá até a aba de Propriedades e adicione uma ligação no campo Mestre Detalhe. Clique em "..." (destaque 1 da Figura 7), depois clique em Adicionar Ligação (2) e selecione no Campo detalhe a chave estrangeira criada no relacionamento entre fontes pedido igual ao id da fonte de dados Pedido.active.id do componente Formulário. Exemplo: pedido = Expressão Pedido.active.id.

Figura 7 - Configurando mestre detalhe

Adicionar campo

Em seguida, arraste um componente (ex.: Entrada de texto) à div do formulário, verificando se as arestas da div do componente sub formulário estão tracejadas (Figura 8) e solte-o. Para adicionar outro componente, arraste-o para a área de edição abaixo do campo recém-adicionado.

Figura 8 - Adicionando campo ao sub formulário

Configurar campo

Para que o item seja salvo, é necessário vincular os componentes adicionados no Sub Formulário com os campos da fonte de dados. Então, selecione o componente e, na aba Propriedades, abra a caixa de seleção do campo Valor (Figura 9) e escolha em qual dos campos da fonte de dados será salvo. 

Deve-se fazer esse procedimento para todos os componentes adicionados ao Sub formulário.

Figura 9 - Configurando valor do componente

Alguns componentes permitem adicionar a propriedade apenas leitura para que não seja possível editar o campo quando não estiver em modo de inserção ou edição. No caso de um componente Entrada de texto, selecione-o e desagrupe-o. Selecione somente a tag input (destaque 1 da Figura 10), clique em Exibir mais na aba Propriedades e adicione o conteúdo !datasource.editing && !datasource.inserting na propriedade Apenas leitura.

Repita esse procedimento para todos os campos adicionados no Sub formulário.

Figura 9 - Configurando propriedade apenas leitura

Ocultar componente

Para ocultar quando não estiver editando ou inserindo selecione o componente sub formulário e, na aba Propriedades, adicione no campo Exibir (Figura 11) o conteúdo datasource.editing || datasource.inserting.

Figura 11 - Ocultando o sub formulário

Teste

Por fim, rode o projeto e abra a página na aplicação. Clique no ícone de Inserir (Figura 12) para adicionar um pedido. 

Figura 12 - Inserindo um novo pedido

Em seguida, clique em Adicionar (Figura 13) na grade para inserir um status. Note que o sub formulário é exibido apenas ao inserir ou editar na grade.

Figura 13 - Adicionando dados na grade

Informação extra

No exemplo da Animação 1 do tópico Função, o Sub Formulário está dentro da div do Formulário. Por padrão, a navegação entre os botões estará desativada quando não estiver editando o Formulário. Isso acontece porque a div do componente está configurada para ficar desabilitada fora do modo de edição. Para permitir a navegação entre os botões é necessário selecionar o Sub Formulário e clicar na div do formulário na árvore DOM (destaque 1 da Figura 14) e, na aba de Propriedades, remover o conteúdo do campo Desabilitar Se (destaque em amarelo).

Figura 14 - Remover o Desabilitar Se do formulário

Tratamento de erro

Ao editar um Sub formulário deixando-o em modo de edição ao salvar ou cancelar o Formulário, o componente Sub formulário aparecerá aberto no modo desabilitado e permanecerá aberto na próxima edição. Para evitar esse erro, siga os passos abaixo.

Image Added

Figura 15 - Tratar erro de edição

1. Selecione a fonte de dados do Sub Formulário (Status);
2. Na aba de Propriedades da fonte, clique em Exibir mais;
3. Em seguida, procure pelo campo Depende de Salvamento e selecione a fonte de dados do Formulário (Pedido).