Escrevendo ação de envio personalizado para formulários adaptáveis

Formulários adaptáveis exigem ações de envio para processar dados especificados pelo usuário. Uma ação Enviar determina a tarefa executada nos dados que você envia usando um formulário adaptável. A Adobe Experience Manager (AEM) inclui ações de Enviar OOTB que demonstram tarefas personalizadas que você pode executar usando os dados enviados pelo usuário. Por exemplo, você pode realizar tarefas, como enviar e-mail ou armazenar os dados.

Fluxo de trabalho para uma ação Enviar

O fluxograma descreve o fluxo de trabalho de uma ação Enviar que é acionada quando você clica no botão Enviar em um formulário adaptável. Os arquivos no componente Anexo de arquivo são carregados no servidor e os dados do formulário são atualizados com os URLs dos arquivos carregados. No cliente, os dados são armazenados no formato JSON. O cliente envia uma solicitação Ajax para um servlet interno que massaja os dados especificados e os retorna no formato XML. O cliente cola esses dados com campos de ação. Ele envia os dados para o servlet final (servlet Guide Submit) por meio de uma ação de envio de formulário. Em seguida, o servlet encaminha o controle para a ação Enviar. A ação Enviar pode encaminhar a solicitação para um recurso de sling diferente ou redirecionar o navegador para outro URL.

Fluxograma que descreve o fluxo de trabalho para a ação Enviar

Formato de dados XML

Os dados XML são enviados para o servlet usando o parâmetro de solicitação jcr:data. As ações de envio podem acessar o parâmetro para processar os dados. O código a seguir descreve o formato dos dados XML. Os campos vinculados ao modelo de formulário são exibidos na seção afBoundData. Campos não vinculados são exibidos na seção afUnoundData. Para obter mais informações sobre o formato do arquivo data.xml, consulte Introdução ao pré-preenchimento de campos de formulário adaptáveis.

<?xml ?>
<afData>
<afUnboundData>
<data>
<field1>value</field2>
<repeatablePanel>
    <field2>value</field2>
</repeatablePanel>
<repeatablePanel>
    <field2>value</field2>
</repeatablePanel>
</data>
</afUnboundData>
<afBoundData>
<!-- xml corresponding to the Form Model /XML Schema -->
</afBoundData>
</afData>

Campos de ação

Uma ação Enviar pode adicionar campos de entrada ocultos (usando a tag HTML input) ao formulário renderizado HTML. Esses campos ocultos podem conter valores necessários durante o processamento do envio do formulário. Ao enviar o formulário, esses valores de campo são lançados de volta como parâmetros de solicitação que a ação Enviar pode usar durante a manipulação de envio. Os campos de entrada são chamados de campos de ação.

Por exemplo, uma ação Enviar que também captura o tempo gasto para preencher um formulário pode adicionar os campos de entrada ocultos startTime e endTime.

Um script pode fornecer os valores dos campos startTime e endTime quando o formulário é renderizado e antes do envio do formulário, respectivamente. O script de ação Enviar post.jsp pode acessar esses campos usando parâmetros de solicitação e calcular o tempo total necessário para preencher o formulário.

Anexos de arquivo

As ações de envio também podem usar os anexos de arquivo carregados usando o componente Anexo de arquivo. Os scripts de ação Submit podem acessar esses arquivos usando a API sling RequestParameter. O método isFormField da API ajuda a identificar se o parâmetro de solicitação é um arquivo ou um campo de formulário. É possível repetir os parâmetros de Solicitação em uma ação Enviar para identificar os parâmetros de Anexo de arquivo.

O código de amostra a seguir identifica os anexos de arquivo na solicitação. Em seguida, ele lê os dados no arquivo usando a Get API. Finalmente, cria um objeto de Documento usando os dados e o anexa a uma lista.

RequestParameterMap requestParameterMap = slingRequest.getRequestParameterMap();
for (Map.Entry<String, RequestParameter[]> param : requestParameterMap.entrySet()) {
    RequestParameter rpm = param.getValue()[0];
    if(!rpm.isFormField()) {
        fileAttachments.add(new Document(rpm.get()));
    }
}

Caminho de encaminhamento e URL de redirecionamento

Depois de executar a ação necessária, o servlet Enviar encaminha a solicitação para o caminho de encaminhamento. Uma ação usa a API setForwardPath para definir o caminho de encaminhamento no servlet Guide Submit.

