Removed render option, added natural as new default

After some research I discovered that waiting for onload to fire on a detached new Image() object doesn't guarantee complete rendering of an <img> element with the same source. You'll notice this when loading very large images. Having an option called `render` that uses this approach but doesn't guarantee a full render all the time doesn't make sense, so we're switching to a new option called `natural`, called as soon as naturalWidth/Height are available. This explains the intent of the polling method much better. It's enabled as our new default to make things faster.
staaky · Nov 8, 2014 · 9ca9e33 · 9ca9e33
1 parent b580d9a
commit 9ca9e33
Show file tree

Hide file tree

Showing 9 changed files with 44 additions and 43 deletions.
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@ Voilà is a [jQuery](http://jquery.com) plugin that provides callbacks for image
 
 Its API is inspired by [imagesLoaded](http://imagesloaded.desandro.com). Voilà extends this by adding useful methods like `abort()` and support for `naturalWidth/Height` in all browsers, making it compatible with IE6 and IE7.
 
-Voilà also comes with an alternative loading method that allows callbacks to be used as soon as naturalWidth/Height are available, even while images are still rendering.
+Voilà uses a polling method that triggers callbacks as soon as `naturalWidth` is available. This makes it faster than methods that wait for `onload` to fire.
 
 ## Install
 
@@ -37,7 +37,7 @@ $(element).voila([options][, callback]);
 ```js
 // For example
 $('#container').voila(callback);
-$('#container').voila({ render: false }, callback);
+$('#container').voila({ natural: false }, callback);
 ```
 
 + `options` _Object_ - (optional) An object with Options
@@ -72,11 +72,10 @@ $('#container').voila()
 
 Options can be set as the first parameter.
 
-+ `render` - _Boolean_ - Wait for images to fully render before using callbacks when `true` (the default), or as soon as naturalWidth/Height are available when `false`. Using `false` means images could still be rendering as callbacks are called.
++ `natural` - _Boolean_ - Callback are called as soon as `naturalWidth/Height` are available when `true` (the default). Using `false` will call callbacks as soon as `onload` fires on a detached Image object, which is slower, but can give the image more time to render.
 
 ```js
-$('#container').voila({ render: false }, function(instance) {
-  console.log('naturalWidth/Height available, some images might still be rendering');
+$('#container').voila({ natural: true }, function(instance) {
   $.each(instance.images, function(i, image) {
     var img = image.img;
     console.log(img.src + ' = ' + img.naturalWidth + 'x' + img.naturalHeight);

diff --git a/bower.json b/bower.json
@@ -1,6 +1,6 @@
 {
   "name": "voila",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "A jQuery plugin that provides callbacks for images, letting you know when they've loaded.",
   "keywords": [
     "image",

diff --git a/demo/index.html b/demo/index.html
@@ -21,7 +21,7 @@ <h1>Voil&agrave;</h1>
       <button id="reset">Reset</button>
     </div>
     <div class='checkboxes'>
-      <input type='checkbox' checked='checked' id='render'/> <label for='render'>Render</label>
+      <input type='checkbox' checked='checked' id='natural'/> <label for='natural'>Natural</label>
       <input type='checkbox' id='dimensions'/> <label for='dimensions'>Dimensions</label>
     </div>
   </div>

diff --git a/demo/js/demo.js b/demo/js/demo.js
@@ -28,7 +28,7 @@ var Demo = {
 
     Progress.initialize({ items: this._items });
 
-    this.renderChange();
+    this.naturalChange();
 
     this.startObserving();
   },
@@ -40,7 +40,7 @@ var Demo = {
   startObserving: function() {
     $('#add').on('click', $.proxy(this.add, this));
     $('#reset').on('click', $.proxy(this.reset, this));
-    $('#render').on('change', $.proxy(this.renderChange, this));
+    $('#natural').on('change', $.proxy(this.naturalChange, this));
   },
 
   add: function() {
@@ -95,9 +95,9 @@ var Demo = {
     }
   },
 
-  renderChange: function() {
+  naturalChange: function() {
     this.setOptions({
-      render: $('#render').prop('checked')
+      natural: $('#natural').prop('checked')
     });
   }
 };

diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "voila",
   "title": "Voil&agrave;",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "A jQuery plugin that provides callbacks for images, letting you know when they've loaded.",
   "keywords": [
     "image",

diff --git a/src/imageready.js b/src/imageready.js
@@ -17,32 +17,32 @@ $.extend(ImageReady.prototype, {
     this.isLoaded = false;
 
     this.options = $.extend({
-      render: true,
+      natural: true,
       pollFallbackAfter: 1000
     }, arguments[3] || {});
 
+
+    // a fallback is used when we're not polling for naturalWidth/Height
+    // IE6-7 also use this to add support for naturalWidth/Height
+    if (!this.supports.naturalWidth || !this.options.natural) {
+      // timeout allows callbacks to be attached
+      setTimeout($.proxy(this.fallback, this));
+      return;
+    }
+
     // can exit out right away if we have a naturalWidth
     if (this.img.complete && $.type(this.img.naturalWidth) != 'undefined') {
       setTimeout($.proxy(function() {
         if (this.img.naturalWidth > 0) {
           this.isLoaded = true;
-          this.successCallback(this);
+          this.success();
         } else {
-          this.errorCallback(this);
+          this.error();
         }
       }, this));
       return;
     }
 
-    // fallback for browsers without support for naturalWidth/Height
-    // IE7-8
-    // we also use it to wait for complete image loading
-    if (!this.supports.naturalWidth || this.options.render) {
-      // timeout allows callbacks to be attached
-      setTimeout($.proxy(this.fallback, this));
-      return;
-    }
-
     // we instantly bind to onerror so we catch right away
     // timeout allows callbacks to be attached
     $(this.img).bind('error', $.proxy(function() {
@@ -65,6 +65,7 @@ $.extend(ImageReady.prototype, {
     this._time = 0;
     this._delay = this.intervals[this._ipos][1];
 
+    // start polling
     this.poll();
   },
 
@@ -122,7 +123,7 @@ $.extend(ImageReady.prototype, {
 
     img.onerror = $.proxy(this.error, this);
 
-    img.src = $(this.img).attr('src');
+    img.src = this.img.src;
   },
 
   abort: function() {

diff --git a/src/voila.js b/src/voila.js
@@ -9,7 +9,7 @@ function Voila(elements, opts, cb) {
                    $.type(arguments[2]) === 'function' ? arguments[2] : false;
 
   this.options = $.extend({
-    render: true
+    natural: true
   }, options);
 
   this.deferred = new jQuery.Deferred();

diff --git a/voila.pkgd.js b/voila.pkgd.js
@@ -1,5 +1,5 @@
 /*!
- * Voilà - v1.0.4
+ * Voilà - v1.0.5
  * (c) 2014 Nick Stakenburg
  *
  * MIT License
@@ -25,7 +25,7 @@ function Voila(elements, opts, cb) {
                    $.type(arguments[2]) === 'function' ? arguments[2] : false;
 
   this.options = $.extend({
-    render: true
+    natural: true
   }, options);
 
   this.deferred = new jQuery.Deferred();
@@ -160,32 +160,32 @@ $.extend(ImageReady.prototype, {
     this.isLoaded = false;
 
     this.options = $.extend({
-      render: true,
+      natural: true,
       pollFallbackAfter: 1000
     }, arguments[3] || {});
 
+
+    // a fallback is used when we're not polling for naturalWidth/Height
+    // IE6-7 also use this to add support for naturalWidth/Height
+    if (!this.supports.naturalWidth || !this.options.natural) {
+      // timeout allows callbacks to be attached
+      setTimeout($.proxy(this.fallback, this));
+      return;
+    }
+
     // can exit out right away if we have a naturalWidth
     if (this.img.complete && $.type(this.img.naturalWidth) != 'undefined') {
       setTimeout($.proxy(function() {
         if (this.img.naturalWidth > 0) {
           this.isLoaded = true;
-          this.successCallback(this);
+          this.success();
         } else {
-          this.errorCallback(this);
+          this.error();
         }
       }, this));
       return;
     }
 
-    // fallback for browsers without support for naturalWidth/Height
-    // IE7-8
-    // we also use it to wait for complete image loading
-    if (!this.supports.naturalWidth || this.options.render) {
-      // timeout allows callbacks to be attached
-      setTimeout($.proxy(this.fallback, this));
-      return;
-    }
-
     // we instantly bind to onerror so we catch right away
     // timeout allows callbacks to be attached
     $(this.img).bind('error', $.proxy(function() {
@@ -208,6 +208,7 @@ $.extend(ImageReady.prototype, {
     this._time = 0;
     this._delay = this.intervals[this._ipos][1];
 
+    // start polling
     this.poll();
   },
 
@@ -265,7 +266,7 @@ $.extend(ImageReady.prototype, {
 
     img.onerror = $.proxy(this.error, this);
 
-    img.src = $(this.img).attr('src');
+    img.src = this.img.src;
   },
 
   abort: function() {

diff --git a/voila.pkgd.min.js b/voila.pkgd.min.js