AMP

amp-mustache

Permite a renderização de Mustache.js.

Script obrigatório
<script async custom-template="amp-mustache" src="https://cdn.ampproject.org/v0/amp-mustache-0.2.js"></script>
Exemplos Veja um exemplo de amp-mustache com anotações no site AMP By Example.

Notas de versão

Versão Descrição
0.2 Compatibilidade com elementos <svg> e tamanho de pacote reduzido (12,2 KB versus 20,5 KB, compactado com Gzip).

Migra para uma biblioteca de limpeza de HTML mais moderna (de Caja para DOMPurify). Isso pode causar pequenas alterações interruptivas devido a diferenças na lista de permissões de tags e atributos. Recomendamos que você teste suas páginas antes de enviá-las para a produção para garantir que as alterações na marcação gerada não afetem a funcionalidade.
0.1 Implementação inicial.

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 &amp; (por exemplo, &quot; -> &amp;quot;). Uma solução é usar caracteres de fax, por exemplo, ′ (&prime;) e ″ (&Prime;).

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 &lcub;&lcub; 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.

Precisa de mais ajuda?

Você já leu este documento várias vezes, mas ainda ficou com dúvidas sem respostas? Talvez outras pessoas pensem da mesma forma. Procure entrar em contato com elas no Stack Overflow.

Ir para o Stack Overflow
Encontrou um bug ou sente falta de um recurso?

O projeto AMP incentiva fortemente sua participação e contribuições! Esperamos que você se torne um participante assíduo de nossa comunidade de código aberto, mas também agradecemos contribuições pontuais para problemas que você tenha particular interesse.

Ir para o GitHub