[WIP] allow user to override amp-img placeholder and hook into active and hidden class

builtins/amp-img.js

@@ -48,6 +48,9 @@ export function installImg(win) {
       /** @private {?Element} */
       this.placeholder_ = this.getPlaceholder();
 
+      /** @private {boolean} */
+      this.pendingPlaceholderState_ = false;
+
       /** @private {boolean} */
       this.isDefaultPlaceholder_ = !this.placeholder_;
 
@@ -69,7 +72,7 @@ export function installImg(win) {
       this.srcset_ = parseSrcset(this.element.getAttribute('srcset') ||
           this.element.getAttribute('src'));
 
-      this.setDefaultPlaceholder_();
+      this.setDefaultPlaceholder_(true);
       // TODO(@dvoytenko) Remove when #254 is fixed.
       // Always immediately request the first two images to make sure
       // we start the HTTP requests for them as early as possible.
@@ -98,7 +101,9 @@ export function installImg(win) {
      * @override
      */
     viewportCallback(inViewport) {
-      this.setDefaultPlaceholder_();
+      if (inViewport) {
+        this.setDefaultPlaceholder_();
+      }
     }
 
     /**
@@ -118,36 +123,40 @@ export function installImg(win) {
     }
 
     /**
+     * @param {boolean=} opt_asyncFlag
      * @private
      */
-    setDefaultPlaceholder_() {
-      if (this.isDefaultPlaceholder_ && !this.placeholder_ &&
-          !this.imgLoadedOnce_ && this.isInViewport()) {
+    setDefaultPlaceholder_(opt_asyncFlag) {
+      if (this.isDefaultPlaceholder_ && !this.placeholder_) {
         this.placeholder_ = createLoaderElement();
         this.placeholder_.setAttribute('placeholder', '');
         this.element.appendChild(this.placeholder_);
+      }
 
+      if (opt_asyncFlag) {
+        this.pendingPlaceholderState_ = true;
         // Set a minimum delay in case the image resource loads much faster
         // than an intermitent loading screen that dissapears right away.
         // This can occur on fast internet connections or on a local server.
-        return timer.delay(() => {
-          this.placeholder_.classList
-              .toggle('hidden', this.imgLoadedOnce_);
-          this.placeholder_.classList
-              .toggle('active', !this.imgLoadedOnce_);
-        }, 100);
+        timer.delay(() => {
+          this.togglePlaceholderState_();
+          this.pendingPlaceholderState_ = false;
+        }, 150);
+      } else if (!this.pendingPlaceholderState_) {
+        this.togglePlaceholderState_();
       }
     }
 
-    /**
-     * @private
-     */
+    /** @private */
+    togglePlaceholderState_() {
+      this.placeholder_.classList.toggle('hidden', this.imgLoadedOnce_);
+      this.placeholder_.classList.toggle('active', !this.imgLoadedOnce_);
+    }
+
+    /** @private */
     cleanupPlaceholder_() {
-      let inViewport = this.isInViewport();
-      if (this.placeholder_ && (!inViewport || this.imgLoadedOnce_)) {
-        if (this.isDefaultPlaceholder_) {
-          this.placeholder_.classList.remove('active');
-        }
+      if (this.placeholder_ && this.imgLoadedOnce_) {
+        this.placeholder_.classList.remove('active');
         this.placeholder_.classList.add('hidden');
       }
     }

builtins/amp-img.md

@@ -29,6 +29,24 @@ The `amp-img` includes attributes for denoting attribution via the attribution a
 
 Additional image features like captions can be implemented with standard HTML - using the `figure` and `figcaption` elements, for example.
 
+By default `amp-img` has a placeholder animation that will be visible until the
+image has finished downloading. You may override the properties in the default
+placeholders classes (see example below in Styling section).
+You may also fully override the default placeholder by adding a child element
+under `amp-img` and adding a `placeholder` attribute on that element and styling that element
+(and its children) as you see fit.  An `active` class is set on the
+element with the `placeholder` attribute if the image has not finished
+loading and this class is subsequently removed when the image has finished
+loading and a `hidden` class will be added to the element.
+
+If you just want to turn off the default placeholder animation add the following to your css:
+```css
+.amp-autoplaceholder.active .amp-loader-dot {
+  visibility: hidden;
+  animation-name: none;
+}
+```
+
 #### Attributes
 
 **src**
@@ -52,9 +70,51 @@ A string that indicates the attribution of the image. E.g. `attribution=“CC co
 
 #### Styling
 
-`amp-img` can be styled directly via CSS properties. Setting a grey background
+- `amp-img` can be styled directly via CSS properties. Setting a grey background
 placeholder for example could be achieved via:
 
     amp-img {
       background-color: grey;
     }
+
+- styling the default auto-placeholder
+
+  ```html
+  <style>
+    .amp-loader-dot {
+      /* lets zero out the border-radius to turn it into a square */
+      border-radius: 0;
+    }
+
+    .amp-autoplaceholder.active .amp-loader-dot {
+      /* replace the animation with ours by replacing the name and switching the timing */
+      animation: my-awesome-animation 1s infinite;
+    }
+
+    /* lets change the delay of the individual dots, the first one stats at 0 delay */
+    .amp-loader .amp-loader-dot:nth-child(2) {
+      animation-delay: .3s;
+    }
+
+    .amp-loader .amp-loader-dot:nth-child(3) {
+      animation-delay: .6s;
+    }
+
+    /* our new animation just alternates from blue and orange */
+    @keyframes my-awesome-animation {
+      0%, 100% {
+        background-color: blue;
+      }
+
+      50% {
+        background-color: orange;
+      }
+    }
+  </style>
+  <amp-img
+      src="../../examples/img/sample.jpg"
+      layout="responsive" width="360"
+      alt="abc"
+      height="216">
+  </amp-img>
+  ```

css/amp.css

@@ -177,7 +177,7 @@ amp-pixel {
   visibility: hidden;
 }
 
-.-amp-loader {
+.amp-loader {
   position: absolute;
   display: block;
   height: 10px;
@@ -188,15 +188,15 @@ amp-pixel {
   white-space: nowrap;
 }
 
-/**
- * We want to be a bit more specific here as we don't want a global active
- * to just trigger the loading animation
- */
-.-amp-autoplaceholder.active .-amp-loader-dot {
-  animation: -amp-loader-dots 2s infinite;
+.amp-autoplaceholder.active .amp-loader-dot {
+  animation: amp-loader-dots-animation 2s infinite;
+}
+
+.amp-autoplaceholder.hidden .amp-loader-dot {
+  animation-iteration-count: 0;
 }
 
-.-amp-loader-dot {
+.amp-loader-dot {
   position: relative;
   display: inline-block;
 
@@ -206,24 +206,23 @@ amp-pixel {
   border-radius: 100%;
   background-color: rgba(0, 0, 0, .3);
 
-  animation: -amp-loader-dots 1s infinite;
   box-shadow: 2px 2px 2px 1px rgba(0, 0, 0, .2);
   will-change: transform;
 }
 
-.-amp-loader .-amp-loader-dot:nth-child(1) {
+.amp-loader .amp-loader-dot:nth-child(1) {
   animation-delay: 0s;
 }
 
-.-amp-loader .-amp-loader-dot:nth-child(2) {
+.amp-loader .amp-loader-dot:nth-child(2) {
   animation-delay: .1s;
 }
 
-.-amp-loader .-amp-loader-dot:nth-child(3) {
+.amp-loader .amp-loader-dot:nth-child(3) {
   animation-delay: .2s;
 }
 
-@keyframes -amp-loader-dots {
+@keyframes amp-loader-dots-animation {
   0%, 100% {
     transform: scale(.7);
     background-color: rgba(0, 0, 0, .3);

src/loader.js

@@ -29,12 +29,12 @@ export function createLoaderElement() {
   placeholder.appendChild(loader);
 
   placeholder.classList.add('hidden');
-  placeholder.classList.add('-amp-autoplaceholder');
-  loader.classList.add('-amp-loader');
+  placeholder.classList.add('amp-autoplaceholder');
+  loader.classList.add('amp-loader');
 
   for (let i = 0; i < 3; i++) {
     let dot = document.createElement('div');
-    dot.classList.add('-amp-loader-dot');
+    dot.classList.add('amp-loader-dot');
     loader.appendChild(dot);
   }
   return placeholder;

test/functional/test-amp-img.js

@@ -72,7 +72,7 @@ describe('amp-img', () => {
       height: 200
     }).then((ampImg) => {
       let img = ampImg.querySelector('img');
-      let placeholder = ampImg.querySelector('.-amp-autoplaceholder');
+      let placeholder = ampImg.querySelector('.amp-autoplaceholder');
       expect(placeholder.hasAttribute('placeholder')).to.be.true;
       expect(placeholder).to.not.be.null;
     });