AMP

Important: this documentation is not applicable to your currently selected format stories!

amp-mustache

Description

Autoriser l'affichage de modèles Mustache.js.

 

Required Scripts

<script async custom-template="amp-mustache" src="https://cdn.ampproject.org/v0/amp-mustache-0.2.js"></script>

Ce composant autorise l'affichage de modèle Mustache.js.

Script requis
<script async custom-template="amp-mustache" src="https://cdn.ampproject.org/v0/amp-mustache-0.2.js"></script>
Exemples Consultez l'exemple de composant amp-mustache annoté sur AMP By Example.

Remarques relatives à la version

Version Description
0.2 Compatibilité avec les éléments <svg> et réduction de la taille du paquet (12,2 Ko contre 20,5 Ko, compressé avec gzip).

Migration vers une bibliothèque de désinfection HTML plus récente (de Caja vers DOMPurify). Cela peut entraîner de légères modifications, compte tenu des différences au niveau de la mise sur liste blanche des balises et des attributs. Nous vous recommandons de commencer par tester vos pages avant de passer en production pour vous assurer que les modifications apportées au balisage généré n'ont pas d'incidence sur la fonctionnalité.
0.1 Mise en œuvre initiale.

Syntaxe

Mustache est une syntaxe de modèle sans logique. Pour plus d'informations, consultez les documents relatifs à Mustache.js. Voici quelques-unes des principales balises de Mustache :

  • {{variable}} : balise de variable. Affiche la valeur d'une variable avec échappement HTML.
  • {{#section}}{{/section}}: balise de section. Permet de vérifier l'existence d'une variable et de la répéter s'il s'agit d'un tableau.
  • {{^section}}{{/section}}: : balise inversée. Permet de vérifier qu'une variable n'existe pas.
  • {{{unescaped}}} : balise HTML sans échappement. Elle est limitée dans le balisage qu'elle peut générer (voir la section "Restrictions" ci-dessous).

Utilisation

Le modèle amp-mustache doit être défini et utilisé conformément aux spécifications du modèle AMP.

Tout d'abord,amp-mustache doit être déclaré et chargé comme suit :

<script src="https://cdn.ampproject.org/v0/amp-mustache-0.2.js" async="" custom-template="amp-mustache"></script>

Ensuite, les modèles Mustache peuvent être définis dans une balise script ou template comme suit :

<!-- Utilisation de la balise template. -->
<template type="amp-mustache">
  Hello {{world}}!
</template>

ou

<script type="text/plain" template="amp-mustache">
  Hello {{world}}!
</script>

Dans la mesure du possible, utilisez la balise template, car la validation AMP fournit des indications dev-x utiles. Utilisez le modèle script pour les cas extrêmes et les problèmes liés à la création de modèles dans le contexte des tables. Pour en savoir plus, consultez la section "Tables" ci-dessous.

Le mode de détection des modèles, le moment où ils sont affichés et la manière dont les données sont fournies sont autant d'informations déterminées par l'élément AMP cible qui utilise ce modèle pour afficher son contenu (par exemple, dans un composant amp-list, amp-form, etc.).

Restrictions

Validation

À l'instar de tous les modèles AMP, les modèles amp-mustache doivent être des fragments DOM correctement formatés. Cela signifie notamment que vous ne pouvez pas utiliser amp-mustache pour les tâches suivantes :

  • Calculer le nom de la balise. Par exemple, <{{tagName}}> n'est pas autorisé.
  • Calculer le nom de l'attribut. Par exemple, <div {{attrName}}=something> n'est pas autorisé.

La sortie de "triple mustache" est expurgée afin de n'autoriser que les balises suivantes : a, b, br, caption, colgroup, code, del, div, em, i, ins, li, mark, ol, p, q, s, small, span, strong, sub, sup, table, tbody, time, td, th, thead, tfoot, tr, u, ul.

Désinfection

La sortie de Mustache est désinfectée pour des raisons de sécurité, mais aussi pour maintenir la conformité avec AMP. Cela peut entraîner la suppression discrète de certains éléments et attributs.

Pièges

Modèles imbriqués

Conformément à la validation AMP, les éléments <template> ne peuvent pas être des enfants d'autres éléments <template>. Cela peut se produire lors de l'imbrication de deux composants qui utilisent des modèles ; amp-list et amp-form, par exemple.

Pour contourner ce problème, les éléments <template> peuvent également être référencés par id via l'attribut template sur le composant. Par exemple :

<amp-list id="myList" src="https://foo.com/list.json">
  <template type="amp-mustache">
    <div>{{title}}</div>
  </template>
</amp-list>

Peut également être représenté sous la forme :

<!-- Externalize templates to avoid nesting. -->
<template type="amp-mustache" id="myTemplate">
  <div>{{title}}</div>
</template>

<amp-list id="myList" src="https://foo.com/list.json" template="myTemplate">
</amp-list>

Tables

Étant donné que les chaînes de modèle AMP doivent être spécifiées dans des éléments <template>, cela peut entraîner un comportement inattendu en raison de l'analyse du navigateur. Par exemple, les éléments <table> peuvent se traduire par l'adoption du texte (concept de foster parenting en anglais). Dans l'exemple suivant :

<template type="amp-mustache">
  <table>
    <tr>
      {{#foo}}<td></td>{{/foo}}
  </tr>
</table>
</template>

Le navigateur va adopter les nœuds de texte {{#foo}} et {{/foo}}:

{{#foo}}
{{/foo}}

<table>
  <tr>
    <td></td>
  </tr>
</table>

Pour remédier au problème, vous pouvez encapsuler les sections Mustache dans les commentaires HTML (<!-- {{#bar}} -->, par exemple) en utilisant plutôt des éléments non table tels que <div> ou en utilisant une balise <script type="text/plain"> pour définir vos modèles.

<script type="text/plain" template="amp-mustache">
  <table>
    <tr>
      {{#foo}}<td></td>{{/foo}}
  </tr>
</table>
</script>

Échappement de guillemets simples ou doubles

Lorsque vous utilisez amp-mustache pour calculer des valeurs d'attribut, l'échappement de guillemets simples ou doubles peut poser problème. Par exemple :

<template type="amp-mustache">
<!-- A double-quote (") in foo will cause malformed HTML. -->
<amp-img alt="{{foo}}" src="example.jpg" width="100" height="100"></amp-img>

<!-- A single-quote (') or double-quote (") in bar will cause an AMP runtime parse error. -->
<button on="tap:AMP.setState({foo: &#39;{{bar}}&#39;})">Cliquer ici</button>
</template>

L'utilisation de codes de caractères HTML dans les variables {{foo}} et {{bar}} ne fonctionne pas, car Mustache interprète les caractères &amp; en HTML (par exemple, &amp;quot; -> &amp;amp;quot;). Une solution consiste à utiliser des caractères fac-similé ; par exemple, ′ (&prime;) et ″ (&Prime;).

Il existe une proposition ouverte pour effectuer plutôt cette substitution dans le composant amp-mustache. N'hésitez pas à commenter le problème si vous souhaitez apporter votre aide.

Entités HTML

Les entités HTML ne sont pas conservées dans les éléments <template>.

Cela peut poser problème si vous souhaitez effectuer un rendu côté serveur d'un élément <template> contenant du texte généré par l'utilisateur, car le texte qui contient {{, }}, {{{, }}} sera traité comme une section Mustache. Par exemple, {{ ne peut pas être remplacé par les entités HTML &lcub;&lcub;, car elles ne sont pas conservées lorsque le navigateur analyse l'élément <template>.

Pour remédier à ce problème, vous pouvez remplacer des chaînes telles que {{ par des caractères différents ou les supprimer purement et simplement du contenu généré par l'utilisateur.

Validation

Consultez les règles relatives à amp-mustache dans les spécifications du validateur AMP.

Besoin d'une aide supplémentaire ?

Vous avez lu ce document une douzaine de fois mais il ne répond pas à toutes vos questions ? D'autres personnes ont peut-être eu le même sentiment. Contactez-les sur Stack Overflow.

Se rendre sur Stack Overflow
Vous avez trouvé un bug ou une fonctionnalité manquante ?

Le projet AMP encourage fortement votre participation et vos contributions ! Nous espérons que vous deviendrez un membre régulier de notre communauté open source, mais nous serons également ravis de recevoir des contributions ponctuelles concernant les questions qui vous intéressent particulièrement.

Se rendre sur GitHub