DocumentaçãoAEM 6.4Guia de desenvolvimento

Desenvolvimento do Forms (interface clássica) developing-forms-classic-ui

Last update: Thu May 04 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

Criado para:

  • Desenvolvedor
CAUTION
AEM 6.4 chegou ao fim do suporte estendido e esta documentação não é mais atualizada. Para obter mais detalhes, consulte nossa períodos de assistência técnica. Encontre as versões compatíveis here.

A estrutura básica de um formulário é:

  • Início do formulário
  • Elementos de formulário
  • Fim do formulário

Todos estes são realizados com uma série de padrões Componentes do formulário, disponível em uma instalação AEM padrão.

Além de desenvolvimento de novos componentes para uso em formulários, você também pode:

Uso de scripts estender a funcionalidade, quando necessário.

NOTE
Este documento se concentra no desenvolvimento de formulários usando o Componentes básicos na interface clássica. A Adobe recomenda o aproveitamento do novo Componentes principais e Ocultar Condições para desenvolvimento de formulário na interface habilitada para toque.

Pré-carregar valores do formulário preloading-form-values

O componente de início do formulário fornece um campo para a variável Carregar caminho, um caminho opcional que aponta para um nó no repositório.

O Caminho de carregamento é o caminho para as propriedades do nó, usado para carregar valores predefinidos em vários campos no formulário.

Este é um campo opcional que especifica o caminho para um nó no repositório. Quando esse nó tem propriedades que correspondem aos nomes dos campos, os campos apropriados no formulário são pré-carregados com o valor dessas propriedades. Se não houver correspondência, o campo conterá o valor padrão.

NOTE
A ação de formulário também pode definir o recurso do qual carregar os valores iniciais. Isso é feito usando FormsHelper#setFormLoadResource inside init.jsp.
Somente se isso não for definido, o formulário será preenchido a partir do caminho definido no componente de formulário inicial pelo autor.

Pré-carregamento de campos de formulário com vários valores preloading-form-fields-with-multiple-values

Vários campos de formulário também têm a variável Caminho de carregamento dos itens, novamente um caminho opcional que aponta para um nó no repositório.

O Caminho de carregamento dos itens é o caminho para as propriedades do nó, usado para carregar valores predefinidos nesse campo específico do formulário, por exemplo, um lista suspensa, grupo de caixas de seleção ou grupo de rádio.

Exemplo - Pré-Carregamento De Uma Lista Suspensa Com Vários Valores example-preloading-a-dropdown-list-with-multiple-values

Uma lista suspensa pode ser configurada com o intervalo de valores para seleção.

O Caminho de carregamento dos itens pode ser usada para acessar uma lista de uma pasta no repositório e pré-carregá-las no campo :

  1. Crie uma nova pasta sling ( sling:Folder)

    por exemplo, /etc/designs/<myDesign>/formlistvalues

  2. Adicionar uma nova propriedade (por exemplo, myList) do tipo string com vários valores ( String[]) para conter a lista de itens suspensos. O conteúdo também pode ser importado usando um script, como com um script JSP ou cURL em um script de shell.

  3. Use o caminho completo na Caminho de carregamento dos itens campo :

    por exemplo, /etc/designs/geometrixx/formlistvalues/myList

Observe que se os valores na variável String[] são formatadas desta forma:

  • AL=Alabama
  • AK=Alaska
  • etc.

então AEM gerará a lista como:

  • <option value="AL">Alabama</option>
  • <option value="AK">Alaska</option>

Esse recurso pode, por exemplo, ser aproveitado em uma configuração de vários idiomas.

Desenvolvimento de suas próprias ações de formulário developing-your-own-form-actions

Um formulário precisa de uma ação. Uma ação define a operação que é executada quando o formulário é enviado com os dados do usuário.

Uma variedade de ações são fornecidas com uma instalação padrão do AEM, essas ações podem ser vistas em:

/libs/foundation/components/form/actions

e na Tipo de ação lista de Formulário componente:

chlimage_1-226

Esta seção aborda como você pode desenvolver sua própria ação de formulário para inclusão nesta lista.

