amp-form

<script async custom-element="amp-form" src="https://cdn.ampproject.org/v0/amp-form-0.1.js"></script>

Comportamento

A extensão amp-form permite que você crie formulários (<form>) para enviar campos de entrada em um documento AMP. A extensão amp-form também fornece polyfills para alguns comportamentos ausentes em navegadores.

Antes de criar um <form>, é preciso incluir o script exigido para a extensão <amp-form>. Se você não fizer isso, seu documento será inválido. Se você está usando tags input para finalidades que não sejam o envio dos valores delas (por exemplo, entradas que não estejam dentro de um <form>), não é necessário carregar a extensão amp-form.

Veja um exemplo de formulário básico:

<form method="post"
    action-xhr="https://example.com/subscribe"  
    target="_top">
    <fieldset>
      <label>
        <span>Name:</span>
        <input type="text"
          name="name"
          required>
      </label>
      <br>
      <label>
        <span>Email:</span>
        <input type="email"
          name="email"
          required>
      </label>
      <br>
      <input type="submit"
        value="Subscribe">
    </fieldset>
    <div submit-success>
      <template type="amp-mustache">
        Subscription successful!
      </template>
    </div>
    <div submit-error>
      <template type="amp-mustache">
        Subscription failed!
      </template>
    </div>
  </form>

Atributos

target

Indica onde exibir a resposta do formulário após o envio dele. O valor precisa ser _blank ou _top.

action

Especifica um endpoint do servidor para processar a entrada do formulário. O valor precisa ser um URL https (absoluto ou relativo) e não pode ser um link para uma CDN.

• Para method=GET: use este atributo ou action-xhr.
• Para method=POST: use o atributo action-xhr.

action-xhr

Especifica um endpoint do servidor para processar a entrada do formulário e enviar o formulário via XMLHttpRequest (XHR). Uma solicitação XHR (às vezes chamada de solicitação AJAX) é o local em que o navegador faz a solicitação sem carregar totalmente a página ou ao abrir uma nova página. Os navegadores enviam a solicitação em segundo plano usando a API Fetch, quando disponível, que é substituída pela API XMLHttpRequest no caso dos navegadores mais antigos.

Esse atributo é obrigatório para method=POST e opcional para method=GET.

O valor de action-xhr pode ser o mesmo endpoint de action ou outro e tem os mesmos requisitos de action descritos acima.

Para saber mais sobre como redirecionar o usuário após o envio do formulário, consulte a seção Redirecionamento após um envio abaixo.

Outros atributos de formulário

Todos os outros atributos de formulário são opcionais.

custom-validation-reporting

Este é um atributo opcional que ativa e seleciona uma estratégia personalizada de relatórios de validação. Os valores válidos são: show-first-on-submit, show-all-on-submit ou as-you-go.

Consulte a seção Validações personalizadas para ver mais detalhes.

Entradas e campos

Permitidos:

• Outros elementos relacionados a formulário, incluindo: <textarea>, <select>, <option>, <fieldset>, <label>, <input type=text>, <input type=submit> e assim por diante.
• <input type=password> e <input type=file> dentro de <form method=POST action-xhr>.
• amp-selector.

Não permitidos:

• <input type=button>, <input type=image>.
• A maioria dos atributos relacionados a formulários em entradas, incluindo: form, formaction, formtarget, formmethod e outros.

É possível que algumas dessas regras sejam flexibilizadas no futuro. Se você precisa de algum desses itens, entre em contato e forneça casos de uso.

Para ver detalhes sobre entradas e campos válidos, consulte as regras de amp-form nas especificações do validador de AMP.

Ações

O elemento amp-form expõe as seguintes ações:

Eventos

O amp-form expõe os seguintes eventos:

Esses eventos podem ser usados por meio do atributo on.

Por exemplo, o código a seguir escuta os eventos submit-success e submit-error e mostra lightboxes diferentes dependendo do evento:

