src & docs : re-factor callback triggers

+ document callback in intro
+ more callbacks in test
+ update README with v1.5

for #6

v1.5.0

README.mdown

@@ -36,6 +36,9 @@ Changelog
 
 View the [commit history](https://github.com/desandro/isotope/commits/master/jquery.isotope.js) for a complete robust list of changes to the script.
 
++ **v1.5**
+  [2011-10-19](https://github.com/desandro/isotope/commit/2c789ecb5ec#jquery.isotope.js)
+  - add proper callback support that trigger after animation/transition
 + **v1.4** [2011-06-29](https://github.com/desandro/isotope/commit/8e2f51612eaf20e3031b81b8c5ff5e322cbb7b4f#jquery.isotope.js)
   - shuffle method added
   - inserting and appending positions items then reveals them

_posts/docs/2010-12-01-introduction.mdown

@@ -67,6 +67,20 @@ $('#container').isotope({
 
 There are a number of [options](options.html) you can specify.  Within the options is where you can [set the layout mode](layout-modes.html), [filter items](filtering.html),  and [sort items](sorting.html).
 
+Additionally you can specify a callback after the options object. This function will be triggered after the animation has completed.
+
+{% highlight javascript %}
+
+$('#container').isotope({ filter: '.my-selector' }, function( $items ) {
+  var id = this.attr('id'),
+      len = $items.length;
+  console.log( 'Isotope has filtered for ' + len + ' items in #' + id );
+});
+
+{% endhighlight %}
+
+Within this callback <code><span class="k">this</span></code> refers to the container, and `$items` refers to the item elements. Both of these are jQuery objects and do _not_ need to be put in jQuery wrappers.
+
 ### CSS
 
 Add these styles to your CSS for [filtering](filtering.html), [animation](animating.html) with CSS transitions, and [adding items](adding-items.html).

_posts/docs/2010-12-04-methods.mdown

@@ -140,7 +140,7 @@ Removes specified item elements from Isotope widget and the DOM.
 
 {% highlight javascript %}
 
-.isotope( 'shuffle' )
+.isotope( 'shuffle', callback )
 
 {% endhighlight %}
 

_posts/tests/2011-10-19-callbacks.html

@@ -141,21 +141,21 @@ category: tests
     // change size of clicked element
     $container.delegate( '.element', 'click', function(){
       $(this).toggleClass('large');
-      $container.isotope('reLayout');
+      $container.isotope( 'reLayout', changeBGColor );
     });
 
     // toggle variable sizes of all elements
     $('#toggle-sizes').find('a').click(function(){
       $container
         .toggleClass('variable-sizes')
-        .isotope('reLayout');
+        .isotope( 'reLayout', changeBGColor );
       return false;
     });
 
 
     var $sortBy = $('#sort-by');
     $('#shuffle a').click(function(){
-      $container.isotope('shuffle');
+      $container.isotope( 'shuffle', changeBGColor );
       $sortBy.find('.selected').removeClass('selected');
       $sortBy.find('[data-option-value="random"]').addClass('selected');
       return false;

jquery.isotope.js

@@ -1,5 +1,5 @@
 /**
- * Isotope v1.5.0 beta
+ * Isotope v1.5.0
  * An exquisite jQuery plugin for magical layouts
  * http://isotope.metafizzy.co
  *
@@ -613,7 +613,6 @@
             this.isUsingJQueryAnimation ? 'animate' : 'css'
           ),
           animOpts = this.options.animationOptions,
-          _isInsertingAnimated = this._isInserting && this.isUsingJQueryAnimation,
           objStyleFn, processor,
           triggerCallbackNow, callbackFn;
 
@@ -622,36 +621,46 @@
         obj.$el[ styleFn ]( obj.style, animOpts );
       };
 
-      if ( this._isInserting || !callback ) {
+      if ( this._isInserting && this.isUsingJQueryAnimation ) {
-        // process styleQueue
+        // if using styleQueue to insert items
         processor = function( i, obj ) {
           // only animate if it not being inserted
-          objStyleFn = _isInsertingAnimated && obj.$el.hasClass('no-transition') ? 'css' : styleFn;
+          objStyleFn = obj.$el.hasClass('no-transition') ? 'css' : styleFn;
           obj.$el[ objStyleFn ]( obj.style, animOpts );
         };
         
-      } else {
+      } else if ( callback ) {
-        var isCallbackTriggered = false;
+        // has callback
+        var isCallbackTriggered = false,
+            instance = this;
+        triggerCallbackNow = true;
+        // trigger callback only once
         callbackFn = function() {
-          // trigger callback only once
           if ( isCallbackTriggered ) {
             return;
           }
-          callback( $elems );
+          callback.call( instance.element, $elems );
           isCallbackTriggered = true;
         };
         
-        if ( this.isUsingJQueryAnimation ) {
+        if ( this.isUsingJQueryAnimation && styleFn === 'animate' ) {
           // add callback to animation options
           animOpts.complete = callbackFn;
+          triggerCallbackNow = false;
+
         } else if ( Modernizr.csstransitions ) {
           // detect if first item has transition
           var i = 0,
-              testElem = this.styleQueue[0].$el;
+              testElem = this.styleQueue[0].$el,
+              styleObj;
           // get first non-empty jQ object
-          // console.log( this.styleQueue )
+          while ( !testElem.length ) {
-          if ( !testElem.length ) {
+            styleObj = this.styleQueue[ i++ ];
-            return;
+            // HACK: sometimes styleQueue[i] is undefined
+            if ( !styleObj ) {
+              return;
+            }
+            testElem = styleObj.$el;
           }
           // get transition duration of the first element in that object
           // yeah, this is inexact
@@ -662,9 +671,7 @@
                 // trigger callback at transition end
                 .one( transitionEndEvent, callbackFn );
             }
-          } else {
+            triggerCallbackNow = false;
-            // no transition? hit it now, son
-            triggerCallbackNow = true;
           }
         }
       }
@@ -777,11 +784,11 @@
       
     },
     
-    shuffle : function() {
+    shuffle : function( callback ) {
       this.updateSortData( this.$allAtoms );
       this.options.sortBy = 'random';
       this._sort();
-      this.reLayout();
+      this.reLayout( callback );
     },
     
     // destroys widget, returns elements and container back (close) to original style