Expressões de formulário adaptável adaptive-form-expressions

O Adobe recomenda o uso de Componentes principaisde captura de dados moderna e extensível para criar um novo Forms Adaptávelou adicionar o Forms Adaptável às páginas do AEM Sites. Esses componentes representam um avanço significativo na criação do Forms adaptável, garantindo experiências de usuário impressionantes. Este artigo descreve a abordagem mais antiga para criar o Forms adaptável usando componentes de base.

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

O JavaScript é o idioma de expressão dos 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 best-practices-for-writing-expressions

Práticas recomendadas para expressões envolvendo o painel de repetição best-practices-for-expressions-involving-repeating-panel

Os painéis repetitivos são instâncias de um painel que são adicionadas ou removidas dinamicamente, usando a API de script ou dados pré-preenchidos. Para obter informações detalhadas sobre como usar o painel de repetição, consulte criação de formulários com seções repetíveis.

Tipos de expressão expression-types

Nos formulários adaptáveis, é possível escrever expressões para adicionar comportamentos, como campos e painéis de exibição/ocultação dinâmicos. Você também pode escrever expressões para adicionar campos calculados, tornar os campos somente leitura, lógica de validação e muito mais. Os formulários adaptáveis oferecem suporte às seguintes expressões:

Expressão de acesso (expressão de ativação) access-expression-enablement-expression

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á acionada novamente.

Aplica-se a: campos

Tipo de Retorno: a expressão retorna um valor Booleano, representando se o campo está habilitado ou desabilitado. true representa que o campo está habilitado e false representa que o campo está desabilitado.

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

Calcular expressão calculate-expression

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á disparada novamente 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 de cálculo para mostrar a soma de dois campos em campo1 é:
field2.value + field3.value

Expressão de clique click-expression

A expressão de clique lida com as ações executadas no evento de clique de um botão. Imediatamente, o GuideBridge fornece APIs para executar várias funções, como enviar, validar, que são usadas junto com a expressão de clique. Para obter a lista completa das APIs, consulte APIs do GuideBridge.

Aplica-se a: campos de botão

Tipo de Retorno: a expressão de clique não retorna nenhum valor. Se qualquer expressão retornar um valor, ele 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 initialization-script

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:

Aplica-se a: campos e painel

Tipo de Retorno: A expressão de script de Inicialização não retorna nenhum valor. Se qualquer expressão retornar um valor, ele será ignorado.

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

Expressão de opções options-expression

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 de opções retorna uma matriz de valores de cadeia de caracteres. Cada valor pode ser uma sequência simples, como Masculino, ou em um formato de par chave=valor, 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, Número de Filhos, com base no Estado Civil 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á acionada novamente. Você também pode preencher a lista suspensa de um serviço REST. Para obter informações detalhadas, consulte Preencher menus suspensos dinamicamente.

Expressão de resumo summary

A expressão Resumo calcula dinamicamente o título de um painel secundário de um painel de layout do Accordion. Você pode especificar a expressão Summary 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 você estiver preenchendo previamente um formulário, a expressão será executada após o preenchimento prévio dos dados ou quando o valor dos campos dependentes usados na expressão for alterado.

A expressão Resumo é normalmente usada para repetir filhos de um painel de layout de acordeão a fim de fornecer um título significativo para cada painel filho.

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

Tipo de retorno: a expressão retorna uma Cadeia de caracteres que se torna o título do acordeão.

Exemplo: "Número da conta : " + textbox1.value

Validar expressão validate-expression

A expressão validate é usada para validar os campos usando a expressão fornecida. Normalmente, essas expressões usam expressões regulares junto com o valor do campo para validar um campo. A expressão é acionada novamente 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 booliano, 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 o código postal do Reino Unido, a expressão de validação é:

(este.valor && 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 não vazio não corresponder ao padrão, a expressão retornará false para indicar que o campo não é válido.

Script de Value Commit value-commit-script

O script de Value Commit é acionado quando:

Aplica-se a: campos

Tipo de Retorno: A expressão de script de confirmação de valor não retorna nenhum valor. Se qualquer expressão retornar um valor, ele será ignorado.

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

Expressão de visibilidade visibility-expression

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

Aplica-se a: campos e painel

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

Exemplo: para um painel que se torna visível somente se o valor de campo1 for definido como Macho, a expressão de visibilidade será: field1.value == "Male"

Expressão de conclusão da etapa step-completion-expression

A expressão de conclusão da etapa é usada para impedir que um usuário vá para a próxima etapa de um layout do 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 mover para a próxima etapa, painel ou subseção somente se todos os valores necessários na seção atual estiverem preenchidos e forem válidos.

Aplica-se a: painéis com layout de item definido como assistente.

Tipo de Retorno: a expressão retorna um valor Booleano, representando que o painel atual é válido ou não. True 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 para o próximo painel, o painel atual é validado. Nesses casos, as expressões de conclusão da etapa são usadas. Geralmente, essas expressões usam a API de validação do 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 validations-in-adaptive-form

Há vários métodos para adicionar 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. False representa que o valor é inválido. Se você inserir e sair por tabulação em um campo, a mensagem de erro não será gerada.

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

Obrigatório required

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

Padrões de validação validation-patterns

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 à cláusula Picture para formulários HTML5.

Expressões de validação validation-expressions

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 additional-information

Utilização do formato de exibição de campo using-field-display-format

O 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, código postal de formato ou seletor de datas. 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 guidebridge-apis-and-events

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

Uso do GuideBridge em várias expressões guidebridge-usage-in-various-expressions

Usando expressões externas do GuideBridge  using-guidebridge-outside-expressions-nbsp

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

Para usar a API do GuideBridge para o exemplo mencionado acima, capture uma instância do GuideBridge. Para capturar a instância, escute o bridgeInitializeStartevento de um window objeto:

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

     })

})

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

Eventos do GuideBridge guidebridge-events

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

Use o código a seguir 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 creating-custom-patterns-for-a-field

Como mencionado acima, os formulários adaptáveis permitem que o autor forneça padrões para validação ou formatos de exibição. Além de usar padrões prontos para uso, é possível definir um padrão personalizado reutilizável para um componente de formulário adaptável. Por exemplo, você pode definir um campo de texto ou numérico. Depois de definido, é possível 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 de edição de um componente. Para obter detalhes sobre definição ou formato de Padrão, consulte Suporte à cláusula Picture 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: