Expressões de formulário adaptável

Os formulários adaptáveis fornecem experiência de preenchimento de formulários otimizada e simplificada para usuários finais com recursos de script dinâmico. Permite gravar expressões para adicionar vários comportamentos, como mostrar/ocultar campos e painéis dinâmicos. Também permite adicionar campos calculados, tornar campos somente leitura, adicionar lógica de validação e muito mais. O comportamento dinâmico é baseado na entrada do usuário ou nos dados pré-preenchidos.

JavaScript é a linguagem de expressão de formulários adaptáveis. Todas as expressões são expressões JavaScript válidas e usam APIs de modelo de script de formulários adaptáveis. Essas expressões retornam valores de determinados tipos. Para obter a lista completa de classes de formulários adaptáveis, eventos, objetos e APIs públicas, consulte Referência da API da biblioteca JavaScript para formulários adaptáveis.

Práticas recomendadas para escrever expressões

  • Ao gravar expressões, para acessar campos e painéis, é possível usar o nome do campo ou do painel. Para acessar o valor de um campo, use a propriedade value . Por exemplo, field1.value
  • Use nomes exclusivos para campos e painéis no formulário. Isso ajuda a evitar possíveis conflitos com os nomes de campo usados ao gravar expressões.
  • Ao escrever expressões de várias linhas, use um ponto e vírgula para encerrar uma instrução.

Práticas recomendadas para expressões envolvendo painel repetitivo

Painéis repetitivos são instâncias de um painel que são adicionadas ou removidas dinamicamente usando a API de scripts ou dados pré-preenchidos. Para obter informações detalhadas sobre o uso do painel repetitivo, consulte criar formulários com seções repetíveis.

  • Para criar um painel repetitivo, na caixa de diálogo do painel, abra as configurações e defina o valor do campo de contagem máxima como mais de 1.

  • O valor da contagem mínima das configurações de repetição do painel pode ser um ou mais, mas não pode ser maior que o valor da contagem máxima.

  • Quando uma expressão se refere a um campo de painel repetitivo, os nomes de campo na expressão são resolvidos para o elemento repetitivo mais próximo.

  • Formulários adaptáveis oferecem algumas funções especiais para simplificar o cálculo de painéis repetidos, como soma, contagem, mín, máx, filtro e muito mais. Para obter a lista completa de funções, consulte Referência da API da biblioteca JavaScript para formulários adaptáveis

  • As APIs para manipular instâncias do painel repetitivo são:

    • Para adicionar uma instância de painel: panel1.instanceManager.addInstance()
    • Para obter um índice de repetição de painel: panel1.instanceIndex
    • Para obter o instanceManager de um painel: _panel1 or panel1.instanceManager
    • Para remover uma instância de um painel: _panel1.removeInstance(panel1.instanceIndex)

Tipos de expressão

Em formulários adaptáveis, você pode gravar expressões para adicionar comportamentos, como campos dinâmicos de mostrar/ocultar e painéis. Também é possível gravar expressões para adicionar campos calculados, tornar campos somente leitura, lógica de validação e muito mais. Os formulários adaptáveis suportam as seguintes expressões:

Expressão de acesso (Expressão de ativação)

Você pode usar a expressão de acesso para ativar ou desativar um campo. Se a expressão usar o valor de um campo, sempre que o valor do campo for alterado, a expressão será reacionada.

Aplica-se a: campos

Tipo de retorno: A expressão retorna um valor booleano, representando se o campo está ativado ou desativado. O representa que o campo está ativado e o ​false apresenta o campo como desativado.

Exemplo: Para ativar um campo somente quando o valor de field1 estiver definido como X, a expressão de acesso é: field1.value == "X"

Calcular expressão

A expressão calculate é usada para calcular automaticamente o valor de um campo usando uma expressão. Normalmente, essa expressão usa a propriedade value de outros campos. Por exemplo, field2.value + field3.value. Sempre que o valor de field2ou field3for alterado, a expressão será reacionada e o valor será recalculado.

Aplica-se a: campos

Tipo de retorno: A expressão retorna um valor compatível com o campo onde o resultado da expressão é exibido (por exemplo, decimal).

Exemplo: A expressão calculate para mostrar a soma de dois campos no campo1 é:
field2.value + field3.value

Clique em Expressão

A expressão click manipula as ações executadas no evento click de um botão. Pronto para uso, o GuideBridge fornece APIs para executar várias funções, como enviar, validar e serem usadas junto com a expressão de clique. Para obter uma lista completa das APIs, consulte APIs do GuideBridge.

Aplica-se a: Campos de botão

Tipo de retorno: A expressão click não retorna nenhum valor. Se qualquer expressão retornar um valor, o valor será ignorado.

