initialize amp-list from amp-state, finishing touches (ampproject#27180)

* amp-list: add example for initialization from amp-state * improve example, and add amp-state to allowed protocols * add documentation * remove feature flag * unique ids * lint * format amp-list.md * remove accidental additions * address choumx feedback * revert experiments-config.js * ben rewrite
twintwox · Mar 24, 2020 · 1b178b9 · 1b178b9
1 parent ddb655d
commit 1b178b9
Show file tree

Hide file tree

Showing 7 changed files with 123 additions and 16 deletions.
diff --git a/build-system/global-configs/canary-config.json b/build-system/global-configs/canary-config.json
@@ -15,6 +15,7 @@
   "amp-auto-ads-adsense-holdout": 0.1,
   "amp-auto-ads-no-op-experiment": 0.05,
   "amp-consent-restrict-fullscreen": 1,
+  "amp-list-init-from-state": 1,
   "amp-mega-menu": 1,
   "amp-nested-menu": 1,
   "amp-playbuzz": 1,

diff --git a/build-system/global-configs/prod-config.json b/build-system/global-configs/prod-config.json
@@ -15,6 +15,7 @@
   "amp-auto-ads-adsense-holdout": 0.1,
   "amp-auto-ads-no-op-experiment": 0.05,
   "amp-consent-restrict-fullscreen": 1,
+  "amp-list-init-from-state": 1,
   "amp-mega-menu": 1,
   "amp-nested-menu": 1,
   "amp-playbuzz": 1,

diff --git a/examples/amp-list.state.html b/examples/amp-list.state.html
@@ -0,0 +1,67 @@
+<!doctype html>
+<html ⚡>
+<head>
+  <meta charset="utf-8">
+  <script async src="https://cdn.ampproject.org/v0.js"></script>
+  <script async custom-element="amp-list" src="https://cdn.ampproject.org/v0/amp-list-0.1.js"></script>
+  <script async custom-template="amp-mustache" src="https://cdn.ampproject.org/v0/amp-mustache-latest.js"></script>
+  <script async custom-element="amp-bind" src="https://cdn.ampproject.org/v0/amp-bind-0.1.js"></script>
+  <link rel="canonical" href="https://amp.dev/documentation/examples/components/amp-list/">
+  <meta name="viewport" content="width=device-width,minimum-scale=1,initial-scale=1">
+  <style amp-boilerplate>body{-webkit-animation:-amp-start 8s steps(1,end) 0s 1 normal both;-moz-animation:-amp-start 8s steps(1,end) 0s 1 normal both;-ms-animation:-amp-start 8s steps(1,end) 0s 1 normal both;animation:-amp-start 8s steps(1,end) 0s 1 normal both}@-webkit-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-moz-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-ms-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@-o-keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}@keyframes -amp-start{from{visibility:hidden}to{visibility:visible}}</style><noscript><style amp-boilerplate>body{-webkit-animation:none;-moz-animation:none;-ms-animation:none;animation:none}</style></noscript>
+  <style amp-custom>
+    amp-list {
+      margin-left: 16px;
+    }
+    .list-overflow {
+      width: 160px;
+      margin-left: auto;
+    }
+  </style>
+</head>
+<body>
+  <div on="tap:list1.refresh,list2.refresh,list3.refresh">
+    Refresh All Lists
+  </div>
+
+  <h3>Static amp-list, inlined state.
+    <button on="tap:AMP.setState({'listExample': {'items': listExample.items.concat([{'title': 'appended item'}])}}),list1.refresh"> Append items</button>
+  </h3>
+  <amp-list id="list1" width="auto" height="100" [height]="20 * listExample.items.length"
+    layout="fixed-height" src="amp-state:listExample">
+    <template type="amp-mustache" id="amp-template-id">
+      <div><a href="{{url}}">{{title}}</a></div>
+    </template>
+  </amp-list>
+
+  <h3>Static amp-list, async state</h3>
+  <amp-list id="list2" width="auto" height="100" layout="fixed-height" src="amp-state:listAsyncExample" reset-on-refresh>
+    <template type="amp-mustache" id="amp-template-id">
+      <div><a href="{{url}}">{{title}}</a></div>
+    </template>
+  </amp-list>
+
+  <h3>Paging amp-list</h3>
+  <amp-list id="list3" width="auto" height="200" layout="fixed-height" src="amp-state:listAsyncExample" template="amp-template-id" class="m1" load-more="auto" load-more-bookmark="next">
+    <div overflow role="button" aria-label="Show more">
+      Show more
+    </div>
+  </amp-list>
+
+  <amp-state id="listAsyncExample" src="./list.example.json"></amp-state>
+  <amp-state id="listExample">
+    <script type="application/json">
+    {
+      "items": [
+        { "title": "amp-carousel" },
+        { "title": "amp-img" },
+        { "title": "amp-ad" },
+        { "title": "amp-accordion" }
+      ],
+      "next": "./list.example.json"
+    } 
+    </script> 
+  </amp-state>
+
+</body>
+</html>
diff --git a/extensions/amp-list/0.1/test/validator-amp-list.html b/extensions/amp-list/0.1/test/validator-amp-list.html
@@ -50,6 +50,10 @@
             [src]="foo.bar" [state]="baz.qux">
     <div></div>
   </amp-list>
