Práticas recomendadas para trabalhar com formulários adaptáveis best-practices-for-working-with-adaptive-forms

Use o Apache Maven aem-project-archetype para criar e gerenciar a estrutura do projeto AEM. Ele cria a estrutura e os modelos recomendados para o projeto AEM. Além disso, fornece sistemas de automação de build e controle de alterações para ajudar a gerenciar o projeto.

• Use o comando maven archetype:generate para gerar a estrutura inicial.
• Use o comando maven eclipse:eclipse para gerar os arquivos de projeto do eclipse e importar o projeto para o eclipse.

A ferramenta FileVault ou VLT ajuda a mapear o conteúdo de uma instância CRX ou AEM para o seu sistema de arquivos. Ele fornece operações de gerenciamento de controle de alterações, como check-in e check-out do conteúdo do projeto AEM. Consulte Como usar a Ferramenta VLT.

Se você usar um ambiente de desenvolvimento integrado ao Eclipse, poderá usar as ferramentas do desenvolvedor do AEM para integração perfeita do Eclipse IDE com as instâncias do AEM para criar aplicativos do AEM. Para obter detalhes, consulte as ferramentas para desenvolvedores do AEM para Eclipse.

Não armazene conteúdo nem faça modificações na pasta /libs. Crie sobreposições nas pastas /app para estender ou substituir as funcionalidades padrão.

Ao criar pacotes para mover o conteúdo, certifique-se de que os caminhos de filtro de pacote estejam corretos e que apenas os caminhos necessários sejam mencionados.

Não armazene conteúdo nem faça modificações na pasta /libs. Crie sobreposições nas pastas /app para estender ou substituir as funcionalidades padrão.

Defina as dependências corretas para os pacotes para forçar uma ordem/sequência de instalação predeterminada.

Não crie nenhum nó referenciável em /libs ou /apps.

Um modelo de formulário adaptável é uma página AEM especializada que define a estrutura e as informações do cabeçalho-rodapé de um formulário adaptável. Um modelo tem layouts, estilos e estrutura básica pré-configurados para um formulário adaptável. O AEM Forms fornece modelos e componentes prontos para uso que você pode usar para criar formulários adaptáveis. No entanto, você pode criar modelos e componentes personalizados de acordo com seus requisitos. É recomendável coletar os requisitos para modelos e componentes adicionais necessários em seus formulários adaptáveis. Para obter detalhes, consulte Personalização de formulários e componentes adaptáveis.

É recomendável carregar os pacotes de formulários usando a interface do usuário do Gerenciador de formulários em vez da interface do Gerenciador de pacotes do CRX, pois o carregamento de pacotes por meio do Gerenciador de pacotes do CRX pode, às vezes, causar anomalias.

O AEM Forms permite criar formulários adaptáveis com base nos seguintes modelos de formulário. Os modelos de formulário atuam como interface para a troca de dados entre um formulário e um sistema AEM e fornecem uma estrutura baseada em XML para o fluxo de dados dentro e fora de um formulário adaptável. Além disso, os modelos de formulário impõem regras e restrições aos formulários adaptáveis na forma de restrições de esquema e XFA.

• Nenhum: os formulários adaptáveis criados com esta opção não usam nenhum modelo de formulário. O XML de dados gerado desses formulários tem uma estrutura simples com campos e valores correspondentes.
• Esquema XML ou JSON: os esquemas XML e JSON representam a estrutura em que os dados são produzidos ou consumidos pelo sistema back-end em sua organização. Você pode associar um esquema a um formulário adaptável e usar seus elementos para adicionar conteúdo dinâmico ao formulário adaptável. Os elementos do esquema estão disponíveis na guia Objeto de modelo de dados do navegador de conteúdo para a criação de formulários adaptáveis. Você pode arrastar e soltar os elementos do esquema para criar o formulário.
• Modelo de formulário XFA: é um modelo de formulário ideal se você tem investimentos em formulários HTML5 baseados em XFA. Ele fornece uma maneira direta de converter seus formulários baseados em XFA em formulários adaptáveis. Quaisquer regras XFA existentes são mantidas nos formulários adaptáveis associados. Os formulários adaptáveis resultantes são compatíveis com construções XFA, como validações, eventos, propriedades e padrões.
• Modelo de dados de formulário: é um modelo de formulário preferido se você estiver procurando integrar seus sistemas de back-end, como bancos de dados, serviços da Web e perfil de usuário AEM, para preencher previamente formulários adaptáveis e gravar dados de formulário enviados nos sistemas de back-end. Um editor de modelo de dados de formulário permite definir e configurar entidades e serviços em um modelo de dados de formulário que você pode usar para criar formulários adaptáveis. Para obter mais informações, consulte Integração de dados do AEM Forms.

