Description | Fetches content dynamically from a CORS JSON endpoint and renders it using a supplied template. |
Availability | Stable |
Required Script | <script async custom-element="amp-list" src="https://cdn.ampproject.org/v0/amp-list-0.1.js"></script> |
Supported Layouts | fill, fixed, fixed-height, flex-item, nodisplay, responsive |
Examples | Annotated code example for amp-list |
The amp-list
defines data source using the following attributes:
src
defines a CORS URL. The URL's protocol must be HTTPS.credentials
defines acredentials
option as specified by the Fetch API. To send credentials, pass the value of "include". If this is set, the response must follow the AMP CORS security guidelines.
The response is expected to contain the array that will be rendered. The path to the array
is specified using the optional items
attribute. This attribute contains the dot-notated path
to the array within the response object. The default value is "items". To indicate that the
response itself is an array, the "." value can be used. The array can be nested within the
response and accessed using, e.g. items="field1.field2"
expression.
Thus, when items="items"
is specified (the default) the response must be a JSON object that
contains an array property "items":
{
"items": [...]
}
The template can be specified using either of the following two ways:
template
attribute that references an ID of an existingtemplate
element.template
element nested directly inside of thisamp-list
element.
For more details on templates, see AMP HTML Templates.
Optionally, amp-list
element can contain an element with overflow
attribute. This
element will be shown if AMP Runtime cannot resize the amp-list
element as requested.
Example: Using overflow
<amp-list src="https://data.com/articles.json?ref=CANONICAL_URL"
width=300 height=200 layout=responsive>
<template type="amp-mustache">
<div>
<amp-img src="{{imageUrl}}" width=50 height=50></amp-img>
{{title}}
</div>
</template>
<div overflow role=button aria-label="Show more" class="list-overflow">
Show more
</div>
</amp-list>
.list-overflow[overflow] {
position: absolute;
bottom: 0;
}
The amp-list
allows all standard URL variable substitutions.
See Substitutions Guide for more info.
For example:
<amp-list src="https://foo.com/list.json?RANDOM"></amp-list>
may make a request to something like https://foo.com/list.json?0.8390278471201
where the RANDOM value is randomly generated upon each impression.
The request is always made from the client, even if the document was served from the AMP cache. Loading is triggered using normal AMP rules depending on how far the element is from the current viewport.
If amp-list
needs more space after loading it requests the AMP runtime to update its
height using the normal AMP flow. If AMP Runtime cannot satisfy the request for new
height, it will display overflow
element when available. Notice however, the typical
placement of amp-list
elements at the bottom of the document almost always guarantees
that AMP Runtime can resize it.
By default, amp-list
adds list
ARIA role to the list element and listitem
role to item
elements rendered via the template.
src (required)
The URL location of the remote endpoint that will return the JSON that will be rendered
within this amp-list
. This must be a CORS HTTP service.
credentials (optional)
Defines a credentials
option as specified by the Fetch API.
To send credentials, pass the value of "include". If this is set, the response must follow
the AMP CORS security guidelines.
The support values are "omit" and "include". Default is "omit".
items
Defines the expression to locate the array to be rendered within the response. It's a dot-notated expression that navigates via fields of the JSON response. Notice:
- The default value is "items". The expected response:
{items: [...]}
. - If the response itself is the desired array, use the value of ".". The expected response is:
[...]
. - Nest navigation is permitted (e.g., "field1.field2"). The expected response is:
{field1: {field2: [...]}}
.
common attributes
This element includes common attributes extended to AMP components.
See amp-list rules in the AMP validator specification.