+  <!-- Valid: amp-list with "amp-state" src -->
+  <amp-list width=10 height=10 src="amp-state:example"> 
+    <div></div>
+  </amp-list>
   <!-- Valid: amp-list with src and reset-on-refresh attributes -->
   <amp-list width=10 height=10
             src="https://data.com/articles.json?ref=CANONICAL_URL"

diff --git a/extensions/amp-list/0.1/test/validator-amp-list.out b/extensions/amp-list/0.1/test/validator-amp-list.out
@@ -53,6 +53,10 @@ amp-list/0.1/test/validator-amp-list.html:48:2 The attribute '[state]' may not a
 |              [src]="foo.bar" [state]="baz.qux">
 |      <div></div>
 |    </amp-list>
+|    <!-- Valid: amp-list with "amp-state" src -->
+|    <amp-list width=10 height=10 src="amp-state:example"> 
+|      <div></div>
+|    </amp-list>
 |    <!-- Valid: amp-list with src and reset-on-refresh attributes -->
 |    <amp-list width=10 height=10
 |              src="https://data.com/articles.json?ref=CANONICAL_URL"
@@ -92,7 +96,7 @@ amp-list/0.1/test/validator-amp-list.html:48:2 The attribute '[state]' may not a
 |    <!-- Valid amp-list with deprecated auto-resize attribute -->
 |    <amp-list width=10 height=10
 >>   ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:90:2 The attribute 'auto-resize' in tag 'amp-list' is deprecated - use 'replacement-to-be-determined-at-a-later-date' instead. (see https://github.com/ampproject/amphtml/issues/18849)
+amp-list/0.1/test/validator-amp-list.html:94:2 The attribute 'auto-resize' in tag 'amp-list' is deprecated - use 'replacement-to-be-determined-at-a-later-date' instead. (see https://github.com/ampproject/amphtml/issues/18849)
 |      src="https://data.com/articles.json?ref=CANONICAL_URL"
 |      auto-resize>
 |    <div></div>
@@ -144,69 +148,69 @@ amp-list/0.1/test/validator-amp-list.html:90:2 The attribute 'auto-resize' in ta
 |    <!-- Invalid: unsupported "binding" attribute value -->
 |    <amp-list width=10 height=10
 >>   ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:140:2 The attribute 'binding' in tag 'amp-list' is set to the invalid value 'this-is-an-error'. (see https://amp.dev/documentation/components/amp-list)
+amp-list/0.1/test/validator-amp-list.html:144:2 The attribute 'binding' in tag 'amp-list' is set to the invalid value 'this-is-an-error'. (see https://amp.dev/documentation/components/amp-list)
 |              src="https://data.com/articles.json?ref=CANONICAL_URL"
 |              binding="this-is-an-error">
 |      <div></div>
 |    </amp-list>
 |    <!-- Invalid: width is mistyped. -->
 |    <amp-list src="https://data.com/articles.json?ref=CANONICAL_URL"
 >>   ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:146:2 The attribute 'wdith' may not appear in tag 'amp-list'. (see https://amp.dev/documentation/components/amp-list)
+amp-list/0.1/test/validator-amp-list.html:150:2 The attribute 'wdith' may not appear in tag 'amp-list'. (see https://amp.dev/documentation/components/amp-list)
 |              wdith=10 height=10>
 |      <div></div>
 |    </amp-list>
 |    <!-- Invalid: missing at least src, [src] or data-amp-bind-src. -->
 |    <amp-list width=10 height=10>
 >>   ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:151:2 The tag 'amp-list' is missing a mandatory attribute - pick at least one of ['src','[src]','data-amp-bind-src']. (see https://amp.dev/documentation/components/amp-list)
+amp-list/0.1/test/validator-amp-list.html:155:2 The tag 'amp-list' is missing a mandatory attribute - pick at least one of ['src','[src]','data-amp-bind-src']. (see https://amp.dev/documentation/components/amp-list)
 |      <div></div>
 |    </amp-list>
 |    <!-- Invalid: width/height missing, so it's container layout
 |         which isn't supported. -->
 |    <amp-list src="https://data.com/articles.json?ref=CANONICAL_URL">
 >>   ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:156:2 Incomplete layout attributes specified for tag 'amp-list'. For example, provide attributes 'width' and 'height'. (see https://amp.dev/documentation/components/amp-list)
+amp-list/0.1/test/validator-amp-list.html:160:2 Incomplete layout attributes specified for tag 'amp-list'. For example, provide attributes 'width' and 'height'. (see https://amp.dev/documentation/components/amp-list)
 |      <div></div>
 |    </amp-list>
 |    <!-- Invalid amp-list with load-more attribute -->
 |    <amp-list width=10 height=10
 >>   ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:160:2 The attribute 'load-more' in tag 'amp-list' is set to the invalid value ''. (see https://amp.dev/documentation/components/amp-list)
+amp-list/0.1/test/validator-amp-list.html:164:2 The attribute 'load-more' in tag 'amp-list' is set to the invalid value ''. (see https://amp.dev/documentation/components/amp-list)
 |      src="https://data.com/articles.json?ref=CANONICAL_URL"
 |      load-more></amp-list>
 |    </amp-list>
 |    <!-- Invalid amp-list with bad load-more attribute -->
 |    <amp-list width=10 height=10
 >>   ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:165:2 The attribute 'load-more' in tag 'amp-list' is set to the invalid value 'gibberish'. (see https://amp.dev/documentation/components/amp-list)
+amp-list/0.1/test/validator-amp-list.html:169:2 The attribute 'load-more' in tag 'amp-list' is set to the invalid value 'gibberish'. (see https://amp.dev/documentation/components/amp-list)
 |      src="https://data.com/articles.json?ref=CANONICAL_URL"
 |      load-more="gibberish"
 |      load-more-bookmark="next"></amp-list>
 |    </amp-list>
 |    <!-- Invalid load-more attributes -->
 |    <div load-more-button></div>
 >>   ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:171:2 The attribute 'load-more-button' may not appear in tag 'div'.
+amp-list/0.1/test/validator-amp-list.html:175:2 The attribute 'load-more-button' may not appear in tag 'div'.
 |    <div load-more-loading></div>
 >>   ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:172:2 The attribute 'load-more-loading' may not appear in tag 'div'.
+amp-list/0.1/test/validator-amp-list.html:176:2 The attribute 'load-more-loading' may not appear in tag 'div'.
 |    <div load-more-failed></div>
 >>   ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:173:2 The attribute 'load-more-failed' may not appear in tag 'div'.
+amp-list/0.1/test/validator-amp-list.html:177:2 The attribute 'load-more-failed' may not appear in tag 'div'.
 |    <div load-more-end></div>
 >>   ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:174:2 The attribute 'load-more-end' may not appear in tag 'div'.
+amp-list/0.1/test/validator-amp-list.html:178:2 The attribute 'load-more-end' may not appear in tag 'div'.
 |    <amp-list-load-more></amp-list-load-more>
 >>   ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:175:2 The parent tag of tag 'amp-list-load-more' is 'body', but it can only be 'amp-list'. (see https://amp.dev/documentation/components/amp-list)
+amp-list/0.1/test/validator-amp-list.html:179:2 The parent tag of tag 'amp-list-load-more' is 'body', but it can only be 'amp-list'. (see https://amp.dev/documentation/components/amp-list)
 |    <amp-list width=10 height=10
 |      src="https://data.com/articles.json?ref=CANONICAL_URL"
 |      load-more="manual"
 |      load-more-bookmark="next">
 |      <button load-more-clickable></button>
 >>     ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:180:4 The parent tag of tag 'amp-list-load-more button[load-more-clickable]' is 'amp-list', but it can only be 'amp-list-load-more'. (see https://amp.dev/documentation/components/amp-list)
+amp-list/0.1/test/validator-amp-list.html:184:4 The parent tag of tag 'amp-list-load-more button[load-more-clickable]' is 'amp-list', but it can only be 'amp-list-load-more'. (see https://amp.dev/documentation/components/amp-list)
 |    </amp-list>
 |    <amp-list width=10 height=10
 |      src="https://data.com/articles.json?ref=CANONICAL_URL"
@@ -217,7 +221,7 @@ amp-list/0.1/test/validator-amp-list.html:180:4 The parent tag of tag 'amp-list-
 |    <!-- References to template elements -->
 |    <amp-list width=10 height=10
 >>   ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:189:2 Attribute 'template' in tag 'amp-list' contains a value that does not match any other tags on the page. (see https://amp.dev/documentation/components/amp-list)
+amp-list/0.1/test/validator-amp-list.html:193:2 Attribute 'template' in tag 'amp-list' contains a value that does not match any other tags on the page. (see https://amp.dev/documentation/components/amp-list)
 |      src="https://data.com/articles.json?ref=CANONICAL_URL"
 |      template="missing">
 |      <div></div>
@@ -229,9 +233,9 @@ amp-list/0.1/test/validator-amp-list.html:189:2 Attribute 'template' in tag 'amp
 |    </amp-list>
 |    <template id="found"></template>
 >>   ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:199:2 The mandatory attribute 'type' is missing in tag 'template'. (see https://amp.dev/documentation/components/amp-mustache)
+amp-list/0.1/test/validator-amp-list.html:203:2 The mandatory attribute 'type' is missing in tag 'template'. (see https://amp.dev/documentation/components/amp-mustache)
 >>   ^~~~~~~~~
-amp-list/0.1/test/validator-amp-list.html:199:2 The tag 'template' requires including the 'amp-mustache' extension JavaScript. (see https://amp.dev/documentation/components/amp-mustache)
+amp-list/0.1/test/validator-amp-list.html:203:2 The tag 'template' requires including the 'amp-mustache' extension JavaScript. (see https://amp.dev/documentation/components/amp-mustache)
 |    <!-- Valid: amp-list with src and xssi-prefix attribute -->
 |    <amp-list width=10 height=10
 |              src="https://data.com/articles.json?ref=CANONICAL_URL"

diff --git a/extensions/amp-list/amp-list.md b/extensions/amp-list/amp-list.md
@@ -220,6 +220,35 @@ In several cases, we may need the `<amp-list>` to resize on user interaction. Fo
 </amp-list>
 ```
 
+### Initialization from amp-state
+
+In most cases, you’ll probably want to have `<amp-list>` request JSON from a server. But `<amp-list>` can also use JSON you’ve included in an `<amp-state>`, right there in your HTML! This means rendering can occur without an additional server call, although, of course, if your page is served from an AMP cache, the data may not be fresh.
+
+Here’s how to have `<amp-list>` render from an `<amp-state>`:
+
+1. Add the [amp-bind](https://amp.dev/documentation/components/amp-bind/) script to your document's `<head>`.
+2. Use the `amp-state:` protocol in your `<amp-list>`’s src attribute, like this:
+   `<amp-list src="amp-state:localState">`
+
+Note that `<amp-list>` treats your JSON in the same way whether it’s requested from your server or pulled from a state variable. The format required doesn’t change.
+
+See below for a full example,
+
+```html
+<amp-state id="localState">
+  <script type="application/json">
+    {
+      "items": [{"id": 1}, {"id": 2}, {"id": 2}]
+    }
+  </script>
+</amp-state>
+<amp-list src="amp-state:localState">
+  <template type="amp-mustache">
+    <li>{{id}}</li>
+  </template>
+</amp-list>
+```
+
 ## Attributes
 
 ### src (required)

diff --git a/extensions/amp-list/validator-amp-list.protoascii b/extensions/amp-list/validator-amp-list.protoascii
@@ -98,6 +98,7 @@ tags: {  # <amp-list> with mandatory src and/or [src] attr
     mandatory_anyof: "['src','[src]','data-amp-bind-src']"
     value_url: {
       protocol: "https"
+      protocol: "amp-state"
       allow_relative: true  # Will be set to false at a future date.
     }
     blacklisted_value_regex: "__amp_source_origin"