O AEM Forms fornece modelos de formulário adaptáveis prontos para uso que você pode usar para criar formulários adaptáveis. Você também pode criar seus próprios templates. O AEM fornece modelos estáticos e editáveis.

• Os modelos estáticos são definidos e configurados pelos desenvolvedores.
• Os modelos editáveis são criados pelos autores usando o editor de modelos. O editor de modelos permite definir uma estrutura básica e o conteúdo inicial em um modelo. Qualquer modificação na camada da estrutura é refletida em todos os formulários que usam esse modelo. O conteúdo inicial pode incluir tema pré-configurado, serviço de preenchimento prévio, ação de envio e assim por diante. No entanto, essas configurações podem ser modificadas para um formulário usando o editor de formulários. Para obter mais informações, consulte Modelos de formulário adaptável.

Para estilizar uma instância específica de campo ou painel, use estilo em linha. Como alternativa, você pode definir uma classe em um arquivo CSS e especificar o nome da classe na propriedade Classe CSS do componente.

Inclua uma biblioteca do cliente em um componente para aplicar estilos de forma consistente em formulários ou fragmentos adaptáveis que usam esse componente. Para obter mais informações, consulte Criar um componente de página de formulário adaptável.

Aplique os estilos definidos em uma biblioteca do cliente para selecionar formulários adaptáveis, especificando o caminho para a biblioteca do cliente no campo Caminho do arquivo CSS nas propriedades do contêiner de formulários adaptáveis.

Para criar uma biblioteca cliente de seus estilos, você pode configurar o arquivo CSS personalizado na clientlib base do Editor de temas ou nas propriedades do Contêiner de formulário.

Os formulários adaptáveis fornecem layouts de painel, como responsivo, com guias, acordeões e assistente, para controlar como os componentes de formulário são posicionados em um painel. É possível criar layouts de painel personalizados e disponibilizá-los para uso por autores de formulário. Para obter mais informações, consulte Criação de componentes de layout personalizados para formulários adaptáveis.

Você também pode personalizar componentes específicos do formulário adaptável, como campos e layout do painel.

• Use a funcionalidade de Sobreposição do AEM para modificar uma cópia de um componente. Não é recomendável modificar componentes padrão.
• Para personalizar o layout dos componentes de formulário adaptáveis prontos para uso em /libs, crie componentes de layout personalizados, além dos layouts padrão.
• Introduza interatividades personalizadas criando widgets ou aparências personalizados. Não é recomendável modificar componentes padrão. Para obter mais informações, consulte Estrutura de aparência.

Consulte Manipulando informações de identificação pessoal para obter recomendações sobre como manipular dados de PII.

Use o navegador de Objetos na barra lateral para acessar rapidamente os campos no fundo da hierarquia de formulários. Você pode usar a caixa de pesquisa para procurar objetos no formulário ou na árvore de objetos para navegar de um objeto para outro.

Para exibir e editar as propriedades de um componente no navegador de componentes na barra lateral, selecione o componente e clique em . Você também pode clicar duas vezes em um componente para exibir suas propriedades no navegador de propriedades.

Use atalhos de teclado para executar ações rápidas em seus formulários. Consulte Atalhos de teclado do AEM Forms.

Os componentes de formulários adaptáveis são recomendados para uso somente em páginas de formulários adaptáveis. Os componentes têm dependência em sua hierarquia pai. Portanto, não os use em uma página de AEM.

Use nomes significativos e exclusivos para campos de formulário e componentes para evitar possíveis conflitos ao escrever regras.

Use o operador this para um componente se referir a si mesmo em uma expressão de regra. Ela garante que a regra permaneça válida mesmo se o nome do componente for alterado. Por exemplo, field1.valueCommit script: this.value > 10.

Usar nomes de componentes ao fazer referência a outros componentes de formulário. Use a propriedade value para buscar o valor de um campo ou componente. Por exemplo, field1.value.

Consulte os componentes por hierarquia exclusiva relativa para evitar conflitos. Por exemplo, parentName.fieldName.

Ao lidar com regras complexas ou de uso comum, considere escrever lógica de negócios como funções em uma biblioteca do cliente separada que você pode especificar e reutilizar em formulários adaptáveis. A biblioteca do cliente deve ser uma biblioteca independente e não deve ter dependências externas, exceto em jQuery e Underscore.js. Você também pode usar a biblioteca do cliente para impor a revalidação do lado do servidor dos dados de formulário enviados.

