AMP

Thank you!

amp-render

Description

Renders remote or inline data using a template.

 

Required Scripts

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

Usage

The amp-render component renders content in a specified template. It can fetch content from a CORS JSON endpoint or inline from amp-state or amp-script.

Your endpoint must implement the requirements specified in the CORS Requests in AMP spec.

You can specify a template in one of two ways:

  • a template attribute that references an ID of an existing templating element.
<template id="my-template" type="amp-mustache">
  Your personal offer: ${{price}}</template>
<amp-render template="my-template" src="https://example.com/data.json">
</amp-render>
  • a templating element nested directly inside the amp-render element.
<amp-render src="https://example.com/data.json">
  <template type="amp-mustache">
    Your personal offer: ${{price}}  </template>
</amp-render>

For more details on templates, see AMP HTML Templates.

XHR batching

AMP batches XMLHttpRequests (XHRs) to JSON endpoints. This lets you use a single JSON request as a data source for multiple elements on an AMP page. For example, if your <amp-render> makes an XHR to an endpoint, while the XHR is in flight, all subsequent XHRs to the same endpoint won't trigger and will instead return the results from the first XHR.

Placeholder and fallback

<amp-render> supports an optional placeholder and/or fallback.

  • A placeholder is a child element with the placeholder attribute. This element is shown until the <amp-render> loads successfully. If a fallback is also provided, the placeholder is hidden when the <amp-render> fails to load.
  • A fallback is a child element with the fallback attribute. This element is shown if the <amp-render> fails to load.

Learn more in Placeholders & Fallbacks. Note that a child element cannot be both a placeholder and a fallback.

<amp-render src="https://example.com/data.json">
  <div placeholder>Loading ...</div>
  <div fallback>Failed to load data.</div>
</amp-render>

Refreshing data

The <amp-render> element exposes a refresh action that other elements can reference in on="tap:..." attributes.

<button on="tap:myComponent.refresh">Refresh</button>
<amp-render id="myComponent" src="https://example.com/data.json">
  <template type="amp-mustache">
    <div>{{title}}</div>
  </template>
</amp-render>

Substitutions

<amp-render> allows all standard URL variable substitutions. See the Substitutions Guide for more info.

For example:

<amp-render src="https://example.com/data.json?RANDOM"></amp-render>

may make a request to something like https://example.com/data.json?0.8390278471201 where the RANDOM value is randomly generated upon each impression.

Attributes

src (required)

The URL of the remote endpoint that returns the JSON that will be rendered within this <amp-render>. There are three valid protocols for the src attribute.

  1. https: This must refer to a CORS HTTP service. Insecure HTTP is not supported.
  2. amp-state: For initializing from <amp-state> data. See Initialization from <amp-state> section from amp-list for more details.
  3. amp-script: For using <amp-script> functions as the data source. See Using <amp-script> as a data source section from amp-list for more details.

Your endpoint must implement the requirements specified in the CORS Requests in AMP spec.

The src attribute may be omitted if the [src] attribute exists. [src] supports URL and non-URL expression values.

credentials

Defines a credentials option as specified by the Fetch API.

  • Supported values: omit, include
  • Default: omit

To send credentials, pass the value of include. If this value is set, the response must follow the AMP CORS security guidelines.

The example below uses the "include" value in credentials to display personalized content:

<amp-render
  credentials="include"
  src="<%host%>/json/product.json?clientId=CLIENT_ID(myCookieId)"
>
  <template type="amp-mustache">
    Your personal offer: ${{price}}  </template>
</amp-render>

xssi-prefix

Causes <amp-render> to strip a prefix from the fetched JSON before parsing. This can be useful for APIs that include security prefixes like )]} to help prevent cross site scripting attacks.

For example, let's say we had an API that returned this response:

)]}{ "items": ["value"] }

We could instruct amp-render to remove the security prefix like so:

<amp-render xssi-prefix=")]}" src="https://example.com/data.json"></amp-render>

key

Defines the expression to locate the sub-object to be rendered within the response. For example, let's say we had an API that returned this response:

{
  "automobiles": {
    "cars": {
      "german": {
        "make": "BMW",
        "model": "M3"
      },
      "american": {
        "make": "Tesla",
        "model": "Model X"
      }
    }
  }
}

If we just want to display the German cars from the response, we can use the key attribute.

<amp-render src="https://example.com/data.json" key="automobiles.cars.german">
  <template type="amp-mustache">
{{make}} {{model}}  </template>
</amp-render>

Note that they key attribute is valid only when src is a URL.

binding

Controls whether to block render to evaluate bindings (e.g. [text]) in children on pages using amp-render and amp-bind together.

  • binding="never" or binding="no": Never block render (fastest).
  • binding="refresh" (default): Don't block render on initial load (faster).
  • binding="always": Always block render (slow).

Essentially, binding="always" is binding="refresh" that also blocks to evaluate bindings on the initial load of amp-render.

If binding attribute is not provided, default is refresh. This is a departure from amp-list binding where the default is always. Due to this change, if specifying only a bound src attribute ([src]), it is imperative to include the binding="always" attribute on the component to be able to display templated content on the initial load.

Common attributes

This element includes common attributes extended to AMP components.

Accessibility

For amp-render instances that do not have an aria-live attribute, aria-live="polite" will be added so any changes to the content are announced by screen readers. To override the addition of aria-live="polite", add aria-live="off".

Validation

See amp-render rules in the AMP validator specification.

Perlu bantuan lainnya?

Anda telah membaca dokumen ini belasan kali, tetapi belum semua pertanyaan Anda terjawab? Mungkin orang lain merasakan hal yang sama. Berinteraksilah dengan mereka di Stack Overflow.

Kunjungi Stack Overflow
Menemukan bug atau ada fitur yang kurang?

Proyek AMP sangat menganjurkan partisipasi dan kontribusi Anda! Kami berharap Anda akan terus ambil bagian dalam komunitas sumber terbuka kami, tetapi kami juga menerima kontribusi satu kali untuk topik tertentu yang Anda minati.

Kunjungi GitHub