amp-sidebar - Whitelist checks and Documentation.

ampproject · Apr 8, 2016 · d4608fe · d4608fe
1 parent a2dcc3f
commit d4608fe
Show file tree

Hide file tree

Showing 3 changed files with 123 additions and 3 deletions.
diff --git a/extensions/amp-sidebar/0.1/amp-sidebar.js b/extensions/amp-sidebar/0.1/amp-sidebar.js
@@ -16,8 +16,8 @@
 
 import {CSS} from '../../../build/amp-sidebar-0.1.css';
 import {Layout} from '../../../src/layout';
+import {dev, user} from '../../../src/log';
 import {isExperimentOn} from '../../../src/experiments';
-import {dev} from '../../../src/log';
 import {platform} from '../../../src/platform';
 import {setStyles} from '../../../src/style';
 import {vsyncFor} from '../../../src/vsync';
@@ -35,6 +35,9 @@ const ANIMATION_TIMEOUT = 550;
 /** @const */
 const IOS_SAFARI_BOTTOMBAR_HEIGHT = '10vh';
 
+/** @const */
+const WHITELIST_ = ['AMP-ACCORDION', 'AMP-FIT-TEXT', 'AMP-IMG'];
+
 export class AmpSidebar extends AMP.BaseElement {
   /** @override */
   isLayoutSupported(layout) {
@@ -83,6 +86,8 @@ export class AmpSidebar extends AMP.BaseElement {
       return;
     }
 
+    this.checkWhitelist_();
+
     if (this.side_ != 'left' && this.side_ != 'right') {
       const pageDir =
           this.document_.body.getAttribute('dir') ||
@@ -260,6 +265,28 @@ export class AmpSidebar extends AMP.BaseElement {
       this.bottomBarCompensated_ = true;
     }
   }
+
+  /**
+   * Checks if the sidebar only has the whitlisted custom amp- elements.
+   * @private
+   */
+  checkWhitelist_() {
+    const elements = this.element.getElementsByClassName('-amp-element');
+    let i = elements.length - 1;
+    while (i >= 0) {
+      const tagName = elements[i].tagName;
+      if (tagName.indexOf('AMP-') == 0) {
+        const isWhiteListed = user.assert(
+            WHITELIST_.indexOf(tagName) >= 0,
+            '%s can only contain the following custom tags: %s',
+            this.element, WHITELIST_);
+        if (!isWhiteListed) {
+          break;
+        }
+      }
+      i--;
+    }
+  }
 }
 
 AMP.registerElement('amp-sidebar', AmpSidebar, CSS);
diff --git a/extensions/amp-sidebar/0.1/test/test-amp-sidebar.js b/extensions/amp-sidebar/0.1/test/test-amp-sidebar.js
@@ -263,4 +263,31 @@ describe('amp-sidebar', () => {
       expect(sidebarElement.children.length).to.equal(initalChildrenCount + 1);
     });
   });
+
+  it('should whitelist properly', () => {
+    return getAmpSidebar().then(obj => {
+      assert = function() {};
+      const iframe = obj.iframe;
+      const sidebarElement = obj.ampSidebar;
+      const impl = sidebarElement.implementation_;
+      const accordion = iframe.doc.createElement('amp-accordion');
+      accordion.classList.add('-amp-element');
+      const fitText = iframe.doc.createElement('amp-fit-text');
+      fitText.classList.add('-amp-element');
+      const img = iframe.doc.createElement('amp-img');
+      img.classList.add('-amp-element');
+      sidebarElement.appendChild(accordion);
+      sidebarElement.appendChild(fitText);
+      sidebarElement.appendChild(img);
+      expect(() => {
+        impl.checkWhitelist_();
+      }).to.not.throw(/can only contain the following custom tags/);
+      const ad = iframe.doc.createElement('amp-ad');
+      ad.classList.add('-amp-element');
+      sidebarElement.appendChild(ad);
+      expect(() => {
+        impl.checkWhitelist_();
+      }).to.throw(/can only contain the following custom tags/);
+    });
+  });
 });
