<h2>Usage<a href="#usage"></a></h2>

<h3>The HTML Structure</h3>
<p>The only real important thing here is the <code class="language-markup token attr-name">data-groups</code> attribute. It has to be a <a href="http://jsonlint.com/">valid JSON</a> array of strings. Optionally, it can be a string delimeted by a value you provide. See <code>delimeter</code> in the <a href="#options">options</a>.</p>

<p>This example is using this site's grid. Each item would be 4 columns at the "sm" breakpoint (768px).</p>

<h3>Images</h3>
<p>To see why the images are wrapped in <code>.aspect</code> elements, check out the <a href="{{ site.baseurl }}{% post_url 2013-05-03-images %}">images demo</a>.</p>

<div class="code-block">
  <pre rel="HTML"><code class="language-markup">&lt;div id="grid" class="row my-shuffle-container"&gt;
  &lt;figure class="col-4@sm picture-item" data-groups='[&quot;photography&quot;]' data-date-created="2010-09-14" data-title="Baseball"&gt;
    &lt;div class="aspect aspect--16x9"&gt;
      &lt;div class="aspect__inner"&gt;
        &lt;img src="/img/baseball.png" alt="" height="145" width="230"&gt;
      &lt;/div&gt;
    &lt;/div&gt;
    &lt;figcaption&gt;Baseball&lt;/figcaption&gt;
  &lt;/figure&gt;
  &lt;figure class="col-4@sm picture-item" data-groups='[&quot;wallpaper&quot;,&quot;3d&quot;]' data-date-created="2011-08-14" data-title="Tennis"&gt;
    &lt;div class="aspect aspect--16x9"&gt;
      &lt;div class="aspect__inner"&gt;
        &lt;img src="/img/tennis-ball.png" alt="" height="145" width="230"&gt;
      &lt;/div&gt;
    &lt;/div&gt;
    &lt;figcaption&gt;Tennis&lt;/figcaption&gt;
  &lt;/figure&gt;
  &lt;figure class="col-4@sm picture-item" data-groups='[&quot;wallpaper&quot;,&quot;3d&quot;]' data-date-created="2009-05-27" data-title="iMac"&gt;
    &lt;div class="aspect aspect--16x9"&gt;
      &lt;div class="aspect__inner"&gt;
        &lt;img src="/img/imac.png" alt="" height="145" width="230"&gt;
      &lt;/div&gt;
    &lt;/div&gt;
    &lt;figcaption&gt;iMac&lt;/figcaption&gt;
  &lt;/figure&gt;
  &lt;div class="col-1@sm my-sizer-element"&gt;&lt;/div&gt;
&lt;/div&gt;</code></pre>
</div>

<h3 id="columns">How column widths work<a href="#how-column-widths-work"></a></h3>
<p>There are 4 options for defining the width of the columns:</p>
<ol>
  <li>Use a <strong>sizer</strong> element. This is the easiest way to specify column and gutter widths. Add the sizer element and make it 1 column wide. Shuffle will measure the <code>width</code> and <code>margin-left</code> of this <code>sizer</code> element each time the grid resizes. This is awesome for responsive or fluid grids where the width of a column is a percentage.</li>
  <li>Use a <strong>function</strong>. When a function is used, its first parameter will be the width of the shuffle element. You need to return the column width for shuffle to use (in pixels).</li>
  <li>A <strong>number</strong>. This will explicitly set the column width to your number (in pixels).</li>
  <li>By default, shuffle will use the width of the first item to calculate the column width.</li>
</ol>

<h3>A basic setup example</h3>
<p>If you want functional buttons, check out <a href="{{ site.baseurl }}/js/demos/homepage.js">the js file</a>.</p>
<p>Shuffle uses a UMD definition so that you can use it with globals, AMD, or CommonJS.</p>
<div class="code-block">
  <pre rel="JavaScript"><code class="language-javascript">var Shuffle = window.shuffle;
var element = document.getElementById('grid');
var sizer = element.querySelector('.my-sizer-element');

var shuffle = new Shuffle(element, {
  itemSelector: '.picture-item',
  sizer: sizer // could also be a selector: '.my-sizer-element'
});</code></pre>
</div>