Você pode adicionar sua própria ação em /apps como se segue:

  1. Criar um nó do tipo sling:Folder. Especifique um nome que reflita a ação a ser implementada.

    Por exemplo:

    /apps/myProject/components/customFormAction

  2. Nesse nó, defina as seguintes propriedades e clique em Salvar tudo para continuar suas alterações:

    • sling:resourceType - definido como foundation/components/form/action

    • componentGroup - definir como .hidden

    • Opcionalmente:

      • jcr:title - especifique um título de sua escolha, que será exibido na lista suspensa de seleção. Se não estiver definido, o nome do nó será mostrado
      • jcr:description - insira uma descrição da sua escolha

  3. Na pasta, crie um nó de diálogo:

    1. Adicione campos para que o autor possa editar a caixa de diálogo de formulários depois que a ação for escolhida.

  4. Na pasta, crie:

    1. Um script de postagem.

      O nome do script é post.POST.<extension>, por exemplo post.POST.jsp

      O script de publicação é chamado quando um formulário é enviado para processar o formulário, ele contém o código que manipula os dados que chegam do formulário POST.

    2. Adicione um script forward que é chamado quando o formulário é enviado.

      O nome do script é forward.<extension>, por exemplo forward.jsp

      Esse script pode definir um caminho. A solicitação atual é encaminhada ao caminho especificado.
      A chamada necessária é FormsHelper#setForwardPath (2 variantes). Um caso típico é executar alguma validação, ou lógica, para encontrar o caminho de destino e, em seguida, avançar para esse caminho, permitindo que o servlet Sling POST padrão faça o armazenamento real no JCR.

    Também pode haver outro servlet que faça o processamento real, nesse caso, a ação do formulário e a variável forward.jsp atuaria somente como o código de "cola". Um exemplo disso é a ação de email em /libs/foundation/components/form/actions/mail, que encaminha detalhes para <currentpath>.mail.htmlonde um servlet de email está.

    Assim:

    • a post.POST.jsp é útil para pequenas operações plenamente realizadas pela própria ação
    • enquanto a variável forward.jsp é útil quando somente a delegação é necessária.

    A ordem de execução dos scripts é:

    • Ao renderizar o formulário ( GET):

      1. init.jsp
      2. para todas as restrições do campo: clientvalidation.jsp
      3. validationRT do formulário: clientvalidation.jsp
      4. O formulário é carregado por meio do recurso de carregamento, se definido
      5. addfields.jsp ao processar <form></form>

    • ao manusear um formulário POST:

      1. init.jsp
      2. para todas as restrições do campo: servervalidation.jsp
      3. validationRT do formulário: servervalidation.jsp
      4. forward.jsp
      5. se um caminho de encaminhamento foi definido ( FormsHelper.setForwardPath), encaminhe a solicitação e chame cleanup.jsp
      6. se nenhum caminho de encaminhamento foi definido, chame post.POST.jsp (termina aqui, não cleanup.jsp chamado)

  5. Novamente na pasta, opcionalmente, adicione:

    1. Um script para adicionar campos.

      O nome do script é addfields.<extension>, por exemplo addfields.jsp

      Um script addfields é chamado imediatamente após o HTML para o início do formulário ser gravado. Isso permite que a ação adicione campos de entrada personalizados ou outro HTML dentro do formulário.

    2. Um script de inicialização.

      O nome do script é init.<extension>, por exemplo init.jsp

      Esse script é chamado quando o formulário é renderizado. Ele pode ser usado para inicializar ações específicas. "

    3. Um script de limpeza.

      O nome do script é cleanup.<extension>, por exemplo cleanup.jsp

      Esse script pode ser usado para realizar a limpeza.

  6. Use o Forms em um parsys. O Tipo de ação a lista suspensa agora incluirá sua nova ação.

    note note
    NOTE
    Para ver as ações padrão que fazem parte do produto:
    /libs/foundation/components/form/actions

Desenvolvimento de suas próprias restrições de formulário developing-your-own-form-constraints

As restrições podem ser impostas em dois níveis:

Restrições para campos individuais constraints-for-individual-fields

É possível adicionar suas próprias restrições para um campo individual (em /apps) como segue:

  1. Criar um nó do tipo sling:Folder. Especifique um nome que reflita a restrição a ser implementada.

    Por exemplo:

    /apps/myProject/components/customFormConstraint

  2. Nesse nó, defina as seguintes propriedades e clique em Salvar tudo para continuar suas alterações:

    • sling:resourceType - defina como foundation/components/form/constraint

    • constraintMessage - uma mensagem personalizada que será exibida se o campo não for válido, de acordo com a restrição, quando o formulário for enviado

    • Opcionalmente:

      • jcr:title - especifique um título de sua escolha, que será exibido na lista de seleção. Se não estiver definido, o nome do nó será mostrado
      • hint - informações adicionais, para o usuário, sobre como usar o campo

  3. Nessa pasta, você pode precisar dos seguintes scripts:

    • Um script de validação de cliente:

      O nome do script é clientvalidation.<extension>, por exemplo clientvalidation.jsp

      Isso é chamado quando o campo de formulário é renderizado. Ele pode ser usado para criar o javascript cliente para validar o campo no cliente.

    • Um script de validação de servidor:

      O nome do script é servervalidation.<extension>, por exemplo servervalidation.jsp

      Isso é chamado quando o formulário é enviado. Ele pode ser usado para validar o campo no servidor após o envio.

NOTE
Restrições de amostra podem ser vistas em:
/libs/foundation/components/form/constraints

Restrições globais de formulário form-global-constraints

A validação global do formulário é especificada pela configuração de um tipo de recurso no componente do formulário inicial ( validationRT). Por exemplo:

apps/myProject/components/form/validation