Se a ação não fornecer um caminho de encaminhamento, o servlet Enviar redirecionará o navegador usando o URL de redirecionamento. O autor configura o URL de redirecionamento usando a configuração da Página de agradecimento na caixa de diálogo Edição de formulário adaptável. Você também pode configurar o URL de redirecionamento por meio da ação Enviar ou da API setRedirectUrl no servlet Enviar guia. Você também pode configurar os parâmetros de Solicitação enviados para o URL de redirecionamento usando a API setRedirectParameters no servlet Guide Submit.

OBSERVAÇÃO

Um autor fornece o URL de redirecionamento (usando a Configuração da página de agradecimento). As ações Enviar OTB utilizam o URL de redirecionamento para redirecionar o navegador do recurso ao qual o caminho de encaminhamento faz referência.

Você pode gravar uma ação de Enviar personalizada que encaminha uma solicitação para um recurso ou servlet. O Adobe recomenda que o script que executa a manipulação de recursos para o caminho de encaminhamento redirecione a solicitação para o URL de redirecionamento quando o processamento for concluído.

Enviar ação

Uma ação Enviar é uma sling:Folder que inclui o seguinte:

  • addfields.jsp: Esse script fornece os campos de ação adicionados ao arquivo HTML durante a execução. Use esse script para adicionar os parâmetros de entrada ocultos necessários durante o envio no script post.POST.jsp.

  • dialog.xml: Esse script é semelhante à caixa de diálogo Componente do CQ. Ele fornece informações de configuração que o autor personaliza. Os campos são exibidos na guia Enviar ações na caixa de diálogo Edição de formulário adaptável quando você seleciona a ação Enviar.

  • post.POST.jsp: O servlet Enviar chama esse script com os dados que você envia e os dados adicionais nas seções anteriores. Qualquer menção à execução de uma ação nesta página implica a execução do script post.POST.jsp. Para registrar a ação Enviar com os formulários adaptáveis a serem exibidos na caixa de diálogo Edição de formulário adaptável, adicione essas propriedades à sling:Folder:

    • ​guideComponentType do tipo String e valor fd/af/components/guidesubmittype
    • ​guideDataModelof tipo String que especifica o tipo de formulário adaptável ao qual a ação Enviar é aplicável. Há suporte para xfais adaptativos baseados em XFA e ​xsdis são suportados para formulários adaptativos baseados em XSD. Há suporte básico para formulários adaptáveis que não usam XDP ou XSD. Para exibir a ação em vários tipos de formulários adaptáveis, adicione as strings correspondentes. Separe cada string por vírgula. Por exemplo, para tornar uma ação visível em formulários adaptativos baseados em XFA e XSD, especifique os valores xfa e xsd respectivamente.
    • jcr: descrição do tipo String. O valor dessa propriedade é exibido na lista de ação Enviar na guia Enviar ações da caixa de diálogo Edição de formulário adaptável. As ações OOTB estão presentes no repositório CRX no local /libs/fd/af/components/guidesubmittype.

Criação de uma ação Enviar personalizada