Exemplo: Para preencher uma caixa de texto textbox1 na ação de clique de um botão com valor AEM Forms, a expressão de clique do botão é textbox1.value="AEM Forms"

Script de inicialização

O script de inicialização é acionado quando um formulário adaptável é inicializado. Dependendo dos cenários, o script de inicialização se comporta da seguinte maneira:

  • Quando um formulário adaptável é renderizado sem um preenchimento prévio de dados, o script de inicialização é executado depois que o formulário é inicializado.
  • Quando um formulário adaptável é renderizado com um preenchimento prévio de dados, o script é executado após a conclusão da operação de preenchimento prévio.
  • Quando a revalidação de um formulário adaptável pelo lado do servidor é acionada, o script de inicialização é executado.

Aplica-se a: campos e painel

Tipo de retorno: a expressão do script de Inicialização não retorna nenhum valor. Se qualquer expressão retornar um valor, o valor será ignorado.

Exemplo: em um cenário de pré-preenchimento de dados, para preencher campos com valor padrão 'Adaptive Forms' quando o valor for salvo como nulo, a expressão do script de inicialização é:
if(this.value==null) this.value='Adaptive Forms';

Expressão de opções

A expressão options é usada para preencher dinamicamente as opções de um campo de lista suspensa.

Aplica-se a: campos de lista suspensa

Tipo de retorno: A expressão options retorna uma matriz de valores de string. Cada valor pode ser uma string simples, como Masculino, ou em um formato de par key=value, como 1=Masculino

Exemplo: Para preencher o valor de um campo, com base no valor de outro campo, forneça uma expressão de opções simples. Por exemplo, para preencher um campo, Number of Kids, com base no Marital Status expresso em outro campo, a expressão é:

marital_status.value == "married" ? ["1=One", "2=two"] : ["0=Zero"].

Sempre que o valor do campo marital_status for alterado, a expressão será reacionada. Também é possível preencher a lista suspensa em um serviço REST. Para obter informações detalhadas, consulte Preencher dinamicamente listas suspensas.

Expressão de resumo

A expressão Resumo calcula dinamicamente o título de um painel filho de um painel de layout de acordeão. Você pode especificar a expressão Resumo em uma regra, que usa um campo de formulário ou uma lógica personalizada para avaliar o título. A expressão é executada quando o formulário é inicializado. Se um formulário estiver sendo preenchido previamente, a expressão será executada depois que os dados forem preenchidos previamente ou quando o valor dos campos dependentes usados na expressão for alterado.

Normalmente, a expressão Resumo é usada para filhos repetitivos de um painel de layout de acordeão para fornecer um título significativo para cada painel filho.

Aplica-se a: Painéis que são filhos diretos de um painel cujo layout está configurado como Acordeão.

Tipo de retorno: a expressão retorna uma string que se torna o título da opção.

Exemplo: "Account number : "+ textbox1.value

Validar expressão

A expressão validate é usada para validar os campos usando a expressão fornecida. Normalmente, essas expressões usam expressões regulares juntamente com o valor do campo para validar um campo. A expressão é reacionada e o status de validação do campo é recalculado em qualquer alteração no valor de um campo.

Aplica-se a: campos

Tipo de retorno: A expressão retorna um valor booleano, representando o status de validação do campo. O valor false representa que o campo é inválido e true representa que o campo é válido.
Exemplo: Para um campo que representa código postal do Reino Unido, a expressão de validação é:

(this.value && this.value.match(/^(GIR 0AA|[A-Z]{1,2}\d[A-Z0-9]? ?[0-9][A-Z]{2}\s*)$/i) == null) ? false : true

No exemplo acima, se o valor que não está vazio não corresponder ao padrão, a expressão retornará false para indicar que o campo não é válido.

OBSERVAÇÃO

Se você gravar uma expressão de validação para um campo não obrigatório ou obrigatório, a expressão será avaliada independentemente do status de visibilidade do campo. Para interromper a validação dos campos ocultos, defina a propriedade validationsDisabled no Script de confirmação de inicialização ou valor como true. Por exemplo, this.validationsDisabled=true

Script de Value Commit

O script Value Commit é acionado quando:

  • Um usuário altera o valor de um campo da interface do usuário.
  • O valor de um campo é alterado programaticamente devido a uma alteração em outro campo.

Aplica-se a: campos

Tipo de retorno: a expressão do script de confirmação de valor não retorna nenhum valor. Se qualquer expressão retornar um valor, o valor será ignorado.

Exemplo: para converter as letras maiúsculas e minúsculas inseridas no campo em confirmar, a expressão de confirmação de valor é:
this.value=this.value.toUpperCase()

