amp-form

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

Comportement

L'extension amp-form vous permet de créer des formulaires (<form>) afin d'envoyer des champs de saisie dans un document AMP. L'extension amp-form fournit également des polyfills pour certains comportements indisponibles dans les navigateurs.

Avant de créer une balise <form>, vous devez inclure le script requis pour l'extension <amp-form>, sans quoi votre document ne sera pas valide. Si vous utilisez des balises input à d'autres fins que l'envoi de leurs valeurs (des entrées situées à l'extérieur d'une balise <form>, par exemple), il n'est pas nécessaire de charger l'extension amp-form.

Voici un exemple de formulaire de base :

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

Attributs

target

Indique où afficher la réponse du formulaire après avoir envoyé ce dernier. La valeur doit être _blank ou _top.

action

Indique un point de terminaison serveur affecté à la gestion de la saisie du formulaire. La valeur doit être une URL https (absolue ou relative), et non un lien vers un CDN.

• Pour method=GET : utilisez cet attribut ou action-xhr.
• Pour method=POST : utilisez l'attribut action-xhr.

action-xhr

Indique un point de terminaison serveur affecté à la gestion de la saisie du formulaire et à l'envoi du formulaire via XMLHttpRequest (XHR). On parle de requête XHR (parfois appelée requête AJAX) lorsque le navigateur effectue une requête sans procéder à un chargement complet de la page, ni ouvrir une nouvelle page. Les navigateurs envoient la requête en arrière-plan à l'aide de l'API Fetch lorsqu'elle est disponible et de l'API XMLHttpRequest pour les navigateurs plus anciens.

Cet attribut est obligatoire pour method=POST et facultatif pour method=GET.

La valeur de l'attribut action-xhr peut être le même point de terminaison que l'attribut action ou un point de terminaison différent. Les exigences sont identiques à celles décrites ci-dessus pour action.

Pour en savoir plus sur la redirection de l'utilisateur après l'envoi du formulaire, consultez la section Redirection après un envoi ci-dessous.

Autres attributs de formulaire

Tous les autres attributs de formulaire sont facultatifs.

custom-validation-reporting

Cet attribut facultatif permet d'activer et de sélectionner une stratégie de signalement de validation personnalisée. Les valeurs valides sont show-first-on-submit, show-all-on-submit et as-you-go.

Pour en savoir plus, consultez la section Validation personnalisée.

Entrées et champs

Éléments autorisés :

• Autres éléments liés à un formulaire, y compris <textarea>, <select>, <option>, <fieldset>, <label>, <input type=text>, <input type=submit>, etc.
• <input type=password> et <input type=file> à l'intérieur de <form method=POST action-xhr>.
• amp-selector

Éléments non autorisés :

• <input type=button>, <input type=image>
• La plupart des attributs liés à un formulaire sur des entrées, y compris form, formaction, formtarget, formmethod, etc.

Il se peut que nous nous penchions à nouveau sur l'assouplissement de certaines de ces règles à l'avenir. Si vous en avez besoin, merci de nous en informer et de nous fournir des cas d'utilisation.

Pour plus d'informations sur les entrées et les champs valides, consultez les règles relatives à amp-form dans les spécifications du validateur AMP.

Actions

L'élément amp-form expose les actions suivantes :

Événements

L'élément amp-form expose les événements suivants :

Ces événements peuvent être utilisés au moyen de l'attribut on.

Par exemple, le code suivant écoute les événements submit-success et submit-error, et affiche des modes Lightbox différents en fonction de l'événement :

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

Pour afficher l'intégralité du code, cliquez ici.

Événements de saisie

AMP expose les événements change et input-debounced sur les éléments <input> enfants. Cela vous permet d'utiliser l'attribut on pour exécuter une action sur n'importe quel élément en cas de changement d'une valeur d'entrée.

Par exemple, il est courant d'envoyer un formulaire lors de la modification d'une entrée : sélection d'une case d'option pour répondre à un sondage, choix d'une langue dans une entrée select pour traduire une page, 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>

Pour afficher l'intégralité du code, cliquez ici.

Déclencheurs d'analyse

L'extension amp-form déclenche les événements suivants dont vous pouvez effectuer le suivi dans votre configuration amp-analytics :

Vous pouvez configurer vos solutions d'analyse de manière à envoyer ces événements comme dans l'exemple suivant :

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

Les trois événements génèrent un ensemble de variables qui correspondent au formulaire spécifique et aux champs qu'il contient. Ces variables peuvent être utilisées dans le cadre de l'analyse.

Par exemple, le formulaire suivant comprend un seul champ :

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

