<!--
@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 <img src="..."> 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>