Add "Filters" section.

README.md

@@ -14,7 +14,7 @@ npm install shufflejs
 ```js
 import Shuffle from 'shufflejs';
 
-const myShuffle = new Shuffle(document.getElementById('grid'), {
+const shuffleInstance = new Shuffle(document.getElementById('grid'), {
   itemSelector: '.js-item',
   sizer: '.js-shuffle-sizer'
 });

docs/_includes/advanced-filters.html

@@ -1,11 +1,11 @@
-<h2>Advanced Filtering<a href="#advanced-filters"></a></h2>
+<h2>Advanced Filters<a href="#advanced-filters"></a></h2>
 
 <p>By passing a function to <code>filter</code>, you can fully customize filtering items. Shuffle will iterate over each item and give your function the element and the shuffle instance. Return <code>true</code> to keep the element or <code>false</code> to hide it.</p>
 
 <h3>Example</h3>
 <div class="code-block">
   <pre rel="JavaScript"><code class="language-javascript">// Filters elements with a data-title attribute with less than 10 characters
-instance.filter(function (element) {
+shuffleInstance.filter(function (element) {
   return element.getAttribute('data-title').length &lt; 10;
 });</code></pre>
 </div>

docs/_includes/events.html

@@ -3,7 +3,7 @@
 
 <h3>Get notified when a layout happens</h3>
 <div class="code-block">
-  <pre rel="JavaScript"><code class="language-javascript">myShuffleInstance.on(Shuffle.EventType.LAYOUT, function () {
+  <pre rel="JavaScript"><code class="language-javascript">shuffleInstance.on(Shuffle.EventType.LAYOUT, function () {
   console.log('Things finished moving!');
 });</code></pre>
 </div>
@@ -11,7 +11,7 @@
 
 <h3>Do something when an item is removed</h3>
 <div class="code-block">
-  <pre rel="JavaScript"><code class="language-javascript">myShuffleInstance.on(Shuffle.EventType.REMOVED, function (data) {
+  <pre rel="JavaScript"><code class="language-javascript">shuffleInstance.on(Shuffle.EventType.REMOVED, function (data) {
   console.log(this, data, data.collection, data.shuffle);
 });</code></pre>
 </div>

docs/_includes/filters.html

@@ -0,0 +1,45 @@
+<h2>Filters<a href="#filters"></a></h2>
+
+<h3>Filter by a group</h3>
+<p>Use the <code>filter()</code> method. If, for example, you wanted to show only items that match <code>"space"</code>, you would do this:</p>
+
+<div class="code-block">
+  <pre rel="JavaScript"><code class="language-javascript">shuffleInstance.filter('space');</code></pre>
+</div>
+
+<h3>Filter by multiple groups</h3>
+<p>Show multiple groups at once by using an array.</p>
+
+<div class="code-block">
+  <pre rel="JavaScript"><code class="language-javascript">shuffleInstance.filter(['space', 'nature']);</code></pre>
+</div>
+
+<p>By default, this will show items that match <code>space</code> <em>or</em> <code>nature</code>. To show only groups that match <code>space</code> <em>and</em> <code>nature</code>, set the <code>filterMode</code> option to <code>Shuffle.FilterMode.ALL</code>.</p>
+
+<h3>Show all items</h3>
+<p>To go back to having no items filtered, you can call <code>filter()</code> without a parameter, or use <code>Shuffle.ALL_ITEMS</code> (which by default is the string <code>"all"</code>).</p>
+
+<div class="code-block">
+  <pre rel="JavaScript"><code class="language-javascript">shuffleInstance.filter(Shuffle.ALL_ITEMS); // or .filter()</code></pre>
+</div>
+
+<h3>Filter and sort</h3>
+<p>You can filter and sort at the same time by passing a <a href="#sorting">sort object</a> as the second parameter.</p>
+
+<div class="code-block">
+  <pre rel="JavaScript"><code class="language-javascript">shuffleInstance.filter('space', {
+  by: function (element) {
+    return element.getAttribute('data-title').toLowerCase();
+  },
+});</code></pre>
+</div>
+
+<h3>Overrides</h3>
+<p>You can override both <code>Shuffle.ALL_ITEMS</code> and <code>Shuffle.FILTER_ATTRIBUTE_KEY</code> if you want.</p>
+
+<div class="code-block">
+  <pre rel="JavaScript"><code class="language-javascript">Shuffle.ALL_ITEMS = 'any';
+Shuffle.FILTER_ATTRIBUTE_KEY = 'categories';</code></pre>
+</div>
+
+<p>Then you would have to use <code>data-categories</code> attribute on your items instead of <code>data-groups</code>.</p>

docs/_includes/nav.html

@@ -24,9 +24,10 @@
                 <li><a href="{{ site.baseurl }}/#features">Features</a></li>
                 <li><a href="{{ site.baseurl }}/#options">Options</a></li>
                 <li><a href="{{ site.baseurl }}/#usage">Usage</a></li>
-                <li><a href="{{ site.baseurl }}/#events">Events</a></li>
+                <li><a href="{{ site.baseurl }}/#filters">Filters</a></li>
+                <li><a href="{{ site.baseurl }}/#advanced-filters">Advanced Filters</a></li>
                 <li><a href="{{ site.baseurl }}/#sorting">Sorting</a></li>
-                <li><a href="{{ site.baseurl }}/#advanced-filtering">Advanced Filtering</a></li>
+                <li><a href="{{ site.baseurl }}/#events">Events</a></li>
                 <li><a href="{{ site.baseurl }}/#adding-removing">Adding and Removing Items</a></li>
                 <li><a href="{{ site.baseurl }}/#public-methods">Public Methods</a></li>
                 <li><a href="{{ site.baseurl }}/#custom-styles">Custom Styles</a></li>

docs/_includes/usage.html

@@ -55,7 +55,7 @@
 var element = document.querySelector('.my-shuffle-container');
 var sizer = element.querySelector('.my-sizer-element');
 
-var shuffle = new Shuffle(element, {
+var shuffleInstance = new Shuffle(element, {
   itemSelector: '.picture-item',
   sizer: sizer // could also be a selector: '.my-sizer-element'
 });</code></pre>

docs/_posts/2013-05-03-images.html

@@ -15,7 +15,7 @@ prism: true
       <ol>
         <li>Set an explicit height on <code>.shuffle-item</code>s like the <a href="{{ site.baseurl }}{% post_url 2013-05-01-basic %}">basic demo</a>.</li>
         <li>Similar to number 1, make the height of the image container a percentage of the width. If you know the aspect ratio of the images you're using, this is the technique you should use. This demo uses that technique.</li>
-        <li>Get notified when images load and call <code>myShuffleInstance.layout()</code>. I recommend using <a href="http://desandro.github.io/imagesloaded/">Desandro's images loaded plugin</a> to know when your images have finished loading.</li>
+        <li>Get notified when images load and call <code>shuffleInstance.layout()</code>. I recommend using <a href="http://desandro.github.io/imagesloaded/">Desandro's images loaded plugin</a> to know when your images have finished loading.</li>
         <li>Do nothing and let your shuffle instance call <code>layout()</code> on the <code>window</code>'s <code>load</code> event. This will the item layout to change on page load.</li>
       </ol>
     </div>

docs/_posts/2017-06-29-shuffle-with-react.html

@@ -54,7 +54,7 @@ prism: true
     <div class="col-12@sm">
       <h2>Shuffle with React</h2>
       <p>And other view-based libraries like Vue and Preact.</p>
-      <p>The simplest way is to use <code>myShuffleInstance.resetItems();</code> inside the <code>componentDidUpdate()</code>        lifecycle method.</p>
+      <p>The simplest way is to use <code>shuffleInstance.resetItems();</code> inside the <code>componentDidUpdate()</code>        lifecycle method.</p>
     </div>
   </div>
 </div>

docs/index.html

@@ -115,11 +115,21 @@ prism: true
   </div>
 </section>
 
-<section id="events">
+<section id="filters">
   <div class="container">
     <div class="row">
       <div class="col-12@sm">
-        {% include events.html %}
+        {% include filters.html %}
+      </div>
+    </div>
+  </div>
+</section>
+
+<section id="advanced-filters">
+  <div class="container">
+    <div class="row">
+      <div class="col-12@sm">
+        {% include advanced-filters.html %}
       </div>
     </div>
   </div>
@@ -135,11 +145,11 @@ prism: true
   </div>
 </section>
 
-<section id="advanced-filters">
+<section id="events">
   <div class="container">
     <div class="row">
       <div class="col-12@sm">
-        {% include advanced-filters.html %}
+        {% include events.html %}
       </div>
     </div>
   </div>

docs/js/demos/images.js

@@ -1,6 +1,6 @@
 var Shuffle = window.Shuffle;
 
-window.myShuffle = new Shuffle(document.querySelector('.my-grid-with-images'), {
+window.shuffleInstance = new Shuffle(document.querySelector('.my-grid-with-images'), {
   itemSelector: '.js-item',
   sizer: '.my-sizer-element',
 });

docs/js/require-main.js

@@ -14,7 +14,7 @@ requirejs.config({
 });
 
 requirejs(['shufflejs'], function (Shuffle) {
-  window.myShuffle = new Shuffle(document.getElementById('grid'), {
+  window.shuffleInstance = new Shuffle(document.getElementById('grid'), {
     itemSelector: '.js-item',
     sizer: document.getElementById('js-sizer'),
   });

docs/js/site-nav.js

@@ -41,7 +41,6 @@
   SiteNav.prototype.handleResize = function () {
     var viewportHeight = window.innerHeight;
     var navHeight = this.element.offsetHeight;
-    console.log(`viewportHeight: ${viewportHeight}\nnavHeight: ${navHeight}`);
     var dropdowns = Array.from(document.querySelectorAll('.site-nav__dropdown'));
     dropdowns.forEach(function (dropdown) {
       dropdown.style.maxHeight = (viewportHeight - navHeight) + 'px';