📖 Add imperative API code samples to Bento component documentation (#…

…32234) * Stream gallery * Inline gallery * Lightbox documentation * Selector documentation * Restore backticks to dead links * Add tip notation Co-authored-by: CrystalOnScript <crystallambert@google.com> * Fix link * ' -> " Co-authored-by: CrystalOnScript <crystallambert@google.com>
ampproject · Jan 27, 2021 · c1d09c4 · c1d09c4
1 parent 3baf76e
commit c1d09c4
Show file tree

Hide file tree

Showing 4 changed files with 530 additions and 15 deletions.
diff --git a/extensions/amp-inline-gallery/amp-inline-gallery.md b/extensions/amp-inline-gallery/amp-inline-gallery.md
@@ -71,14 +71,140 @@ The `<amp-inline-gallery>` component uses an `<amp-base-carousel>` to display sl
 
 The above example shows slides using an aspect ratio of 3:2, with 10% of a slide peeking on either side. An aspect ratio of 3.6:2 is used on the `amp-base-carousel` to show 1.2 slides at a time.
 
-### Migrating from 0.1
+### Standalone use outside valid AMP documents
 
-Unlike `0.1`, the experimental `1.0` version of `amp-inline-gallery` includes the following changes:
+Bento AMP allows you to use AMP components in non-AMP pages without needing to commit to fully valid AMP. You can take these components and place them in implementations with frameworks and CMSs that don't support AMP. Read more in our guide `[Use AMP components in non-AMP pages](https://amp.dev/documentation/guides-and-tutorials/start/bento_guide/)`.
 