<form ...="" on="submit-success:success-lightbox;submit-error:error-lightbox">
</form>

Veja o exemplo completo aqui.

Eventos de entrada

O AMP expõe eventos change e input-debounced em elementos <input> filhos. Isso permite que você use o atributo on para executar uma ação em qualquer elemento quando um valor de entrada for alterado.

Por exemplo, um caso de uso comum é enviar um formulário quando houver alteração da entrada (ao selecionar um botão de opção para responder a uma pesquisa, escolher um idioma em uma entrada select para traduzir uma página etc.).

<form id="myform"
    method="post"
    action-xhr="https://example.com/myform"  
    target="_blank">
    <fieldset>
      <label>
        <input name="answer1"
          value="Value 1"
          type="radio"
          on="change:myform.submit">Value 1
      </label>
      <label>
        <input name="answer1"
          value="Value 2"
          type="radio"
          on="change:myform.submit">Value 2
      </label>
    </fieldset>
  </form>

Veja o exemplo completo aqui.

Acionadores de análise

A extensão amp-form aciona os seguintes eventos, que você pode acompanhar na configuração de amp-analytics:

Você pode configurar sua análise para que envie esses eventos, como no exemplo a seguir:

<amp-analytics>
  <script type="application/json">
    {
      "requests": {
        "event": "https://www.example.com/analytics/event?eid=${eventId}",
        "searchEvent": "https://www.example.com/analytics/search?formId=${formId}&query=${formFields[query]}"
      },
      "triggers": {
        "formSubmit": {
          "on": "amp-form-submit",
          "request": "searchEvent"
        },
        "formSubmitSuccess": {
          "on": "amp-form-submit-success",
          "request": "event",
          "vars": {
            "eventId": "form-submit-success"
          }
        },
        "formSubmitError": {
          "on": "amp-form-submit-error",
          "request": "event",
          "vars": {
            "eventId": "form-submit-error"
          }
        }
      }
    }
  </script>
</amp-analytics>

Os três eventos geram um conjunto de variáveis que correspondem ao formulário específico e aos campos do formulário. Essas variáveis podem ser usadas para análise.

Por exemplo, o formulário a seguir tem um único campo:

<form id="submit_form" action-xhr="/comment" method="POST">
  <input type="text" name="comment">
    <input type="submit" value="Comentar">
    </form>

Quando o evento amp-form-submit, amp-form-submit-success ou amp-form-submit-error é acionado, ele gera as seguintes variáveis com os valores especificados no formulário:

• formId
• formFields[comment]

Renderização de resposta de sucesso/erro

Você pode renderizar respostas de sucesso ou erro no seu formulário usando modelos estendidos, como amp-mustache. Também é possível renderizar respostas de sucesso por meio da vinculação de dados com amp-bind e os seguintes atributos de resposta:

Para renderizar respostas com modelos:

• aplique um atributo de resposta a qualquer filho direto do elemento <form>;
• renderize a resposta no elemento filho incluindo um modelo nela por meio da tag <template></template> ou <script type="text/plain"></script> ou fazendo referência a um modelo com o atributo template="id_of_other_template";
• forneça um objeto JSON válido para as respostas para submit-success e submit-error. As respostas de sucesso e erro precisam ter um cabeçalho Content-Type: application/json.

Exemplo: o formulário exibe mensagens de sucesso, erro e envio

No exemplo a seguir, as respostas são renderizadas em um modelo in-line dentro do formulário.

