WebCompDev / COMPONENTS

<!--
@license
Copyright (c) 2015 The Polymer Project Authors. All rights reserved.
This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
Code distributed by Google as part of the polymer project is also
subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
-->

<link rel="import" href="../polymer/polymer.html">
<link rel="import" href="../iron-flex-layout/classes/iron-flex-layout.html">

<!--
`iron-image` is an element for displaying an image that provides useful sizing and
preloading options not found on the standard `<img>` tag.

The `sizing` option allows the image to be either cropped (`cover`) or
letterboxed (`contain`) to fill a fixed user-size placed on the element.

The `preload` option prevents the browser from rendering the image until the
image is fully loaded.  In the interim, either the element's CSS `background-color`
can be be used as the placeholder, or the `placeholder` property can be
set to a URL (preferably a data-URI, for instant rendering) for an
placeholder image.

The `fade` option (only valid when `preload` is set) will cause the placeholder
image/color to be faded out once the image is rendered.

Examples:

  Basically identical to &lt;img src="..."&gt; tag:

    <iron-image src="http://lorempixel.com/400/400"></iron-image>

  Will letterbox the image to fit:

    <iron-image style="width:400px; height:400px;" sizing="contain"
      src="http://lorempixel.com/600/400"></iron-image>

  Will crop the image to fit:

    <iron-image style="width:400px; height:400px;" sizing="cover"
      src="http://lorempixel.com/600/400"></iron-image>

  Will show light-gray background until the image loads:

    <iron-image style="width:400px; height:400px; background-color: lightgray;"
      sizing="cover" preload src="http://lorempixel.com/600/400"></iron-image>

  Will show a base-64 encoded placeholder image until the image loads:

    <iron-image style="width:400px; height:400px;" placeholder="data:image/gif;base64,..."
      sizing="cover" preload src="http://lorempixel.com/600/400"></iron-image>

  Will fade the light-gray background out once the image is loaded:

    <iron-image style="width:400px; height:400px; background-color: lightgray;"
      sizing="cover" preload fade src="http://lorempixel.com/600/400"></iron-image>


@group Iron Elements
@element iron-image
@demo demo/index.html
-->

<dom-module id="iron-image">

  <style>

    :host {
      display: inline-block;
      overflow: hidden;
      position: relative;
    }

    :host([sizing]) #img {
      display: none;
    }

    #placeholder {
      background-color: inherit;
      opacity: 1;
    }

    #placeholder.faded-out {
      transition: opacity 0.5s linear;
      opacity: 0;
    }

  </style>

  <template>

    <img id="img" role="none" hidden$="[[_computeImageVisibility(sizing)]]">
    <div id="placeholder" hidden$="[[_computePlaceholderVisibility(fade,loaded,preload)]]" class$="[[_computePlaceholderClassName(fade,loaded,preload)]]"></div>
    <content></content>

  </template>

</dom-module>