--   `amp-inline-gallery-pagination` with `inset` attribute positions the element with an overwritable `bottom: 0`.
--   `amp-inline-gallery-thumbnails` takes `data-thumbnail-src` from slide elements (children of the `amp-base-carousel`) instead of `srcset`.
--   `amp-inline-gallery-thumbnails` takes `aspect-ratio` as expressed by `width / height` instead of two separate attributes, `aspect-ratio-width` and `aspect-ratio-height`.
--   `amp-inline-gallery-thumbnails` configuration for `loop` defaults to `"false"`.
+#### Example
+
+The example below demonstrates `amp-inline-gallery` component in standalone use.
+
+[example preview="top-frame" playground="false"]
+
+```
+<head>
+  <script async src="https://cdn.ampproject.org/v0.js"></script>
+  <link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/amp-inline-gallery-1.0.css">
+  <script async custom-element="amp-inline-gallery" src="https://cdn.ampproject.org/v0/amp-inline-gallery-1.0.js"></script>
+  <link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/amp-base-carousel-1.0.css">
+  <script async custom-element="amp-inline-gallery" src="https://cdn.ampproject.org/v0/amp-base-carousel-1.0.js"></script>
+  <style>
+    amp-base-carousel {
+      aspect-ratio: 3/1;
+    }
+    amp-base-carousel > div {
+      aspect-ratio: 1/1;
+    }
+    amp-inline-gallery-pagination {
+      height: 20px;
+    }
+    .red-gradient {
+      background: brown;
+      background: linear-gradient(90deg, brown 50%, lightsalmon 90%, wheat 100%);
+    }
+    .blue-gradient {
+      background: steelblue;
+      background: linear-gradient(90deg, steelblue 50%, plum 90%, lavender 100%);
+    }
+    .green-gradient {
+      background: seagreen;
+      background: linear-gradient(90deg, seagreen 50%, mediumturquoise 90%, turquoise 100%);
+    }
+    .pink-gradient {
+      background: pink;
+      background: linear-gradient(90deg, pink 50%, lightsalmon 90%, wheat 100%);
+    }
+    .yellow-gradient {
+      background: gold;
+      background: linear-gradient(90deg, gold 50%, goldenrod 90%, darkgoldenrod 100%);
+    }
+    .orange-gradient {
+      background: peru;
+      background: linear-gradient(90deg, peru 50%, chocolate 90%, saddlebrown 100%);
+    }
+    .seafoam-gradient {
+      background: darkseagreen;
+      background: linear-gradient(90deg, darkseagreen 50%, lightseagreen 90%, MediumAquaMarine 100%);
+    }
+    .purple-gradient {
+      background: rebeccapurple;
+      background: linear-gradient(90deg, rebeccapurple 50%, mediumpurple 90%, mediumslateblue 100%);
+    }
+    .cyan-gradient {
+      background: darkcyan;
+      background: linear-gradient(90deg, darkcyan 50%, lightcyan 90%, white 100%);
+    }
+  </style>
+</head>
+<amp-inline-gallery>
+  <amp-base-carousel id="my-carousel">
+    <div class="red-gradient"></div>
+    <div class="blue-gradient"></div>
+    <div class="green-gradient"></div>
+    <div class="pink-gradient"></div>
+    <div class="yellow-gradient"></div>
+    <div class="orange-gradient"></div>
+    <div class="seafoam-gradient"></div>
+    <div class="purple-gradient"></div>
+    <div class="cyan-gradient"></div>
+  </amp-base-carousel>
+  <amp-inline-gallery-pagination>
+</amp-inline-gallery>
+<div class="buttons" style="margin-top: 8px;">
+  <button id='prev-button'>Go to previous page of slides</button>
+  <button id='next-button'>Go to next page of slides</button>
+  <button id='go-to-button'>Go to slide with green gradient</button>
+</div>
+<script>
+  (async () => {
+    const carousel = document.querySelector('#my-carousel');
+    await customElements.whenDefined('amp-base-carousel');
+    const api = await carousel.getApi();
+    // programatically advance to next slide
+    api.next();
+    // set up button actions
+    document.querySelector('#prev-button').onclick = () => api.prev();
+    document.querySelector('#next-button').onclick = () => api.next();
+    document.querySelector('#go-to-button').onclick = () => api.goToSlide(2);
+  })();
+</script>
+```
+
+[/example]
+
+#### Interactivity and API usage
+
+Bento enabled components in standalone use are highly interactive through their API. In Bento standalone use, the element's API replaces AMP Actions and events and [`amp-bind`](https://amp.dev/documentation/components/amp-bind/?format=websites).
+
+The `amp-inline-gallery` component is used in combination with `amp-base-carousel` and should access the [`amp-base-carousel` API](https://amp.dev/documentation/components/amp-base-carousel-v1.0/?format=websites) accordingly.
+
+#### Layout and style
+
+Each Bento component has a small CSS library you must include to guarantee proper loading without [content shifts](https://web.dev/cls/). Because of order-based specificity, you must manually ensure that stylesheets are included before any custom styles.
+
+```
+<link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/amp-inline-gallery-1.0.css">
+<link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/amp-base-carousel-1.0.css">
+```
+
+Fully valid AMP pages use the AMP layout system to infer sizing of elements to create a page structure before downloading any remote resources. However, Bento use imports components into less controlled environments and AMP's layout system is inaccessible.
+
+**Container type**
+
+The `amp-inline-gallery-pagination` and `amp-inline-gallery-thumbnails` components have defined layout size types. To ensure the components render correctly, be sure to apply a size to the component and its immediate children (slides) via a desired CSS layout (such as one defined with `height`, `width`, `aspect-ratio`, or other such properties):
+
+```css
+amp-inline-gallery-pagination {
+  height: 20px;
+}
+amp-inline-gallery-thumbnails {
+  aspect-ratio: 4/1
+}
+```
+
+[tip type="note"]
+Because this component composes with `amp-base-carousel`, be sure to also follow [`amp-base-carousel` styling recommendations](https://amp.dev/documentation/components/amp-base-carousel-v1.0/?format=websites#usage).
+[/tip]
 
 ### Include pagination indicators
 
@@ -275,3 +401,12 @@ The `<amp-inline-gallery-thumbnails>` element includes <a href="https://amp.dev/
 ### common attributes
 
 This element includes <a href="https://amp.dev/documentation/guides-and-tutorials/learn/common_attributes">common attributes</a> extended to AMP components.
+
+## Version notes
+
+Unlike `0.1`, the experimental `1.0` version of `amp-inline-gallery` includes the following changes:
+
+-   `amp-inline-gallery-pagination` with `inset` attribute positions the element with an overwritable `bottom: 0`.
+-   `amp-inline-gallery-thumbnails` takes `data-thumbnail-src` from slide elements (children of the `amp-base-carousel`) instead of `srcset`.
+-   `amp-inline-gallery-thumbnails` takes `aspect-ratio` as expressed by `width / height` instead of two separate attributes, `aspect-ratio-width` and `aspect-ratio-height`.
+-   `amp-inline-gallery-thumbnails` configuration for `loop` defaults to `"false"`.
diff --git a/extensions/amp-lightbox/amp-lightbox.md b/extensions/amp-lightbox/amp-lightbox.md
@@ -43,13 +43,100 @@ component. To show a gallery of images in a lightbox, you can use
 
 [/tip]
 
-### Migrating from 0.1
+### Standalone use outside valid AMP documents
 
-The experimental `1.0` version of `amp-lightbox` employs the following differences from version `0.1`:
+Bento AMP allows you to use AMP components in non-AMP pages without needing to commit to fully valid AMP. You can take these components and place them in implementations with frameworks and CMSs that don't support AMP. Read more in our guide `[Use AMP components in non-AMP pages](https://amp.dev/documentation/guides-and-tutorials/start/bento_guide/)`.
 
--   This component does not currently support modifying browser history state.
--   `data-close-button-aria-label` is not supported and will soon be replaced with support for `slot="close-button"`.
--   `animate-in` has been renamed to `animation`.
+#### Example
+
+The example below demonstrates `amp-lightbox` component in standalone use.
+
+[example preview="top-frame" playground="false"]
+
+```html
+<head>
+  <script async src="https://cdn.ampproject.org/v0.js"></script>
+  <link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/amp-lightbox-1.0.css">
+  <script async custom-element="amp-lightbox" src="https://cdn.ampproject.org/v0/amp-lightbox-1.0.js"></script>
+</head>
+<amp-lightbox id="my-lightbox">
+  Lightboxed content
+  <button id='close-button'>Close lightbox</button>
+</amp-lightbox>
+<button id='open-button'>Open lightbox</button>
+<script>
+  (async () => {
+    const lightbox = document.querySelector('#my-lightbox');
+    await customElements.whenDefined('amp-lightbox');
+    const api = await lightbox.getApi();
+
+    // set up button actions
+    document.querySelector('#open-button').onclick = () => api.open();
+    document.querySelector('#close-button').onclick = () => api.close();
+  })();
+</script>
+```
+
+[/example]
+
+#### Interactivity and API usage
+
+Bento enabled components in standalone use are highly interactive through their API. In Bento standalone use, the element's API replaces AMP Actions and events and [`amp-bind`](https://amp.dev/documentation/components/amp-bind/?format=websites).
+
+The `amp-lightbox` component API is accessible by including the following script tag in your document:
+
+```
+await customElements.whenDefined('amp-lightbox');
+const api = await lightbox.getApi();
+```
+
+##### Actions
+
+The `amp-lightbox` API allows you to perform the following actions:
+
+**open()**
+Opens the lightbox.
+
+```
+api.open();
+```
+
+**close()**
+Closes the lightbox.
+
+```
+api.close();
+```
+
+##### Events
+
+The `amp-lightbox` API allows you to register and respond to the following events:
+
+**open**
+
+This event is triggered when the lightbox is opened.
+
+```
+lightbox.addEventListener('open', (e) => console.log(e))
+```
+
+**close**
+
+This event is triggered when the lightbox is closed.
+
+```
+lightbox.addEventListener('close', (e) => console.log(e))
+```
+
+#### Layout and style
+
+Each Bento component has a small CSS library you must include to guarantee proper loading without [content shifts](https://web.dev/cls/). Because of order-based specificity, you must manually ensure that stylesheets are included before any custom styles.
+
+```
+<link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/amp-lightbox-1.0.css">
+```
+
+Fully valid AMP pages use the AMP layout system to infer sizing of elements to create a page structure before downloading any remote resources. However, Bento use imports components into less controlled environments and AMP's layout system is inaccessible.
 
 ## Attributes
 
@@ -76,6 +163,11 @@ nested element instead.
 
 [/tip]
 
+### `scrollable` (optional)
+
+When the `scrollable` attribute is present, the content of the lightbox can
+scroll when overflowing the height of the lightbox.
+
 ## Actions
 
 ### `open` (default)
@@ -113,3 +205,11 @@ attribute value, will be created and focused on.
   <button on="tap:quote-lb.close">Nice!</button>
 </amp-lightbox>
 ```
+
+## Version notes
+
+The experimental `1.0` version of `amp-lightbox` employs the following differences from version `0.1`:
+
+-   This component does not currently support modifying browser history state.
+-   `data-close-button-aria-label` is not supported and will soon be replaced with support for `slot="close-button"`.
+-   `animate-in` has been renamed to `animation`.