Lorsque l'événement amp-form-submit, amp-form-submit-success ou amp-form-submit-error est déclenché, il génère les variables suivantes contenant les valeurs spécifiées dans le formulaire :

• formId
• formFields[comment]

Affichage des réponses de réussite ou d'erreur

Vous pouvez afficher les réponses de réussite ou d'erreur dans votre formulaire en utilisant des modèles étendus, comme amp-moustache. Pour afficher des réponses de réussite, vous pouvez utiliser la liaison de données avec amp-bind et les attributs de réponse suivants :

Pour afficher des réponses avec la création de modèles, procédez comme suit :

• Appliquez un attribut de réponse à tout élément enfant direct de l'élément <form>.
• Affichez la réponse dans l'élément enfant en y incluant un modèle à l'aide de la balise <template></template> ou <script type="text/plain"></script>, ou en référençant un modèle avec un attribut template="id_of_other_template".
• Indiquez un objet JSON valide pour les réponses à submit-success et submit-error. Les réponses de réussite et d'erreur doivent comporter un en-tête Content-Type: application/json.

Exemple : Le formulaire affiche des messages de réussite, d'erreur et d'envoi en cours

Dans l'exemple suivant, les réponses sont affichées dans un modèle intégré au sein du formulaire.

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

Le point de terminaison action-xhr de l'éditeur renvoie les réponses JSON suivantes :

En cas de réussite :

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

En cas d'erreur :

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

Vous pouvez afficher les réponses dans un modèle référencé défini précédemment dans le document, en utilisant l'identifiant du modèle comme valeur de l'attribut template, lequel est défini sur les éléments avec les attributs submit-success et submit-error.

<template type="amp-mustache" id="submit_success_template">
  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 type="amp-mustache" id="submit_error_template">
  Oops! {{name}}, {{message}}.
</template>

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

Pour afficher l'intégralité du code, cliquez ici.

Afficher une réponse positive avec la liaison de données

• Utilisez l'attribut on pour lier l'attribut submit-success à AMP.setState().
• Utilisez la propriété event pour capturer les données de réponse.
• Ajoutez l'attribut d'état à l'élément souhaité pour lier la réponse de formulaire.

L'exemple suivant illustre une réponse submit-success de formulaire avec 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>

Une fois le formulaire envoyé, il renvoie une réponse JSON semblable à celle-ci :

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

amp-bind met ensuite à jour le texte de l'élément <p> pour qu'il corresponde à l'état subscribe :

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

Redirection après un envoi

Vous pouvez rediriger les utilisateurs vers une nouvelle page après l'envoi réussi d'un formulaire. Pour ce faire, définissez l'en-tête de réponse AMP-Redirect-To et indiquez une URL de redirection. L'URL de redirection doit être au format HTTPS, sans quoi une erreur sera renvoyée par AMP et la redirection n'aura pas lieu. La configuration des en-têtes de réponse HTTP s'effectue via votre serveur.

Veillez à mettre à jour l'en-tête de réponse Access-Control-Expose-Headers de manière à inclure AMP-Redirect-To dans la liste des en-têtes autorisés. Pour en savoir plus sur ces en-têtes, consultez la section Sécurité CORS dans AMP.

Exemples d'en-têtes de réponse :

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

Validations personnalisées

L'extension amp-form vous permet de créer votre propre interface de validation personnalisée en utilisant l'attribut custom-validation-reporting avec l'une des stratégies de signalement suivantes : show-first-on-submit, show-all-on-submit ou as-you-go.

Pour spécifier une validation personnalisée sur votre formulaire, procédez comme suit :

1. Définissez l'attribut custom-validation-reporting dans votre formulaire sur l'une des stratégies de signalement de validation.
2. Fournissez votre propre interface de validation, balisée avec des attributs spéciaux. AMP détecte les attributs spéciaux et les signale au moment opportun, en fonction de la stratégie que vous avez spécifiée.

Exemple :

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

Pour consulter d'autres exemples, reportez-vous au fichier examples/forms.amp.html.