OBSERVAÇÃO

Você pode desativar a execução do Script de confirmação de valor quando o valor de um campo é alterado programaticamente. Para fazer isso, vá para https://'[server]:[port]'/system/console/configMgr e altere Adaptive Forms Version for Compatibility para AEM Forms 6.1. Consequentemente, o script de confirmação de valor é executado somente quando o usuário altera o valor do campo da interface do usuário.

Expressão de visibilidade

A expressão Visibility é usada para controlar a visibilidade do campo/painel. Normalmente, a expressão de visibilidade usa a propriedade value de um campo e é reacionada sempre que esse valor é alterado.

Aplica-se a: campos e painel

Tipo de retorno: A expressão retorna um valor booleano, representando o campo/painel que está visível ou não. ​O falso representa que o campo ou painel não está visível e o true representa que o campo ou painel está visível.

Exemplo: Para um painel que se torna visível somente se o valor de field1 estiver definido como Masculino, a expressão de visibilidade é: field1.value == "Male"

Expressão de conclusão de etapa

A expressão de conclusão de etapa é usada para impedir que um usuário vá para a próxima etapa de um layout de assistente. Essas expressões são usadas quando os painéis têm um layout de assistente (um formulário de várias etapas que mostra uma etapa de cada vez). O usuário pode se mover para a próxima etapa, painel ou subseção somente se todos os valores necessários na seção atual forem preenchidos e válidos.

Aplica-se a: Painéis com layout do item definido como assistente.

Tipo de retorno: A expressão retorna um valor booleano, representando o painel atual como válido ou não. ​Representa que o painel atual é válido e que o usuário pode navegar para o próximo painel.

Exemplo: Em um formulário organizado em vários painéis, antes de navegar até o próximo painel, o painel atual é validado. Nesses casos, as expressões de conclusão de etapas são usadas. Geralmente, essas expressões usam a API de validação GuideBridge. Um exemplo de expressão de conclusão de etapa é:
window.guideBridge.validate([],this.panel.navigationContext.currentItem.somExpression)

Validações no formulário adaptável

Existem vários métodos para adicionar a validação de campo a um formulário adaptável. Se uma verificação de validação for adicionada em um campo, True representa que o valor inserido no campo é válido. ​Falsereapresenta que o valor é inválido. Se você inserir ou sair de um campo, a mensagem de erro não será gerada.

Os métodos para adicionar validações em um campo são:

Obrigatório

Para tornar um componente obrigatório, na caixa de diálogo Editar do componente, é possível selecionar a opção Título e Texto > Obrigatório. Você também pode adicionar a mensagem necessária (opcional) apropriada. .

Padrões de validação

Há vários padrões de validação prontos para uso disponíveis para um campo. Para selecionar um padrão de validação, na caixa de diálogo Editar do componente, localize a seção Padrões e selecione padrões. Você pode criar seu próprio padrão de validação personalizado em uma caixa de texto Padrão. O status de validação é retornado True somente se os dados preenchidos forem compatíveis com o padrão de validação, caso contrário False será retornado. Para escrever seu próprio padrão de validação personalizado, consulte Suporte a cláusula de imagem para formulários HTML5.

Expressões de validação

A validação de um campo também pode ser calculada usando expressões em campos diferentes. Essas expressões são gravadas no campo Script de validação da guia Script da caixa de diálogo Editar do componente. O status de validação de um campo depende do valor retornado pela expressão. Para obter informações sobre como gravar essas expressões, consulte Validar Expressão.

Informações adicionais

Usando o Formato de Exibição de Campo

Formato de exibição pode ser usado para exibir os dados em diferentes formatos. Por exemplo, você pode usar o formato de exibição para exibir um número de telefone com hifens, formatar CEP ou seletor de data. Esses padrões de exibição podem ser selecionados na seção Padrões da caixa de diálogo Editar de um componente. Você pode gravar padrões de exibição personalizados semelhantes aos padrões de validação mencionados acima.

GuideBridge - APIs e eventos

O GuideBridge é uma coleção de APIs que podem ser usadas para interagir com formulários adaptáveis no modelo de memória em um navegador. Para obter uma introdução detalhada à API Guide Bridge, métodos de classe, eventos expostos, consulte Referência da API da biblioteca JavaScript para formulários adaptáveis.

OBSERVAÇÃO

É recomendável não usar os ouvintes de eventos do GuideBridge nas expressões.