<script>

  Polymer({

    is: 'iron-image',

    properties: {
      /**
       * The URL of an image.
       */
      src: {
        observer: '_srcChanged',
        type: String,
        value: ''
      },

      /**
       * When true, the image is prevented from loading and any placeholder is
       * shown.  This may be useful when a binding to the src property is known to
       * be invalid, to prevent 404 requests.
       */
      preventLoad: {
        type: Boolean,
        value: false
      },

      /**
       * Sets a sizing option for the image.  Valid values are `contain` (full
       * aspect ratio of the image is contained within the element and
       * letterboxed) or `cover` (image is cropped in order to fully cover the
       * bounds of the element), or `null` (default: image takes natural size).
       */
      sizing: {
        type: String,
        value: null
      },

      /**
       * When a sizing option is uzed (`cover` or `contain`), this determines
       * how the image is aligned within the element bounds.
       */
      position: {
        type: String,
        value: 'center'
      },

      /**
       * When `true`, any change to the `src` property will cause the `placeholder`
       * image to be shown until the
       */
      preload: {
        type: Boolean,
        value: false
      },

      /**
       * This image will be used as a background/placeholder until the src image has
       * loaded.  Use of a data-URI for placeholder is encouraged for instant rendering.
       */
      placeholder: {
        type: String,
        value: null
      },

      /**
       * When `preload` is true, setting `fade` to true will cause the image to
       * fade into place.
       */
      fade: {
        type: Boolean,
        value: false
      },

      /**
       * Read-only value that is true when the image is loaded.
       */
      loaded: {
        notify: true,
        type: Boolean,
        value: false
      },

      /**
       * Read-only value that tracks the loading state of the image when the `preload`
       * option is used.
       */
      loading: {
        notify: true,
        type: Boolean,
        value: false
      },

      /**
       * Can be used to set the width of image (e.g. via binding); size may also be
       * set via CSS.
       */
      width: {
        observer: '_widthChanged',
        type: Number,
        value: null
      },

      /**
       * Can be used to set the height of image (e.g. via binding); size may also be
       * set via CSS.
       *
       * @attribute height
       * @type number
       * @default null
       */
      height: {
        observer: '_heightChanged',
        type: Number,
        value: null
      },

      _placeholderBackgroundUrl: {
        type: String,
        computed: '_computePlaceholderBackgroundUrl(preload,placeholder)',
        observer: '_placeholderBackgroundUrlChanged'
      },

      requiresPreload: {
        type: Boolean,
        computed: '_computeRequiresPreload(preload,loaded)'
      },

      canLoad: {
        type: Boolean,
        computed: '_computeCanLoad(preventLoad, src)'
      }

    },

    observers: [
      '_transformChanged(sizing, position)',
      '_loadBehaviorChanged(canLoad, preload, loaded)',
      '_loadStateChanged(src, preload, loaded)',
    ],

    ready: function() {
      if (!this.hasAttribute('role')) {
        this.setAttribute('role', 'img');
      }
    },

    _computeImageVisibility: function() {
      return !!this.sizing;
    },

    _computePlaceholderVisibility: function() {
      return !this.preload || (this.loaded && !this.fade);
    },

    _computePlaceholderClassName: function() {
      if (!this.preload) {
        return '';
      }

      var className = 'fit';
      if (this.loaded && this.fade) {
        className += ' faded-out';
      }
      return className;
    },

    _computePlaceholderBackgroundUrl: function() {
      if (this.preload && this.placeholder) {
        return 'url(' + this.placeholder + ')';
      }

      return null;
    },

    _computeRequiresPreload: function() {
      return this.preload && !this.loaded;
    },

    _computeCanLoad: function() {
      return Boolean(!this.preventLoad && this.src);
    },

    _widthChanged: function() {
      this.style.width = isNaN(this.width) ? this.width : this.width + 'px';
    },

    _heightChanged: function() {
      this.style.height = isNaN(this.height) ? this.height : this.height + 'px';
    },

    _srcChanged: function(newSrc, oldSrc) {
      if (newSrc !== oldSrc) {
        this.loaded = false;
      }
    },

    _placeholderBackgroundUrlChanged: function() {
      this.$.placeholder.style.backgroundImage =
        this._placeholderBackgroundUrl;
    },

    _transformChanged: function() {
      var placeholderStyle = this.$.placeholder.style;

      this.style.backgroundSize =
        placeholderStyle.backgroundSize = this.sizing;

      this.style.backgroundPosition =
        placeholderStyle.backgroundPosition =
        this.sizing ? this.position : '';

      this.style.backgroundRepeat =
        placeholderStyle.backgroundRepeat =
        this.sizing ? 'no-repeat' : '';
    },

    _loadBehaviorChanged: function() {
      var img;

      if (!this.canLoad) {
        return;
      }

      if (this.requiresPreload) {
        img = new Image();
        img.src = this.src;

        this.loading = true;

        img.onload = function() {
          this.loading = false;
          this.loaded = true;
        }.bind(this);
      } else {
        this.loaded = true;
      }
    },

    _loadStateChanged: function() {
      if (this.requiresPreload) {
        return;
      }

      if (this.sizing) {
        this.style.backgroundImage = this.src ? 'url(' + this.src + ')': '';
      } else {
        this.$.img.src = this.src || '';
      }
    }
  });

</script>