amp-mustache

0.2 0.1

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

Permite a renderização de Mustache.js.

Notas de versão

Sintaxe

Mustache é uma sintaxe de modelo sem lógica. Consulte os documentos sobre Mustache.js (em inglês) para ver mais detalhes. Algumas das principais tags de Mustache são:

• {{variable}}: uma tag de variável. Gera o valor HTML com escape de uma variável.
• {{#section}}{{/section}}: uma tag de seção. Pode testar a existência de uma variável e iterá-la se for uma matriz.
• {{^section}}{{/section}}: uma tag invertida. Pode testar a inexistência de uma variável.
• {{{unescaped}}}: HTML sem escape. Fica restrito à marcação que pode gerar (consulte “Restrições” abaixo).

Uso

O modelo amp-mustache precisa ser definido e usado de acordo com a especificação de modelo de AMP (link em inglês).

Primeiro, o amp-mustache precisa ser declarado/carregado desta forma:

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

Em seguida, os modelos Mustache podem ser definidos em uma tag script ou template como esta:

<!-- Using template tag. -->
<template type="amp-mustache">
  Hello {{world}}!
</template>

ou

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

Use a tag template sempre que possível, porque a validação de AMP fornece dicas úteis sobre dev-x. Use o modelo script para casos extremos e problemas com modelos no contexto de tabelas. Veja a seção "Tabelas" abaixo.

A maneira como os modelos são descobertos, quando são renderizados e a forma como os dados são fornecidos é algo decidido pelo elemento AMP de destino que usa esse modelo para renderizar o conteúdo (por exemplo, em amp-list, amp-form etc.).

Restrições

Validação

Como todos os modelos de AMP, os modelos amp-mustache precisam ser fragmentos DOM bem formados. Isso significa que, entre outras coisas, não é possível usar o amp-mustache para:

• calcular o nome da tag. Por exemplo, <{{tagName}}> não é permitido;
• calcular o nome do atributo. Por exemplo, <div {{attrName}}=something> não é permitido.

A saída de "triple-mustache" é limpa para permitir somente as seguintes tags: 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.

Limpeza

A saída de mustache é limpa por motivos de segurança e para manter a validade de AMP. Isso pode resultar na remoção silenciosa de alguns elementos e atributos.

Armadilhas

Modelos aninhados

De acordo com a validação de AMP, os elementos <template> não podem ser filhos de outros elementos <template>. Isso pode acontecer ao aninhar dois componentes que usam modelos, como amp-list e amp-form.

Para resolver isso, os elementos <template> também podem ser referenciados por id por meio do atributo de template no componente. Exemplo:

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

Ele também pode ser representado como:

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

Tabelas

Como as strings de modelo de AMP precisam ser especificadas nos elementos <template>, isso pode causar um comportamento inesperado devido à análise do navegador. Por exemplo, os elementos <table> podem causar foster parenting do texto (link em inglês). No exemplo a seguir:

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

O navegador promoverá os nós de texto {{#foo}} e {{/foo}}:

{{#foo}}
{{/foo}}
<table>
  <tr>
    <td></td>
  </tr>
</table>

Entre as soluções estão o agrupamento de seções de Mustache em comentários HTML (por exemplo, <!-- {{#bar}} -->), usando elementos que não são de tabela, como <div>, ou usando uma tag <script type="text/plain"> para definir seus modelos.

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

Escape de citação

Ao usar amp-mustache para calcular valores de atributos, fazer escape de citação pode ser um problema. Exemplo:

<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: '{{bar}}'})">Click me</button>
</template>

O uso de códigos de caracteres HTML nas variáveis {{foo}} ou {{bar}} não funcionará, porque o Mustache fará escape de HTML dos caracteres & (por exemplo, " -> "). Uma solução é usar caracteres de fax, por exemplo, ′ (′) e ″ (″).

Há uma proposta aberta para fazer essa substituição em amp-mustache. Se você quiser apoiá-la, comente sobre o problema.

Entidades HTML

As entidades HTML não são preservadas em elementos <template>.

Isso pode ser um problema se você quiser renderizar no lado do servidor um <template> contendo texto gerado pelo usuário, porque o texto que contiver {{, }}, {{{, }}} será tratado como uma seção de Mustache. Por exemplo, a substituição de {{ pelas entidades HTML {{ não funcionará, porque elas não serão preservadas quando o navegador analisar o <template>.

As soluções incluem substituir strings como {{ por caracteres diferentes ou a removê-las diretamente do conteúdo gerado pelo usuário.

Validação

Consulte as regras do amp-mustache (link em inglês) na especificação do validador de AMP.