Os formulários adaptáveis fornecem um conjunto de APIs que você pode usar para se comunicar e executar ações em formulários adaptáveis. Algumas das principais APIs são as seguintes. Para obter mais informações, consulte Referência da API da Biblioteca JavaScript para Forms Adaptável.

• guideBridge.reset(): Redefine um formulário.

• guideBridge.submit(): envia um formulário.

• guideBridge.setFocus(somExp, focusOption, runCompletionExp): define o foco para um campo.

• guideBridge.validate(errorList, somExpression, focus): valida um formulário.

• guideBridge.getDataXML(options): Obtém dados de formulário como XML.

• guideBridge.resolveNode(somExpression): Obtém um objeto de formulário.

• guideBridge.setProperty(somList, propertyName, valueList): define a propriedade de um objeto de formulário.

• Além disso, você pode usar as seguintes propriedades de campo:

  • field.value para alterar o valor de um campo.
  • field.enabled para ativar/desativar um campo.
  • field.visible para alterar a visibilidade de um campo.

Os autores do formulário adaptável podem precisar escrever código JavaScript para criar lógica de negócios em um formulário. Embora o JavaScript seja eficiente, ele provavelmente comprometerá as expectativas de segurança. Portanto, você deve garantir que o autor do formulário seja uma pessoa confiável e que haja processos para revisar e aprovar o código JavaScript antes que um formulário seja colocado em produção. O administrador pode restringir o acesso ao editor de regras a grupos de usuários com base em sua função. Consulte Conceder acesso ao editor de regras para grupos de usuários selecionados.

Você pode usar expressões em regras para tornar formulários adaptáveis dinâmicos. 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 mais informações sobre expressões e práticas recomendadas, consulte Expressões de formulários adaptáveis.

O Adobe recomenda usar operações síncronas do JavaScript em vez de operações assíncronas ao criar regras com o editor de regras. O uso de operações assíncronas é altamente desencorajado. No entanto, se você estiver em uma situação em que as operações assíncronas são inevitáveis, é essencial implementar as funções de Fechamento do JavaScript. Ao fazer isso, você pode se proteger efetivamente contra possíveis condições de corrida, garantindo que as implementações de regras forneçam o melhor desempenho e mantenham a estabilidade em todo o.

Por exemplo, vamos supor que precisamos buscar dados de uma API externa e, em seguida, aplicar algumas regras com base nesses dados. Usamos um fechamento para lidar com a chamada de API assíncrona e garantir que as regras sejam aplicadas após a busca dos dados. Este é o código de exemplo:

     function fetchDataFromAPI(apiEndpoint, callback) {
      // Simulate asynchronous API call with setTimeout
      setTimeout(() => {
        // Assuming the API call is successful, we receive some data
        const data = {
          someValue: 42,
        };
        // Invoke the callback with the fetched data
        callback(data);
      }, 2000); // Simulate a 2-second delay for the API call
    }
    // Rule implementation using Closure
    function ruleImplementation(apiEndpoint) {
      // Using a closure to handle the asynchronous API call and rule application
      // say you have set this value in street field inside address panel
      var streetField = address.street;
      fetchDataFromAPI(apiEndpoint, (data) => {
        streetField.value = data.someValue;
      });
    }
    // Example usage of the rule implementation
    const apiEndpoint = "https://example-api.com/data";
    ruleImplementation(apiEndpoint);

Neste exemplo, fetchDataFromAPI simula uma chamada de API assíncrona usando setTimeout. Depois que os dados são buscados, ele chama a função de retorno de chamada fornecida, que é o fechamento para lidar com a aplicação de regra subsequente. A função ruleImplementation contém a lógica da regra.

É recomendável criar formulários adaptáveis usando o modelo de dados de formulário XSD, mesmo ao converter um XFA em um formulário adaptável, se possível.

Inclua apenas os campos e painéis em formulários adaptáveis que capturem informações do usuário. Considere manter o conteúdo estático mínimo ou use URLs para abri-los em uma janela separada.

Embora cada formulário seja projetado para uma finalidade específica, há alguns segmentos comuns na maioria dos formulários. Por exemplo, detalhes pessoais, endereço, detalhes de emprego e assim por diante. Crie fragmentos de formulário adaptáveis para elementos de formulário e seções comuns e use-os em formulários. Também é possível salvar um painel em um formulário existente como um fragmento. Qualquer alteração em um fragmento é refletida em todos os formulários adaptáveis associados. Ele promove a criação colaborativa, pois vários autores podem trabalhar simultaneamente em diferentes fragmentos que compõem um formulário.