<form ...>
  <fieldset>
    <input type="text" name="firstName">
      …
    </fieldset>
    <div verify-error="">
      <template type="amp-mustache">
        There is a mistake in the form!
        {{#verifyErrors}}{{message}}{{/verifyErrors}}
    </template>
  </div>
  <div submitting="">
    <template type="amp-mustache">
      Form submitting... Thank you for waiting {{name}}.
    </template>
  </div>
  <div submit-success="">
    <template type="amp-mustache">
      Success! Thanks {{name}} for subscribing! Please make sure to check your email {{email}}
    to confirm! After that we'll start sending you weekly articles on {{#interests}}<b>{{name}}</b> {{/interests}}.
  </template>
</div>
<div submit-error="">
  <template type="amp-mustache">
    Oops! {{name}}, {{message}}.
  </template>
</div>
</form>

O endpoint action-xhr do editor retorna as seguintes respostas JSON:

Se houver sucesso:

{
  "name": "Jane Miller",
  "interests": [{"name": "Basketball"}, {"name": "Swimming"}, {"name": "Reading"}],
  "email": "email@example.com"
}

Se houver erro:

{
  "name": "Jane Miller",
  "message": "The email (email@example.com) you used is already subscribed."
}

Você pode renderizar as respostas em um modelo referenciado definido anteriormente no documento, usando o código do modelo como o valor do atributo template, definido nos elementos com os atributos submit-success e submit-error.

<template id="submit_success_template" type="amp-mustache">
  Success! Thanks {{name}} for subscribing! Please make sure to check your email {{email}}
to confirm! After that we'll start sending you weekly articles on {{#interests}}<b>{{name}}</b> {{/interests}}.
</template>
<template id="submit_error_template" type="amp-mustache">
  Oops! {{name}}, {{message}}.
</template></p>

<form ...="">
  <fieldset>
    …
  </fieldset>
  <div submit-success="" template="submit_success_template"></div>
  <div submit-error="" template="submit_error_template"></div>
</form>

Veja o exemplo completo aqui.

Para renderizar uma resposta de sucesso com a vinculação de dados

• Use o atributo on para vincular o atributo submit-success do formulário a AMP.setState().
• Use a propriedade event para capturar os dados da resposta.
• Adicione o atributo de estado ao elemento desejado para vincular a resposta do formulário.

O exemplo a seguir demonstra uma resposta submit-success do formulário com o amp-bind:

<p [text]="'Thanks, ' + subscribe +'! You have successfully subscribed.'">Subscribe to our newsletter</p>
<form method="post"
      action-xhr="/components/amp-form/submit-form-input-text-xhr"
      target="_ top"
      on="submit-success: AMP.setState({'subscribe': event.response.name})">
  <div>
    <input type="text"
        name="name"
        placeholder="Name..."
        required>
    <input type="email"
      name="email"
      placeholder="Email..."
      required>
  </div>
  <input type="submit" value="Subscribe">
</form>

Quando o formulário for enviado com sucesso, ele retornará uma resposta JSON semelhante a esta:

{
  "name": "Jane Miller",
  "email": "email@example.com"
}

Em seguida, amp-bind atualizará o texto do elemento <p> para que corresponda ao estado subscribe:

...
<p [text]="'Thanks, ' + subscribe +'! You have successfully subscribed.'">Thanks Jane Miller! You have successfully subscribed.</p>
...

Redirecionamento após um envio

Você pode redirecionar os usuários para uma nova página após o envio de um formulário com sucesso. Para isso, basta configurar o cabeçalho de resposta AMP-Redirect-To e especificar um URL de redirecionamento, que precisa ser um URL HTTPS. Caso contrário, a AMP gerará um erro, e o redirecionamento não ocorrerá. Os cabeçalhos de resposta HTTP são configurados por meio do seu servidor.

Atualize o cabeçalho de resposta Access-Control-Expose-Headers, incluindo AMP-Redirect-To na lista de cabeçalhos permitidos. Saiba mais sobre esses cabeçalhos em Segurança do CORS em AMP (link em inglês).

Exemplos de cabeçalhos de resposta:

AMP-Redirect-To: https://example.com/forms/thank-you
Access-Control-Expose-Headers: AMP-Access-Control-Allow-Source-Origin, AMP-Redirect-To

Validações personalizadas

A extensão amp-form permite que você crie sua própria IU de validação personalizada usando o atributo custom-validation-reporting junto com as seguintes estratégias de relatório: show-first-on-submit, show-all-on-submit ou as-you-go.

Para especificar a validação personalizada no seu formulário:

1. Configure o atributo custom-validation-reporting no form como uma das estratégias de relatório de validação.
2. Forneça sua própria IU de validação marcada com atributos especiais. O AMP descobrirá os atributos especiais e os informará no momento certo, dependendo da estratégia de relatório especificada.

Veja um exemplo:

<form method="post"
    action-xhr="https://example.com/subscribe"
    custom-validation-reporting="show-all-on-submit"  
    target="_blank">
    <fieldset>
      <label>
        <span>Name:</span>
        <input type="text"
          name="name"
          id="name5"
          required
          pattern="\w+\s\w+">
        <span visible-when-invalid="valueMissing"
          validation-for="name5"></span>
        <span visible-when-invalid="patternMismatch"
          validation-for="name5">
          Please enter your first and last name separated by a space (e.g. Jane Miller)
        </span>
      </label>
      <br>
      <label>
        <span>Email:</span>
        <input type="email"
          name="email"
          id="email5"
          required>
        <span visible-when-invalid="valueMissing"
          validation-for="email5"></span>
        <span visible-when-invalid="typeMismatch"
          validation-for="email5"></span>
      </label>
      <br>
      <input type="submit"
        value="Subscribe">
    </fieldset>
  </form>

Para ver mais exemplos, consulte examples/forms.amp.html.

Para mensagens de validação, se seu elemento não tiver conteúdo textual, o AMP o preencherá com a mensagem de validação padrão do navegador. No exemplo acima, quando a entrada name5 estiver vazia e a validação for iniciada (ou seja, quando o usuário tiver tentado enviar o formulário), o AMP preencherá <span visible-when-invalid="valueMissing" validation-for="name5"></span> com a mensagem de validação do navegador e mostrará esse span para o usuário.

Estratégias de relatórios

Especifique uma das seguintes opções de relatório para o atributo custom-validation-reporting:

Show First on Submit

A opção de relatório show-first-on-submit simula o comportamento padrão do navegador quando a validação padrão é iniciada. Ela mostra o primeiro erro de validação encontrado e para nele.

Show All on Submit

A opção de relatório show-all-on-submit mostra todos os erros de validação em todas as entradas inválidas quando o formulário é enviado. Isso é útil se você quiser mostrar um resumo de validações.

As You Go

A opção de relatório as-you-go permite que o usuário veja as mensagens de validação enquanto interage com a entrada. Por exemplo, se o usuário digitar um endereço de e-mail inválido, ele verá o erro imediatamente. Depois de corrigir o valor, o erro desaparecerá.

Interact and Submit

A opção de relatório interact-and-submit combina o comportamento de show-all-on-submit e as-you-go. Os campos mostrarão erros imediatamente após as interações. Quando o formulário for enviado, serão exibidos erros em todos os campos inválidos.

Verificação

A validação de HTML5 fornece feedback com base apenas nas informações disponíveis na página, como, por exemplo, se um valor corresponde a determinado padrão. Com a verificação de amp-form, você pode dar ao usuário um feedback que a validação de HTML5 por si só não pode. Por exemplo, um formulário pode usar a verificação para confirmar se um endereço de e-mail já foi registrado. Outro caso de uso é verificar se um campo de cidade corresponde a um campo de CEP.

Veja um exemplo:

<h4>Verification example</h4>
<form method="post" action-xhr="/form/verify-json/post" verify-xhr="/form/verify-json/post"{% if not format=='email'%}   target="_blank"{% endif %}>
  <fieldset>
    <label>
      <span>Email</span>
      <input type="text" name="email" required="">
      </label>
      <label>
        <span>Zip Code</span>
        <input type="tel" name="zip" required="" pattern="[0-9]{5}(-[0-9]{4})?">
        </label>
        <label>
          <span>City</span>
          <input type="text" name="city" required="">
          </label>
          <label>
            <span>Document</span>
            <input type="file" name="document" no-verify="">
            </label>
            <div class="spinner"></div>
            <input type="submit" value="Enviar">
            </fieldset>
            <div submit-success="">
              <template type="amp-mustache">
                <p>Congratulations! You are registered with {{email}}</p>
              </template>
            </div>
            <div submit-error="">
              <template type="amp-mustache">
                {{#verifyErrors}}
              <p>{{message}}</p>
              {{/verifyErrors}}
            {{^verifyErrors}}
          <p>Something went wrong. Try again later?</p>
          {{/verifyErrors}}
      </template>
    </div>
  </form>

O formulário envia um campo __amp_form_verify junto com os dados do formulário como uma dica para o servidor de que a solicitação é de verificação, e não um envio formal. Isso é útil para que o servidor não armazene a solicitação de verificação se o mesmo endpoint for usado para verificação e envio.

Veja um exemplo de resposta de erro para verificação:

  {
    "verifyErrors": [
      {"name": "email", "message": "That email is already taken."},
      {"name": "zip", "message": "The city and zip do not match."}
    ]
  }

Para remover um campo da solicitação verify-xhr, adicione o atributo no-verify ao elemento de entrada.

Para ver mais exemplos, consulte examples/forms.amp.html.

Substituições de variáveis

A extensão amp-form permite substituições de variáveis de plataforma (link em inglês) para entradas ocultas e que tenham o atributo data-amp-replace. Em cada envio de formulário, o amp-form encontra todas as input[type=hidden][data-amp-replace] dentro do formulário, aplica substituições de variáveis ao atributo value e o troca pelo resultado da substituição.

Você precisa fornecer as variáveis que está usando para cada substituição em cada entrada, especificando uma string separada por espaços das variáveis usadas em data-amp-replace (veja o exemplo abaixo). O AMP não substitui as variáveis que não são explicitamente especificadas.

Veja um exemplo da aparência das entradas antes e depois das substituições (é preciso usar a sintaxe da plataforma para substituição de variáveis, e não para análise):

<!-- Initial Load -->
<form ...>
  <input name="canonicalUrl" type="hidden"
        value="The canonical URL is: CANONICAL_URL - RANDOM - CANONICAL_HOSTNAME"
        data-amp-replace="CANONICAL_URL RANDOM">
  <input name="clientId" type="hidden"
        value="CLIENT_ID(myid)"
        data-amp-replace="CLIENT_ID">
  ...
</form>

Quando o usuário tentar enviar o formulário, o AMP tentará resolver as variáveis e atualizar o atributo value de todos os campos com as substituições apropriadas. No caso de envios de XHR, é provável que todas as variáveis sejam substituídas e resolvidas. No entanto, em envios GET que não sejam XHR, os valores que exigem resolução assíncrona podem não estar disponíveis por não terem sido resolvidos anteriormente. CLIENT_ID, por exemplo, não seria resolvido se não tivesse sido resolvido e armazenado em cache anteriormente.

<!-- User submits the form, variables values are resolved into fields' value -->
<form ...>
  <input name="canonicalUrl" type="hidden"
        value="The canonical URL is: https://example.com/hello - 0.242513759125 - CANONICAL_HOSTNAME"
        data-amp-replace="CANONICAL_URL RANDOM">
  <input name="clientId" type="hidden"
        value="amp:asqar893yfaiufhbas9g879ab9cha0cja0sga87scgas9ocnas0ch"
        data-amp-replace="CLIENT_ID">
    ...
</form>

Observe como o CANONICAL_HOSTNAME acima não foi substituído porque não estava na lista de permissões do atributo data-amp-replace no primeiro campo.

As substituições ocorrerão em todos os envios subsequentes. Leia mais sobre substituições de variáveis em AMP.

Polyfills

A extensão amp-form fornece polyfills para comportamentos e funcionalidades ausentes em alguns navegadores ou que serão implementados na próxima versão do CSS.

Bloqueio de envio inválido e balão de mensagem de validação

Os navegadores que atualmente usam mecanismos baseados em webkit (desde agosto de 2016) não são compatíveis com envios de formulários inválidos. Isso inclui o Safari em todas as plataformas e todos os navegadores para iOS. A extensão amp-form fornece polyfills para esse comportamento a fim de bloquear envios inválidos e mostrar balões de mensagens de validação em entradas inválidas.

Pseudoclasses de interação com o usuário

As pseudoclasses :user-invalid e :user-valid fazem parte da futura especificação do CSS Selectors 4 e foram lançadas para permitir melhores ganchos para estilizar campos inválidos/válidos com base em alguns critérios.

Uma das principais diferenças entre :invalid e :user-invalid é quando elas são aplicadas ao elemento. A classe :user-invalid é aplicada após uma interação significativa do usuário com o campo (por exemplo, quando o usuário digita em um campo ou desfoca-o).

A extensão amp-form fornece classes para acrescentar polyfills para essas pseudoclasses. A extensão amp-form também propaga as classes para os elementos fieldset ancestrais e form.

Validação de <textarea>

A correspondência de expressão regular é um recurso comum de validação compatível nativamente com a maioria dos elementos de entrada, exceto <textarea>. Fornecemos um polyfill para essa funcionalidade e aceitamos o atributo pattern em elementos <textarea>.

O formulário AMP fornece um atributo autoexpand para elementos <textarea>. Isso permite que a área de texto se expanda e recolha para acomodar as linhas de entrada do usuário, até o tamanho máximo do campo. Se o usuário redimensionar manualmente o campo, o comportamento de expansão automática será removido.

<textarea autoexpand></textarea>

Estilo

Ganchos de classes e CSS

A extensão amp-form fornece ganchos de CSS e de classes para os editores definirem o estilo de formulários e entradas.

As seguintes classes podem ser usadas para indicar o estado do envio do formulário:

• .amp-form-initial
• .amp-form-verify
• .amp-form-verify-error
• .amp-form-submitting
• .amp-form-submit-success
• .amp-form-submit-error

As seguintes classes são um polyfill para as pseudoclasses de interação do usuário:

• .user-valid
• .user-invalid

Os editores podem usar essas classes para definir o estilo de entradas e conjuntos de campos para que respondam às ações do usuário (por exemplo, destacar uma entrada inválida com uma borda vermelha após o usuário desfocá-la).

Veja aqui um exemplo completo de como usar essas classes.

Considerações sobre segurança

Proteção contra XSRF

Além de seguir os detalhes das especificações CORP AMP, preste atenção especial à seção Processar solicitações de alteração de estado#processing-state-changing-requests) (link em inglês) para se proteger contra ataques XSRF, em que um invasor pode executar comandos não autorizados usando a sessão atual do usuário sem o conhecimento dele.

Em geral, lembre-se dos seguintes pontos ao aceitar informações do usuário:

• Use somente POST para solicitações de alteração de estado.
• Use GET que não seja XHR apenas para fins de navegação (por exemplo, para pesquisa).
  • As solicitações GET que não sejam XHR não receberão origem/cabeçalhos precisos, e os back-ends não poderão se proteger contra XSRF com o mecanismo acima.
  • Em geral, use solicitações GET XHR/não XHR apenas para navegação ou recuperação de informações.
• Solicitações POST que não sejam XHR não são permitidas em documentos AMP. Isso ocorre devido a inconsistências na configuração do cabeçalho Origin dessas solicitações nos navegadores. Além disso, a compatibilidade traria complicações para a proteção contra XSRF. Isso pode ser reconsiderado e introduzido posteriormente. Registre um problema se achar necessário.