From 0bdc013985a4b37ebe2b2084f23d68c851addb25 Mon Sep 17 00:00:00 2001
From: David DeSandro <david@desandro.com>
Date: Fri, 31 Dec 2010 10:26:34 -0500
Subject: [PATCH] docs : add Sorting doc

---
 _posts/docs/2010-12-03-options.mdown |   4 +
 _posts/docs/2010-12-07-sorting.mdown | 149 +++++++++++++++++++++++++++
 2 files changed, 153 insertions(+)
 create mode 100644 _posts/docs/2010-12-07-sorting.mdown

diff --git a/_posts/docs/2010-12-03-options.mdown b/_posts/docs/2010-12-03-options.mdown
index fc2440b..69ad420 100644
--- a/_posts/docs/2010-12-03-options.mdown
+++ b/_posts/docs/2010-12-03-options.mdown
@@ -178,6 +178,10 @@ The property name of the method within the `getSortData` option to sort item ele
 
 Looking at the `getSortData` example above, valid values would be `'symbol'`, `'number'`, or `'name'`.
 
+### Values {#sortBy-values}
+
++ `'original-order'` Sorts item elements by their original order.
+
 ## visibleStyle
 
 <dl class="clearfix">
diff --git a/_posts/docs/2010-12-07-sorting.mdown b/_posts/docs/2010-12-07-sorting.mdown
new file mode 100644
index 0000000..eb6b597
--- /dev/null
+++ b/_posts/docs/2010-12-07-sorting.mdown
@@ -0,0 +1,149 @@
+---
+
+title: Sorting
+category: docs
+layout: doc
+
+---
+
+Isotope can rearrange item elements via sorting.
+
+[**See Demo: Sorting**](../demos/sorting.html)
+
+## Markup
+
+In our example, each item element has several data points that can be used for sorting.
+
+
+{% highlight html %}
+
+<div id="demo">
+  <div class="element transition metal" data-category="transition"> 
+    <p class="number">79</p> 
+    <h3 class="symbol">Au</h3> 
+    <h2 class="name">Gold</h2> 
+    <p class="weight">196.966569</p> 
+  </div> 
+    
+  <div class="element metalloid" data-category="metalloid"> 
+    <p class="number">51</p> 
+    <h3 class="symbol">Sb</h3> 
+    <h2 class="name">Antimony</h2> 
+    <p class="weight">121.76</p> 
+  </div>
+</div>
+
+{% endhighlight %}
+
+There's the elemental symbol, number, name of the element, weight, and category.
+
+## getSortData
+
+In order to extract this data from the element, we need to pass in a function to get it via the `getSortData` option.  This option accepts an object, whose values are the functions to extract the data.
+
+Each function receives one argument, which represents a jQuery object for each item element. With that argument, the function needs to return the data point.
+
+In the example above, to get element name, we would need to get the text from the `.name` element. The same works for symbol.
+
+{% highlight javascript %}
+
+$('#demo').isotope({
+  getSortData : {
+    name : function ( $elem ) {
+      return $elem.find('.name').text();
+    },
+    symbol : function ( $elem ) {
+      return $elem.find('.symbol').text();
+    }
+  }
+});
+
+{% endhighlight %}
+
+
+For numerical data, we can convert a text value into a number via `parseInt()` function.
+
+{% highlight javascript %}
+
+getSortData : {
+  // ...
+  number : function ( $elem ) {
+    return parseInt( $elem.find('.name').text(), 10 );
+  },
+  weight : function ( $elem ) {
+    return parseInt( $elem.find('.weight').text(), 10 );
+  }
+}
+
+{% endhighlight %}
+
+The data extracted can be anything accessible in the item element via jQuery. To extract the category data, we can use the `.attr()`.
+
+{% highlight javascript %}
+
+getSortData : {
+  // ...
+  category : function ( $elem ) {
+    return $elem.attr('data-category');
+  }
+}
+
+{% endhighlight %}
+
+## sortBy
+
+For every method set in `getSortData`, Isotope uses that method to build the data for sorting. The data cache is built on initialization so it can be quickly accessed when sorting. With the methods above, we have built data for an item elements name, symbol, number, weight and category.
+
+Sorting elements is done with the `sortBy` option. The value needs to match the property name used in the `getSortData` object.
+
+With our example, we can use `'name'`, `'symbol'`, `'number'`, `'weight'` and `'category'`.
+
+{% highlight javascript %}
+
+$('#demo').isotope({ sortBy : 'symbol' });
+
+{% endhighlight %}
+
+There is an additional sorting data built in to Isotope `'original-order'`. Sorting with `'original-order'` will use the original order of the item elements to arrange them in the layout.
+
+## sortAscending
+
+By default, Isotope sorts data in ascension. If our data for name is "Gold, Antimony, Lead, Iron, Silver", when sorted by name, the elements will be ordered ABC.. : "Antimony, Gold, Iron, Lead, Silver."  To reverse the order and sort data in descension, set the `sortAscending` option to `false`.
+
+{% highlight javascript %}
+
+$('#demo').isotope({ 
+  sortBy : 'name',
+  sortAscending : false
+});
+
+{% endhighlight %}
+
+## Buttons
+
+We can use a simple list for our buttons.
+
+{% highlight html %}
+
+<ul id="sort">
+  <li><a href="#name">name</a></li>
+  <li><a href="#symbol">symbol</a></li>
+  <li><a href="#number">number</a></li>
+  <li><a href="#weight">weight</a></li>
+  <li><a href="#category">category</a></li>
+</ul>
+
+{% endhighlight %}
+
+When one of these links is clicked, we can use the `href` attribute as the value for `sortBy` in the Isotope script.
+
+{% highlight javascript %}
+
+$('#sort a').click(function(){
+  // get href attribute, minus the '#'
+  var sortName = $(this).attr('href').slice(1);
+  $('#demo').isotope({ sortBy : sortName });
+  return false;
+});
+
+{% endhighlight %}