Dans le cas des messages de validation, si votre élément est dépourvu de contenu textuel, AMP y indique le message de validation par défaut du navigateur. Dans l'exemple ci-dessus, lorsque l'entrée name5 est vide et que la validation est lancée (en d'autres termes, l'utilisateur a essayé d'envoyer le formulaire), AMP indique <span visible-when-invalid="valueMissing" validation-for="name5"></span> avec le message de validation du navigateur et présente cet élément span à l'utilisateur.

Stratégies de signalement

Indiquez l'une des options de signalement suivantes pour l'attribut de custom-validation-reporting :

Show First on Submit (Afficher la première lors de l'envoi)

L'option de signalement show-first-on-submit imite le comportement par défaut du navigateur lors du lancement de la validation par défaut. Elle indique la première erreur de validation détectée et s'arrête là.

Show All on Submit (Tout afficher lors de l'envoi)

L'option de signalement show-all-on-submit affiche toutes les erreurs de validation sur l'ensemble des entrées non valides lors de l'envoi du formulaire. Cela s'avère utile si vous souhaitez afficher un récapitulatif des validations.

As You Go (Au fur et à mesure)

L'option de signalement as-you-go permet à l'utilisateur d'afficher les messages de validation à mesure qu'il interagit avec l'entrée. Par exemple, si l'utilisateur saisit une adresse e-mail incorrecte, l'erreur est affichée immédiatement. Une fois la valeur corrigée, l'erreur disparaît.

Interact and Submit (Interagir et envoyer)

L'option de signalement interact-and-submit est la combinaison des options show-all-on-submit et as-you-go. Les erreurs sont immédiatement affichées dans les différents champs après les interactions de l'utilisateur. Lors de l'envoi du formulaire, les erreurs sont également affichées dans tous les champs non valides.

Validation

Les commentaires fournis par la validation HTML5 reposent uniquement sur les informations disponibles sur la page (le fait de savoir si une valeur correspond à un certain schéma, par exemple). La validation amp-form vous permet de transmettre à l'utilisateur des informations que la validation HTML5 seule n'est pas en mesure de lui fournir. Par exemple, la validation peut être utilisée dans un formulaire pour vérifier si une adresse e-mail a déjà été enregistrée. Elle peut également servir à valider la correspondance entre les champs de saisie de la ville et du code postal.

Exemple :

<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>E-mail</span>
      <input type="text" name="email" required="">
      </label>
      <label>
        <span>Code postal</span>
        <input type="tel" name="zip" required="" pattern="[0-9]{5}(-[0-9]{4})?">
        </label>
        <label>
          <span>Ville</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="Envoyer">
            </fieldset>
            <div submit-success="">
              <template type="amp-mustache">
                <p>Félicitations ! Vous êtes inscrit avec l'adresse {{email}}</p>
              </template>
            </div>
            <div submit-error="">
              <template type="amp-mustache">
                {{#verifyErrors}}
              <p>{{message}}</p>
              {{/verifyErrors}}
            {{^verifyErrors}}
          <p>Il y a eu un problème. Réessayer plus tard ?</p>
          {{/verifyErrors}}
      </template>
    </div>
  </form>

Le formulaire envoie un champ __amp_form_verify dans le cadre des données de formulaire pour informer le serveur qu'il s'agit d'une requête de validation et non d'un envoi formel. Il s'agit d'une information utile, en ce sens qu'elle indique au serveur de ne pas stocker la requête de validation si le même point de terminaison est utilisé à la fois pour la validation et pour les envois formels.

Voici un aperçu d'une réponse d'erreur pour la validation :

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

Pour supprimer un champ de la requête verify-xhr, ajoutez l'attribut no-verify à l'élément d'entrée.

Pour consulter d'autres exemples, reportez-vous au fichier examples/forms.amp.html.

Substitutions de variables

L'extension amp-form autorise les substitutions de variables de plate-forme pour les entrées qui sont masquées et qui comportent l'attribut data-amp-replace. À chaque envoi de formulaire, amp-form recherche tous les attributs input[type=hidden][data-amp-replace] dans le formulaire, applique des substitutions de variables à son attribut value, puis le remplace par le résultat de la substitution.

Vous devez fournir les variables que vous utilisez pour chaque substitution sur chaque entrée en spécifiant une chaîne des variables utilisées dans data-amp-replace (voir l'exemple ci-dessous). Les variables de cette chaîne doivent être séparées par des espaces. AMP ne remplace pas les variables qui ne sont pas spécifiées explicitement.

L'exemple ci-dessous montre les entrées avant et après les substitutions (notez que vous devez utiliser la syntaxe des substitutions de variables de la plate-forme et non celle de la solution d'analyse) :

<!-- 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>

Une fois que l'utilisateur tente d'envoyer le formulaire, AMP essaie de résoudre les variables et de mettre à jour l'attribut value de tous les champs avec les substitutions appropriées. Dans le cas des envois XHR, il est probable que toutes les variables soient remplacées et résolues. Cependant, dans les envois GET non XHR, il se peut que les valeurs qui nécessitent une résolution asynchrone ne soient pas disponibles, car elles n'ont pas été résolues auparavant. CLIENT_ID, par exemple, n'est pas résolu s'il n'a pas été résolu et mis en cache précédemment.

<!-- 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>

Notez que l'élément CANONICAL_HOSTNAME ci-dessus n'a pas été remplacé, car il ne figurait pas dans la liste blanche jusqu'à l'attribut data-amp-replace dans le premier champ.

Les remplacements seront effectués lors de chaque envoi ultérieur. En savoir plus sur les substitutions de variables dans AMP

Polyfills

L'extension amp-form fournit des polyfills pour les comportements et les fonctionnalités qui sont indisponibles dans certains navigateurs ou qui seront mis en œuvre dans la prochaine version de CSS.

Info-bulle de message de validation et de blocage d'envois non valides

Depuis août 2016, les navigateurs qui utilisent des moteurs basés sur Webkit n'acceptent plus les envois de formulaire non valides. Il s'agit par exemple de Safari sur toutes les plates-formes et de tous les navigateurs iOS. L'extension amp-form émule ce comportement pour bloquer tout envoi non valide et affiche des info-bulles de messages de validation sur les entrées non valides.

Pseudo-classes d'interaction avec l'utilisateur

Les pseudo-classes :user-invalid et :user-valid font partie de la future spécification CSS Selectors 4. Elles autorisent de meilleurs hooks pour appliquer un style aux champs valides/non valides sur la base de quelques critères.

L'une des différences majeures entre :invalid et :user-invalid se situe au niveau de leur application à l'élément. La classe :user-invalid est appliquée après que l'utilisateur a interagi de manière significative avec le champ (par exemple, l'utilisateur saisit une valeur dans un champ ou floute le champ).

L'extension amp-form fournit des classes pour émuler ces pseudo-classes. Elle `propage également ces éléments aux ancêtresfieldsetelementsetform`.

Validation des éléments <textarea>

La correspondance d'expression régulière est une fonctionnalité de validation courante, compatible en mode natif avec la plupart des éléments d'entrée, à l'exception de <textarea>. Cette fonctionnalité est émulée et l'attribut pattern est accepté sur les éléments <textarea>.

AMP Form fournit un attribut autoexpand pour les éléments <textarea>. La zone de texte peut ainsi être redimensionnée pour s'adapter aux lignes de saisie de l'utilisateur, avec comme limite la taille maximale du champ. Si l'utilisateur redimensionne manuellement le champ, le comportement de développement automatique est supprimé.

<textarea autoexpand></textarea>

Application d'un style

Classes et hooks CSS

L'extension amp-form fournit aux éditeurs des classes et des hooks CSS pour leur permettre d'appliquer un style à leurs formulaires et à leurs entrées.

Les classes suivantes peuvent être utilisées pour indiquer l'état de l'envoi du formulaire :

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

Les classes suivantes constituent un polyfill pour les pseudo-classes d'interaction avec l'utilisateur :

• .user-valid
• .user-invalid

Ces classes permettent aux éditeurs d'appliquer un style à leurs entrées et jeux de champs, de telle sorte qu'ils interagissent avec les actions des utilisateurs (il peut s'agir, par exemple, de la mise en évidence d'une entrée non valide avec une bordure rouge après que l'utilisateur l'a floutée).

Pour en savoir plus sur l'utilisation de ces classes, consultez l'intégralité du code.

Points à noter concernant la sécurité

Protection contre les attaques XSRF

Outre les consignes de la spécification AMP CORS, prêtez une attention particulière aux informations de la section "Processing state changing requests"#processing-state-changing-requests) pour vous protéger comme les attaques XSRF au cours desquelles un pirate informatique peut exécuter des commandes non autorisées à l'aide de la session utilisateur en cours, à l'insu de l'utilisateur.

Veuillez garder à l'esprit les points suivants lorsque vous acceptez des entrées de l'utilisateur :

• Utilisez uniquement POST pour les requêtes de changement d'état.
• Utilisez les requêtes GET non XHR uniquement à des fins de navigation (pour la recherche, par exemple).
  • Les en-têtes "origin" reçus par les requêtes GET non XHR manquent de précision et les backends ne peuvent pas offrir de protection contre XSRF avec le mécanisme décrit ci-dessus.
  • En règle générale, il est conseillé de n'utiliser des requêtes GET XHR/non XHR que dans le cadre de la navigation ou de la récupération d'informations.
• Les requêtes POST non XHR ne sont pas autorisées dans les documents AMP. Cela est dû au fait que l'en-tête Origin est défini de manière incohérente sur ces requêtes en fonction du navigateur. De plus, leur prise en charge entraînerait des complications dans le cadre de la protection contre les attaques XSRF. Ce point pourra être réexaminé ultérieurement. Si vous estimez que cela est nécessaire, veuillez nous en faire part.