diff --git a/extensions/amp-sidebar/amp-sidebar.md b/extensions/amp-sidebar/amp-sidebar.md
@@ -23,6 +23,72 @@ limitations under the License.
   </tr>
   <tr>
     <td width="40%"><strong>Availability</strong></td>
-    <td><div>Experimental</div><div>Work in progress.</div></td>
+    <td><div><a href="https://www.ampproject.org/docs/reference/experimental.html">Experimental</a>; no validations yet.</div><div>Work in progress.</div></td>
   </tr>
-</table>
+  <tr>
+    <td width="40%"><strong>Required Script</strong></td>
+    <td><code>&lt;script async custom-element="amp-sidebar" src="https://cdn.ampproject.org/v0/amp-sidebar-0.1.js">&lt;/script></code></td>
+  </tr>
+  <tr>
+    <td width="40%"><strong>Examples</strong></td>
+    <td>None</td>
+  </tr>
+</table>
+
+## Behavior
+
+- There can be only one `<amp-sidebar>` in an AMP document. The `<amp-sidebar>` should be a direct child of the `<body>`.
+- The sidebar can only appear on the left or right side of a page.
+- The `<amp-sidebar>` may contain any valid HTML elements (supported by AMP).
+- The `<amp-sidebar>` may not contain any AMP Elements except for `amp-accordion`, `amp-img` and `amp-fit-text`.
+- The max-height of the sidebar is 100vh, if the height exceeds 100vh then a vertical scrollbar appears. The default height is set to 100vw in CSS and is overridable in CSS.
+- The width of the sidebar can be set and adjusted between 45px and 80vw using CSS.
+- Touch zoom is disabled on the `amp-sidebar` and it's mask when the sidebar is open.
+
+Example
+```html
+<amp-sidebar id='sidebar1'>
+  <ul>
+    <li> Nav item 1</li>
+    <li> Nav item 2</li>
+    <li> Nav item 3</li>
+    <li> Nav item 4</li>
+    <li> Nav item 5</li>
+    <li> Nav item 6</li>
+    <li> Nav item 7</li>
+    <li> Nav item 8</li>
+    <li> Nav item 9</li>
+    <li on="tap:sidebar1.close"> Close</li>
+  </ul>
+</amp-sidebar>
+```
+
+### Opening and Closing the Sidebar
+Setting the `on` attribute on one or more elements within the page and setting it's method to `toggle` will toggle the sidebar when the element is tapped or clicked. Setting the element's method to `open` or `close` will open or close the sidebar.Tapping back on the partially-visible main content area closes the sidebar.
+
+Alternatively pressing the escape key on the keyboard will also close the lightbox.
+
+Example
+```html
+<div class="hamburger" on='tap:sidebar1.toggle'></button>
+<button on='tap:sidebar1'>Open</button>
+<button on='tap:sidebar1.open'>Open</button>
+<button on='tap:sidebar1.close'>x</button>
+```
+
+## Attributes
+
+**side**
+
+The `side` attribute may be set to `left` or `right` depending upon whether sidebar should open in the left or right side of the page. If a `side` is not set on the `amp-sidebar` then it will be inherited from the `body` tag's `dir` attribute (`ltr` => `left` , `rtl` => right') and if one does not exist then the `side` is defaulted to `left`.
+
+**open**
+The `open` attribute is present on the sidebar when it is open.
+
+## Styling
+
+The `amp-sidebar` component can be styled with standard CSS.
+
+- The `width` of the `amp-sidebar` may be set to adjust the width of the sidebar between the pre-set min(45px) and max(80vw) values.
+- The height of the `amp-sidebar` may be set to adjust the height of the sidebar if required. If the height exceeds 100vw then the sidebar will have a vertical scrollbar. The preset height of the sidebar is 100vw and can be overridden in CSS to make it shorter.
+- The current state of the sidebar is exposed via the `open` attribute that is set on the `amp-sidebar` tag when the side bar is open on the page.