Execute as seguintes etapas para criar uma ação Enviar personalizada que salve os dados no repositório CRX e, em seguida, envie um email para você. O formulário adaptável contém a ação Enviar Conteúdo do Repositório de Ação OOTB (obsoleto) que salva os dados no repositório CRX. Além disso, o CQ fornece uma API Mail que pode ser usada para enviar emails. Antes de usar a API de email, [configure] (https://docs.adobe.com/docs/en/cq/current/administering/notification.html?#Configuring o serviço de email) o serviço Day CQ Mail pelo console do sistema. Você pode reutilizar a ação Armazenar conteúdo (obsoleto) para armazenar os dados no repositório. A ação Armazenar conteúdo (obsoleto) está disponível no local /libs/fd/af/components/guidesubmittype/store no repositório CRX.

  1. Faça logon no CRXDE Lite no URL https://<servidor>:<porta>/crx/de/index.jsp. Crie um nó com a propriedade sling:Folder e name store_and_mail na pasta /apps/custom_submit_action. Crie a pasta custom_submit_action se ela já não existir.

    Captura de tela representando a criação de um nó com a propriedade sling:Folder

  2. Forneça os campos de configuração obrigatórios.

    Adicione a configuração que a ação de Loja requer. Copie o nó cq:dialog da ação Loja de /libs/fd/af/components/guidesubmittype/store para a pasta de ação em /apps/custom_submit_action/store_and_email.

    Captura de tela mostrando a cópia do nó de diálogo para a pasta de ação

  3. Forneça campos de configuração para solicitar ao autor a configuração do email.

    O formulário adaptável também fornece uma ação de Email que envia emails aos usuários. Personalize esta ação com base nas suas necessidades. Navegue até /libs/fd/af/components/guidesubmittype/email/dialog. Copie os nós no nó cq:dialog para cq:node da sua ação Enviar (/apps/custom_submit_action/store_and_email/dialog?lang=pt-BR).

    Personalização da ação de email

  4. Disponibilize a ação na caixa de diálogo Adaptive Form Edit (Edição de formulário adaptável).

    Adicione as seguintes propriedades no nó store_and_email:

    • ​guideComponentType do tipo ​Stringand value fd/af/components/guidesubmittype
    • ​guideDataModelof type ​Stringand value xfa, xsd, basic
    • jcr: descrição do tipo ​String e valor Store e ação de email
  5. Abra qualquer formulário adaptável. Clique no botão Editar ao lado de Start para abrir a caixa de diálogo Editar do container de formulário adaptável. A nova ação é exibida na guia Enviar ações. A seleção de Loja e Ação de E-mail exibe a configuração adicionada no nó de diálogo.

    Caixa de diálogo Enviar configuração de ação

  6. Use a ação para concluir uma tarefa.

    Adicione o script post.POST.jsp à sua ação. (/apps/custom_submit_action/store_and_mail/?lang=pt-BR).

    Execute a ação da Loja OOTB (script post.POST.jsp). Use a API [FormsHelper.runAction] (https://docs.adobe.com/docs/en/cq/current/javadoc/com/day/cq/wcm/foundation/forms/FormsHelper.html#runAction(java.lang.String,%20java.lang.String,%20org.apache.sling.api.resource.Resource,%20org.apache.sling.api.SlingHttpServletRequest,%20org.apache.sling.api.SlingHttpServletResponse?lang=pt-BR) que o CQ fornece em código para executar a ação Loja. Adicione o seguinte código no arquivo JSP:

    FormsHelper.runAction("/libs/fd/af/components/guidesubmittype/store", "post", resource, slingRequest, slingResponse);

    Para enviar o e-mail, o código lê o endereço de e-mail do recipient na configuração. Para obter o valor de configuração no script da ação, leia as propriedades do recurso atual usando o código a seguir. Da mesma forma, você pode ler os outros arquivos de configuração.

    ValueMap properties = ResourceUtil.getValueMap(resource);

    String mailTo = properties.get("mailTo");

    Por fim, use a CQ Mail API para enviar o email. Use a classe SimpleEmail para criar o Objeto de e-mail, conforme mostrado abaixo:

    OBSERVAÇÃO

    Verifique se o arquivo JSP tem o nome post.POST.jsp.

    <%@include file="/libs/fd/af/components/guidesglobal.jsp" %>
    <%@page import="com.day.cq.wcm.foundation.forms.FormsHelper,
           org.apache.sling.api.resource.ResourceUtil,
           org.apache.sling.api.resource.ValueMap,
                    com.day.cq.mailer.MessageGatewayService,
      com.day.cq.mailer.MessageGateway,
      org.apache.commons.mail.Email,
                    org.apache.commons.mail.SimpleEmail" %>
    <%@taglib prefix="sling" 
                    uri="https://sling.apache.org/taglibs/sling/1.0" %>
    <%@taglib prefix="cq" 
                    uri="https://www.day.com/taglibs/cq/1.0" 
    %>
    <cq:defineObjects/>
    <sling:defineObjects/>
    <%
            String storeContent = 
                        "/libs/fd/af/components/guidesubmittype/store";
            FormsHelper.runAction(storeContent, "post", resource, 
                                    slingRequest, slingResponse);
     ValueMap props = ResourceUtil.getValueMap(resource);
     Email email = new SimpleEmail();
     String[] mailTo = props.get("mailto", new String[0]);
     email.setFrom((String)props.get("from"));
            for (String toAddr : mailTo) {
                email.addTo(toAddr);
       }
     email.setMsg((String)props.get("template"));
     email.setSubject((String)props.get("subject"));
     MessageGatewayService messageGatewayService = 
                        sling.getService(MessageGatewayService.class);
     MessageGateway messageGateway = 
                    messageGatewayService.getGateway(SimpleEmail.class);
     messageGateway.send(email);
    %>
    

    Selecione a ação no formulário adaptável. A ação envia um email e armazena os dados.

Nesta página