Em seguida, é possível definir:

  • a clientvalidation.jsp - inserido após os scripts de validação de cliente do campo
  • e servervalidation.jsp - também é chamado após as validações individuais do servidor de campo em um POST.

Mostrar e ocultar componentes de formulário showing-and-hiding-form-components

É possível configurar o formulário para mostrar ou ocultar os componentes do formulário de acordo com o valor de outros campos no formulário.

Alterar a visibilidade de um campo de formulário é útil quando o campo é necessário somente em condições específicas. Por exemplo, em um formulário de feedback, uma pergunta pergunta faz com que os clientes queiram que as informações do produto sejam enviadas a eles por email. Ao selecionar sim, um campo de texto é exibido para permitir que o cliente digite seu endereço de email.

Use o Editar Mostrar/Ocultar Regras caixa de diálogo para especificar as condições em que um componente de formulário é exibido ou oculto.

editor de texto

Use os campos na parte superior da caixa de diálogo para especificar as seguintes informações:

  • Se você estiver especificando as condições para ocultar ou mostrar o componente.
  • Se alguma ou todas as condições precisam ser verdadeiras para mostrar ou ocultar o componente.

Uma ou mais condições são exibidas abaixo desses campos. Uma condição compara o valor de outro componente de formulário (no mesmo formulário) a um valor. Se o valor real no campo atender à condição, a condição avaliará como true. As condições incluem as seguintes informações:

  • O Título do campo de formulário testado.
  • Um operador.
  • Um valor em relação a com o valor do campo é comparado.

Por exemplo, um componente Grupo de opções com o título Receive email notifications?* * contém Yes e No botões de opção. Um componente Campo de texto com o título de Email Address O usa a seguinte condição para que ela fique visível se Yes está selecionada:

showwhidcondition

No Javascript, as condições usam o valor da propriedade Nome do elemento para fazer referência aos campos. No exemplo anterior, a propriedade Nome do elemento do componente Grupo de opções é contact. O código a seguir é o código JavaScript equivalente para esse exemplo:

((contact == "Yes"))

Para mostrar ou ocultar um componente de formulário:

  1. Edite o componente de formulário específico.

  2. Selecionar Mostrar / Ocultar para abrir o Editar Mostrar / Ocultar Regras caixa de diálogo:

    • Na primeira lista suspensa, selecione Mostrar ou Ocultar para especificar se suas condições determinam se deseja mostrar ou ocultar o componente.

    • Na lista suspensa no final da linha superior, selecione:

      • all - se todas as condições devem ser verdadeiras para mostrar ou ocultar o componente
      • any - se apenas uma ou mais condições devem ser verdadeiras para mostrar ou ocultar o componente

    • Na linha de condição (uma é apresentada como padrão), selecione um componente, operador e especifique um valor.

    • Adicione mais condições, se necessário, clicando em Adicionar condição.

    Por exemplo:

    chlimage_1-227

  3. Clique em OK para salvar a definição.

  4. Depois de salvar sua definição, um Editar regras é exibido ao lado do Mostrar / Ocultar nas propriedades do componente de formulário. Clique neste link para abrir o Editar Mostrar / Ocultar Regras para fazer alterações.

    Clique em OK para salvar todas as alterações.

    chlimage_1-228

    note caution
    CAUTION
    Os efeitos das definições Mostrar/Ocultar podem ser vistos e testados:
    • em Visualizar no ambiente do autor (precisa de um recarregamento de página ao alternar para a visualização)
    • no ambiente de publicação

Lidar com referências de componentes quebrados handling-broken-component-references

As condições de mostrar/ocultar usam o valor da propriedade Nome do elemento para fazer referência a outros componentes no formulário. A configuração Mostrar/Ocultar é inválida quando qualquer uma das condições se refere a um componente que é excluído ou que teve a propriedade Nome do Elemento alterada. Quando essa situação ocorre, é necessário atualizar manualmente as condições ou ocorre um erro quando o formulário é carregado.

Quando a configuração Mostrar/Ocultar é inválida, a configuração é fornecida somente como código JavaScript. Edite o código para corrigir os problemas. O código usa a propriedade Nome do elemento que foi originalmente usada para fazer referência aos componentes.

Desenvolvimento de scripts para uso com o Forms developing-scripts-for-use-with-forms

Para obter mais informações sobre os elementos da API que podem ser usados ao gravar scripts, consulte o javadocs relacionados a formulários.

É possível usar essa opção para ações como chamar um serviço antes do envio do formulário e cancelar o serviço em caso de falha:

  • Definir o tipo de recurso de validação

  • Incluir um script para validação:

    • No JSP, chame o serviço da Web e crie um com.day.cq.wcm.foundation.forms.ValidationInfo objeto que contém suas mensagens de erro. Se houver erros, os dados do formulário não serão publicados.
recommendation-more-help
2315f3f5-cb4a-4530-9999-30c8319c520e