third_party/polymer/components/core-image/core-image.html

   1 <!--
   2 Copyright (c) 2014 The Polymer Project Authors. All rights reserved.
   3 This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
   4 The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
   5 The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
   6 Code distributed by Google as part of the polymer project is also
   7 subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
   8 -->
   9
  10 <!--
  11 `core-image` is an element for displaying an image that provides useful sizing and
  12 preloading options not found on the standard `<img>` tag.
  13
  14 The `sizing` option allows the image to be either cropped (`cover`) or
  15 letterboxed (`contain`) to fill a fixed user-size placed on the element.
  16
  17 The `preload` option prevents the browser from rendering the image until the
  18 image is fully loaded.  In the interim, either the element's CSS `background-color`
  19 can be be used as the placeholder, or the `placeholder` property can be
  20 set to a URL (preferably a data-URI, for instant rendering) for an
  21 placeholder image.
  22
  23 The `fade` option (only valid when `preload` is set) will cause the placeholder
  24 image/color to be faded out once the image is rendered.
  25
  26 Examples:
  27
  28   Basically identical to &lt;img src="..."&gt; tag:
  29
  30     <core-image src="http://lorempixel.com/400/400"></core-image>
  31
  32   Will letterbox the image to fit:
  33
  34     <core-image style="width:400px; height:400px;" sizing="contain"
  35       src="http://lorempixel.com/600/400"></core-image>
  36
  37   Will crop the image to fit:
  38
  39     <core-image style="width:400px; height:400px;" sizing="cover"
  40       src="http://lorempixel.com/600/400"></core-image>
  41
  42   Will show light-gray background until the image loads:
  43
  44     <core-image style="width:400px; height:400px; background-color: lightgray;"
  45       sizing="cover" preload src="http://lorempixel.com/600/400"></core-image>
  46
  47   Will show a base-64 encoded placeholder image until the image loads:
  48
  49     <core-image style="width:400px; height:400px;" placeholder="data:image/gif;base64,..."
  50       sizing="cover" preload src="http://lorempixel.com/600/400"></core-image>
  51
  52   Will fade the light-gray background out once the image is loaded:
  53
  54     <core-image style="width:400px; height:400px; background-color: lightgray;"
  55       sizing="cover" preload fade src="http://lorempixel.com/600/400"></core-image>
  56
  57
  58 @group Polymer Core Elements
  59 @element core-image
  60 @homepage github.io
  61 -->
  62
  63 <link rel="import" href="../polymer/polymer.html">
  64
  65 <polymer-element name="core-image">
  66 <template>
  67   <link rel="stylesheet" href="core-image.css">
  68   <template if="{{!sizing}}">
  69     <img id="img">
  70   </template>
  71   <template if="{{preload && fade}}">
  72     <div id="placeholder" fit></div>
  73   </template>
  74   <content></content>
  75 </template>
  76 <script>
  77
  78   Polymer({
  79
  80     publish: {
  81
  82       /**
  83        * The URL of an image.
  84        *
  85        * @attribute src
  86        * @type string
  87        * @default null
  88        */
  89       src: null,
  90
  91       /**
  92        * When false, the image is prevented from loading and any placeholder is
  93        * shown.  This may be useful when a binding to the src property is known to
  94        * be invalid, to prevent 404 requests.
  95        *
  96        * @attribute src
  97        * @type string
  98        * @default null
  99        */
 100       load: true,
 101
 102       /**
 103        * Sets a sizing option for the image.  Valid values are `contain` (full
 104        * aspect ratio of the image is contained within the element and
 105        * letterboxed) or `cover` (image is cropped in order to fully cover the
 106        * bounds of the element), or `null` (default: image takes natural size).
 107        *
 108        * @attribute sizing
 109        * @type string
 110        * @default null
 111        */
 112       sizing: null,
 113
 114       /**
 115        * When a sizing option is uzed (`cover` or `contain`), this determines
 116        * how the image is aligned within the element bounds.
 117        *
 118        * @attribute position
 119        * @type string
 120        * @default 'center'
 121        */
 122       position: 'center',
 123
 124       /**
 125        * When `true`, any change to the `src` property will cause the `placeholder`
 126        * image to be shown until the
 127        *
 128        * @attribute preload
 129        * @type boolean
 130        * @default false
 131        */
 132       preload: false,
 133
 134       /**
 135        * This image will be used as a background/placeholder until the src image has
 136        * loaded.  Use of a data-URI for placeholder is encouraged for instant rendering.
 137        *
 138        * @attribute placeholder
 139        * @type string
 140        * @default null
 141        */
 142       placeholder: null,
 143
 144       /**
 145        * When `preload` is true, setting `fade` to true will cause the image to
 146        * fade into place.
 147        *
 148        * @attribute fade
 149        * @type boolean
 150        * @default false
 151        */
 152       fade: false,
 153
 154       /**
 155        * Read-only value that tracks the loading state of the image when the `preload`
 156        * option is used.
 157        *
 158        * @attribute loading
 159        * @type boolean
 160        * @default false
 161        */
 162       loading: false,
 163
 164       /**
 165        * Can be used to set the width of image (e.g. via binding); size may also be
 166        * set via CSS.
 167        *
 168        * @attribute width
 169        * @type number
 170        * @default null
 171        */
 172       width: null,
 173
 174       /**
 175        * Can be used to set the height of image (e.g. via binding); size may also be
 176        * set via CSS.
 177        *
 178        * @attribute height
 179        * @type number
 180        * @default null
 181        */
 182       height: null
 183
 184     },
 185
 186     observe: {
 187       'preload color sizing position src fade': 'update'
 188     },
 189
 190     widthChanged: function() {
 191       this.style.width = isNaN(this.width) ? this.width : this.width + 'px';
 192     },
 193
 194     heightChanged: function() {
 195       this.style.height = isNaN(this.height) ? this.height : this.height + 'px';
 196     },
 197
 198     update: function() {
 199       this.style.backgroundSize = this.sizing;
 200       this.style.backgroundPosition = this.sizing ? this.position : null;
 201       this.style.backgroundRepeat = this.sizing ? 'no-repeat' : null;
 202       if (this.preload) {
 203         if (this.fade) {
 204           if (!this._placeholderEl) {
 205             this._placeholderEl = this.shadowRoot.querySelector('#placeholder');
 206           }
 207           this._placeholderEl.style.backgroundSize = this.sizing;
 208           this._placeholderEl.style.backgroundPosition = this.sizing ? this.position : null;
 209           this._placeholderEl.style.backgroundRepeat = this.sizing ? 'no-repeat' : null;
 210           this._placeholderEl.classList.remove('fadein');
 211           this._placeholderEl.style.backgroundImage = (this.load && this.placeholder) ? 'url(' + this.placeholder + ')': null;
 212         } else {
 213           this._setSrc(this.placeholder);
 214         }
 215         if (this.load && this.src) {
 216           var img = new Image();
 217           img.src = this.src;
 218           this.loading = true;
 219           img.onload = function() {
 220             this._setSrc(this.src);
 221             this.loading = false;
 222             if (this.fade) {
 223               this._placeholderEl.classList.add('fadein');
 224             }
 225           }.bind(this);
 226         }
 227       } else {
 228         this._setSrc(this.src);
 229       }
 230     },
 231
 232     _setSrc: function(src) {
 233       if (this.sizing) {
 234         this.style.backgroundImage = src ? 'url(' + src + ')': '';
 235       } else {
 236         this.$.img.src = src || '';
 237       }
 238     }
 239
 240   });
 241
 242 </script>
 243 </polymer-element>