• Semelhante aos formulários adaptáveis, é recomendável que todo o estilo específico do fragmento e os scripts personalizados sejam definidos na biblioteca do cliente usando a caixa de diálogo do contêiner do fragmento. Além disso, tente criar fragmentos autossuficientes que não dependam de objetos fora dele.
• Evite usar script de fragmentos cruzados. Se houver algum objeto fora do fragmento ao qual você deve se referir, tente tornar esse objeto uma parte do formulário principal. Se o objeto ainda precisar residir em outro fragmento, consulte-o pelo seu nome no script.

Use Salvar e retomar com o salvamento automático para salvar o formulário adaptável periodicamente e permitir que os usuários visitem novamente mais tarde para preencher o formulário.

Configurar fragmentos para carregar lentamente. No tempo de execução, os fragmentos marcados para carregamento lento são renderizados somente quando necessários. Ele reduz significativamente o tempo de carregamento de formulários grandes. Também é compatível com fragmentos com painéis repetíveis. Para obter mais informações, consulte Configurar carregamento lento.

• Não configure o carregamento lento em fragmentos em um layout de grade responsivo ou no primeiro painel.
• Os componentes de Anexos de arquivo e Termos e condições não são compatíveis com fragmentos carregados lentamente.
• Marque um valor em um painel carregado lento como Usar valor globalmente se esse valor for usado em alguma outra parte do formulário, de modo que o valor esteja disponível para uso quando o painel que o contém for descarregado.
• Considere escrever regras de visibilidade para fragmentos que devem ser exibidos ou ocultados com base em uma condição.

Defina o valor de Número de chamadas por solicitação no Apache Sling Main Servlet para um número relativamente grande. Ela permite que o servidor do Forms permita chamadas adicionais. A configuração exibe um valor padrão de 1500. O valor, 1500 chamadas, é para outros componentes de Experience Manager, como Sites e Assets. O conjunto de valores padrão de formulários adaptáveis é 20000. Se você encontrar o erro too many calls em logs ou o formulário não for renderizado, tente aumentar o valor para um número grande para resolver o problema. Se o número de chamadas exceder 20000, significa que o formulário é complexo e pode levar algum tempo para renderizar o formulário no navegador. Isso só acontece na primeira vez que o formulário é carregado, depois que ele é armazenado em cache e, uma vez armazenado em cache, não há impacto significativo no desempenho.

O AEM Forms fornece um serviço de preenchimento prévio para ler dados de um arquivo XML de dados predefinido e preencher previamente os campos de um formulário adaptável com o conteúdo no arquivo XML de preenchimento prévio.

O XML de dados de preenchimento prévio deve ser compatível com o esquema do modelo de formulário associado ao formulário adaptável.

Inclua seções afBoundedData e afUnBoundedData no XML de preenchimento prévio para preencher previamente campos ligados e não ligados em um formulário adaptável.

Para formulários adaptáveis com base no modelo de dados de formulário, o AEM Forms fornece o Serviço de preenchimento prévio do modelo de dados de formulário pronto para uso. O serviço de preenchimento consulta fontes de dados para objetos de modelo de dados no formulário adaptável e preenche valores de campo ao renderizar o formulário.

Você também pode usar os protocolos de arquivo, crx, serviço ou http para preencher previamente formulários adaptáveis.

O AEM Forms oferece suporte a serviços de preenchimento prévio personalizados que você pode conectar como um serviço OSGi para preencher previamente formulários adaptáveis.

Dependendo do modelo de dados de formulário em que um formulário adaptável é baseado, você pode configurar um modelo para DoR da seguinte maneira:

• Modelo de formulário XFA: use o arquivo XDP associado como modelo do DoR.
• Esquema XSD: use o modelo XFA associado que usa o mesmo esquema XML usado pelo formulário adaptável.
• Nenhum: usar DoR gerado automaticamente.

Configure cabeçalho, rodapé, imagens, cor, fonte e assim por diante, diretamente da guia Documento de registro do editor de formulário adaptável.

Use DoRService para gerar o DoR de forma programática.

Excluir campos ocultos do DoR.

Use o parâmetro de solicitação afAcceptLang para exibir DoR em outra localidade.

Use fragmentos de formulário adaptáveis para elementos comuns em formulários e localizar fragmentos. Ela garante que você localize um fragmento uma vez e reflita em todas as formas em que o fragmento localizado é usado.

