<p>Shuffle emits an event when a layout happens and when elements are removed. The event names are <codeclass="language-javascript">Shuffle.EventType.LAYOUT</code> and <codeclass="language-javascript">Shuffle.EventType.REMOVED</code>.</p>
<p>Shuffle uses the global <code>CustomEvent</code> to <ahref="https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent">create events</a>. A polyfill for IE<=11 is bundled with Shuffle.</p>
<h3>Get notified when shuffle is done with setup</h3>
easing: 'ease-out', // CSS easing function to use.
itemSelector: '', // e.g. '.picture-item'.
sizer: null, // Sizer element. Use an element to determine the size of columns and gutters.
easing: 'ease', // CSS easing function to use.
itemSelector: '*', // e.g. '.picture-item'.
sizer: null, // Element or selector string. Use an element to determine the size of columns and gutters.
gutterWidth: 0, // A static number or function that tells the plugin how wide the gutters between columns are (in pixels).
columnWidth: 0, // A static number or function that returns a number which tells the plugin how wide the columns are (in pixels).
delimeter: null, // If your group is not json, and is comma delimeted, you could set delimeter to ','.
buffer: 0, // Useful for percentage based heights when they might not always be exactly the same (in pixels).
columnThreshold: HAS_COMPUTED_STYLE ? 0.01 : 0.1, // Reading the width of elements isn't precise enough and can cause columns to jump between values.
columnThreshold: 0.01, // Reading the width of elements isn't precise enough and can cause columns to jump between values.
initialSort: null, // Shuffle can be initialized with a sort object. It is the same object given to the sort method.
throttle: throttle, // By default, shuffle will throttle resize events. This can be changed or removed.
throttleTime: 300, // How often shuffle can be called on resize (in milliseconds).
sequentialFadeDelay: 150, // Delay between each item that fades in when adding items.
supported: CAN_TRANSITION_TRANSFORMS // Whether to use transforms or absolute positioning.
staggerAmount: 15, // Transition delay offset for each item in milliseconds.
staggerAmountMax: 250, // Maximum stagger delay in milliseconds.
useTransforms: true, // Whether to use transforms or absolute positioning.
};</code></pre>
</div>
<p>No options <em>need</em> to be specified, but <code>itemSelector</code> should be used. Other common options to change are <code>speed</code>,<code>easing</code>, <code>gutterWidth</code>, and <code>columnWidth</code> (or<code>sizer</code>).</p>
<p>No options <em>need</em> to be specified, but <code>itemSelector</code> should be used. Other common options to change are <code>speed</code> and <code>sizer</code>.</p>
<p>The only real important thing here is the <codeclass="language-markup token attr-name">data-groups</code> attribute. It has to be a <ahref="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 <ahref="#options">options</a>.</p>
<p>In this example, shuffle is using the fluid grid from the <ahref="http://twitter.github.io/bootstrap/">Twitter Bootstrap v2.3</a>. It's also making use of <ahref="http://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/"><abbrtitle="Block-Element-Modifier">BEM</abbr></a> class naming.</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 <ahref="{{ site.baseurl }}{% post_url 2013-05-03-images %}">images demo</a>.</p>
<p>The<code>columnWidth</code> option is used to calculate the column width. You have several options:</p>
<p>There are 4 options for defining the width of the columns:</p>
<ol>
<li>Use a <strong>sizer</strong> element. This is the easest way to specify column and gutter widths. You can use an element or an element wrapped in jQuery to define the column width and gutter width. 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. The <code>sizer</code> option is an alias for <code>columnWidth</code>.<spanclass="demo-link-container">See <ahref="{{ site.baseurl }}{% post_url 2013-05-01-basic %}">a demo</a> using a sizer element or <ahref="{{ site.baseurl }}/js/demos/homepage.js">look at the js file</a> for the sizer demo.</span></li>
<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>
@ -51,14 +49,14 @@
<h3>A basic setup example</h3>
<p>If you want functional buttons, check out <ahref="{{ 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>
<p>You can encounter problems when shuffle item dimensions depend on images. <ahref="{{ site.baseurl }}{% post_url 2013-06-29-image-problems %}">Like this demo</a>. There are three good solutions to this.</p>
<ol>
<li>Set an explicit height on <code>.shuffle-item</code>s like the <ahref="{{ 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 this technique.</li>
<li>Get notified when images load and call <code>myShuffleInstance.layout()</code>. I recommend using <ahref="http://desandro.github.io/imagesloaded/">Desandro's images loaded plugin</a> to know when your images have finished loading.</li>
</ol>
<divclass="row">
<divclass="col-12@sm">
<h2>Using images with Shuffle</h2>
<p>You can encounter problems when shuffle item dimensions depend on images. <ahref="{{ site.baseurl }}{% post_url 2013-06-29-image-problems %}">Like this demo</a>. There are three good solutions to this.</p>
<ol>
<li>Set an explicit height on <code>.shuffle-item</code>s like the <ahref="{{ 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 this technique.</li>
<li>Get notified when images load and call <code>myShuffleInstance.layout()</code>. I recommend using <ahref="http://desandro.github.io/imagesloaded/">Desandro's images loaded plugin</a> to know when your images have finished loading.</li>
<p>In this demo, the height of each item in the grid depends on the image. If Shuffle is initialized before the images load, the heights it calculates will be incorrect. <ahref="{{ site.baseurl }}{% post_url 2013-05-03-images %}">See here</a> for a solution.</p>
<p>Resize the window and it'll fix itself.</p>
<divclass="row">
<divclass="col-12@sm">
<h2>This probably looks broken.</h2>
<p>In this demo, the height of each item in the grid depends on the image. If Shuffle is initialized before the images load, the heights it calculates will be incorrect. <ahref="{{ site.baseurl }}{% post_url 2013-05-03-images %}">See here</a> for a solution.</p>
Shuffle uses a UMD wrapper, so it is compatible with AMD loaders like <ahref="http://requirejs.org">RequireJS</a>. The UMD wrapper also allows Shuffle to work with CommonJS modules. You can take a peek at the <ahref="{{ site.baseurl }}/js/require-main.js">config file</a> used on this page.
</p>
<divclass="row">
<divclass="col-12@sm">
<h2>RequireJS!</h2>
<p>
Shuffle uses a UMD wrapper, so it is compatible with AMD loaders like <ahref="http://requirejs.org">RequireJS</a>. The UMD wrapper also allows Shuffle to work with CommonJS modules. You can take a peek at the <ahref="{{ site.baseurl }}/js/require-main.js">config file</a> used on this page.
<p>Shuffle assumes <code>Promise</code> is available globally. If you care about IE11, use a <ahref="https://github.com/stefanpenner/es6-promise">polyfill</a>. <ahref="http://caniuse.com/#feat=promises">Current support</a>.</p>
<p>Shuffle's <ahref="{{ site.baseurl }}/package.json">other dependencies</a> are bundled with the dist file.</p>
Glen Cheney
8 years ago