Uso do GuideBridge em várias expressões

  • Para redefinir campos de formulário, é possível acionar a API guideBridge.reset() na expressão click de um botão. Da mesma forma, há uma API de envio que pode ser chamada como uma expressão de clique guideBridge.submit().

  • Você pode usar a API setFocus() para definir o foco em vários campos ou painéis (para que o foco do painel seja definido automaticamente para o primeiro campo). setFocus()O fornece uma grande variedade de opções para navegar, como navegação em painéis, travessia anterior/seguinte, definição do foco para um campo específico e muito mais. Por exemplo, para ir para o próximo painel, você pode usar: guideBridge.setFocus(this.panel.somExpression, 'nextItem').

  • Para validar um formulário adaptável ou seus painéis específicos, use guideBridge.validate(errorList, somExpression).

Uso do GuideBridge fora das expressões 

Também é possível usar as APIs do GuideBridge fora das expressões. Por exemplo, você pode usar a API GuideBridge para definir a comunicação entre a página HTML hospedando o formulário adaptável e o Modelo de formulário. Além disso, é possível definir o valor que vem do pai do Iframe que hospeda o formulário.

Para usar a API GuideBridge para o exemplo acima mencionado, capture uma instância de GuideBridge. Para capturar a instância, ouça o evento bridgeInitializeStartde um objeto window:

window.addEventListener("bridgeInitializeStart", function(evnt) {

     // get hold of the guideBridge object

     var gb = evnt.detail.guideBridge;

     //wait for the completion of AF

     gb.connect(function (){

        //this function will be called after Adaptive Form is initialized

     })

})
OBSERVAÇÃO

No AEM, é uma boa prática gravar código em um clientLib e incluí-lo em sua página (header.jsp ou footer.jsp da página)

Para usar o GuideBridge após a inicialização do formulário (o evento bridgeInitializeComplete é despachado), obtenha a instância GuideBridge usando window.guideBridge. Você pode verificar o status de inicialização do GuideBridge usando a API guideBride.isConnected.

Eventos do GuideBridge

O GuideBridge também fornece determinados eventos para scripts externos na página de hospedagem. Os scripts externos podem acompanhar esses eventos e executar várias operações. Por exemplo, sempre que o nome de usuário em um formulário é alterado, o nome mostrado no cabeçalho da página também é alterado. Para obter mais detalhes sobre esses eventos, consulte Referência da API da biblioteca JavaScript para formulários adaptáveis.

Use o seguinte código para registrar manipuladores:

guideBridge.on("elementValueChanged", function (event, data)  {

      // execute some logic when value of a field is changed

});

Criação de padrões personalizados para um campo

Como mencionado acima, formulários adaptáveis permitem que o autor forneça padrões para formatos de validação ou exibição. Além de usar padrões prontos para uso, você pode definir padrões personalizados reutilizáveis para um componente de formulário adaptável. Por exemplo, é possível definir um campo de texto ou um campo numérico. Depois de definido, você pode usar esses padrões em todos os formulários para o tipo especificado de componente. Por exemplo, você pode criar um padrão personalizado para um campo de texto e usá-lo nos campos de texto em seus formulários adaptáveis. Você pode selecionar o padrão personalizado acessando a seção padrão na caixa de diálogo Editar de um componente. Para obter detalhes sobre a definição ou o formato do padrão, consulte Suporte a cláusula de imagem para formulários HTML5.

Execute as seguintes etapas para criar um padrão personalizado para um tipo de campo específico e reutilizá-lo para outros campos do mesmo tipo:

  1. Navegue até o CRXDE Lite na sua instância de criação.

  2. Crie uma pasta para manter seus padrões personalizados. No diretório /apps, crie um nó do tipo sling:folder. Por exemplo, crie um nó com o nome customPatterns. Nesse nó, crie outro nó do tipo nt:unstructed e o nomeie textboxpatterns. Este nó contém os vários padrões personalizados que você deseja adicionar.

  3. Abra a guia Properties do nó criado. Por exemplo, abra a guia Propriedades de textboxpatterns. Adicione a propriedade guideComponentType a este nó e defina seu valor para fd/af/components/formatter/guideTextBox.

  4. O valor dessa propriedade varia dependendo do campo para o qual você deseja definir os padrões. Para campo numérico, o valor da propriedade guideComponentType é fd/af/components/formatter/guideNumericBox. O valor do campo Datepicker é fd/af/components/formatter/guideDatepicker.
    "

  5. Você pode adicionar um padrão personalizado atribuindo uma propriedade ao nó textboxpatterns. Adicione uma propriedade com um nome (por exemplo pattern1) e defina seu valor para o padrão que deseja adicionar. Por exemplo, adicione uma propriedade pattern1 com o valor Fax=text{99-999-999999}. O padrão está disponível para todas as caixas de texto usadas no Adaptive Forms.

    Criação de padrões personalizados para campos no CrxDe

    Criação de padrões personalizados

Nesta página