Quaisquer modificações como adicionar um novo componente ou aplicar um script em um formulário localizado não são localizadas automaticamente. Portanto, você deve finalizar um formulário antes de localizá-lo para evitar vários ciclos de localização.

Use o parâmetro de solicitação afAcceptLang para substituir a localidade do navegador e renderizar o formulário na localidade especificada. Por exemplo, a URL a seguir é forçada a renderizar o formulário na localidade japonesa, independentemente da localidade especificada na configuração do navegador:

https://'[server]:[port]'/<contextPath>/<formFolder>/<formName>.html?wcmmode=disabled&afAcceptLang=ja

Atualmente, o AEM Forms oferece suporte à localização de conteúdo de formulários adaptáveis em inglês (en), espanhol (es), francês (fr), italiano (it), alemão (de), japonês (ja), português-brasileiro (pt-BR), chinês (zh-CN), chinês-Taiwan (zh-TW) e coreano (ko-KR). No entanto, você pode adicionar suporte para novos locais para formulários adaptáveis no tempo de execução. Para obter mais informações, consulte Suporte a novas localidades para localização de formulários adaptáveis.

Ative a compactação da biblioteca do cliente HTML para JavaScript e CSS a partir do Felix Console.

Armazene em cache todas as bibliotecas de clientes em /etc.clientlibs/fd e qualquer biblioteca de clientes personalizada adicional no Dispatcher AEM para aumentar a capacidade de resposta e a segurança de seus formulários publicados. Para obter mais informações, consulte Dispatcher.

Não armazenar em cache os caminhos /content/forms/af/ e /content/dam/formsanddocuments/*. para obter informações detalhadas sobre como configurar o cache de formulários adaptáveis, consulte Armazenamento em cache de formulários adaptáveis.

Habilite o HTML através do módulo de compactação do servidor Web. Para obter mais informações, consulte Ajuste de desempenho do servidor AEM Forms.

Aumente as chamadas por configuração de solicitação para formulários grandes. Consulte Otimizando o desempenho de formulários grandes e complexos.

Criar páginas de erro personalizadas mostradas pelo manipulador de erros.

Servidor AEM Forms seguro.

• Use o modo de execução nosamplecontent para garantir que não haja conteúdo de amostra e usuários de amostra implantados no servidor de produção. Consulte Executando o AEM no Modo Pronto para Produção.

Mantenha o tamanho do heap em no mínimo 8 GB. Para outras configurações, consulte Ajuste de desempenho do servidor AEM Forms.

Use sessões de usuário do serviço em vez de sessões de administrador para executar tarefas de nível de serviço. Para obter mais informações, consulte Autenticação de serviço.

Armazenando dados de rascunho: se estiver usando o recurso Rascunho de formulários adaptáveis, você deve implementar uma SPI (Interface de Provedor de Serviço) personalizada para armazenar dados de rascunho em um armazenamento mais seguro, como um banco de dados. Para obter mais informações, consulte Amostra para integrar o componente de rascunhos e envios ao banco de dados.

Armazenando dados de envio: se estiver usando o Repositório de Envio do Portal de Formulário, você deve implementar uma SPI personalizada para armazenar dados de envio em um banco de dados. Consulte Amostra para integrar o componente de rascunhos e envios ao banco de dados para obter uma integração de amostra.

Você também pode escrever uma ação de envio personalizada que armazene dados de formulário e anexos em um armazenamento seguro. Consulte Gravando ação enviar personalizada para formulários adaptáveis para obter mais informações.

Comprimento da ID de rascunho: quando você salva um formulário adaptável como rascunho, uma ID de rascunho é gerada para identificar exclusivamente o rascunho. O valor mínimo para o comprimento do campo de ID de rascunho é de 26 caracteres. A Adobe recomenda definir o comprimento da ID de rascunho para 26 ou mais caracteres.

Use o controle de versão facilmente como o Git:

• O isolamento do código do conteúdo reduz significativamente os conflitos do Git durante o gerenciamento de conteúdo e promove um repositório bem organizado.
• As Funções personalizadas são valiosas para projetos com vários colaboradores que trabalham simultaneamente.

Benefícios técnicos:

• Funções personalizadas oferecem modularidade e encapsulamento.
• Os módulos podem ser desenvolvidos, testados e mantidos de forma independente.
• Aumenta a reutilização e a capacidade de manutenção do código.

Processo eficiente de desenvolvimento:

• A modularidade permite que os desenvolvedores se concentrem em funcionalidades específicas.
• Diminui o fardo dos desenvolvedores ao reduzir as complexidades de toda a base de código para um processo de desenvolvimento mais eficiente.