JQueryMasonry < System

---+ %TOPIC%
%JQPLUGINS{"masonry"
  format="
    Homepage: $homepage <br />
    Author(s): $author <br />
    Version: $version
  "
}%

%STARTSECTION{"summary"}%
Masonry is a layout plugin for jQuery. Think of it as the flip side of CSS
floats. Whereas floating arranges elements horizontally then vertically,
Masonry arranges elements vertically then horizontally according to a grid. The
result minimizes vertical gaps between elements of varying height, just like a
mason fitting stones in a wall.
%ENDSECTION{"summary"}%

---++ Screenshot

<img src="%ATTACHURL%/jQuery-Masonry.jpg" alt="jQuery-Masonry.jpg" width="547" height="351" />

See the [[http://emberapp.com/desandro/collections/jquery-masonry][jQuery Masonry Collection on Ember]] for more screenshots
of jQuery masonry in the wild.

---++ Usage

---+++ <nop>JavaScript API

Configuring Masonry is fairly easy. Simply attach the =.masonry()= method 
to the wrapping container element in your jQuery script. Depending on the layout,
 you&#8217;ll most likely need to specify one option.

For layouts with elements that span multiple widths:

<verbatim class="js">
$('#wrapper').masonry({ columnWidth: 200 });
</verbatim>

For layouts with elements that span the same width:

<verbatim class="js">
$('#wrapper').masonry({ singleMode: true });
</verbatim>

---+++ Foswiki integration

All containers classified as =jqMasonry= will be processed by this plugin. Options can be specified
using JQueryMetadata.

---++ Options

   * animationOptions: {} %BR%
     A map of options for animation. See the [[http://api.jquery.com/animate/#animate-properties-options][jQuery API for animate options for details]].
   * columnWidth: 240 %BR%
     Width in pixels of 1 column of your grid.
     default: outer width of the first floated element.
   * gutterWidth: 0 %BR%
     Adds additional spacing between columns.
   * isAnimated: false %BR%
     Enables jQuery animation on layout changes.
   * isFitWidth : false %BR%
     If enabled, Masonry will size the width of the container to the nearest column. 
     When enabled, Masonry will measure the width of the container&#8217;s parent element, 
     not the width of the container. This option is ideal for centering Masonry layouts.
   * isResizeable: true %BR%
     Triggers layout logic when browser window is resized.
   * isRTL: false %BR%
     Enables right-to-left layout for languages like Hebrew and Arabic.
   * itemSelector: '.box:visible' %BR%
     Additional selector to specify which elements inside
     the wrapping element will be rearranged.

---++ Methods

Masonry offers several methods to extend functionality. Masonry&#8217;s methods follow the jQuery UI pattern.

<verbatim class="js">$('#container').masonry( 'methodName', [optionalParameters] )</verbatim>

---+++ appended 

<verbatim class="js">.masonry( 'appended', $content, isAnimatedFromBottom )</verbatim>

Triggers layout on item elements that have been appended to the container.

---+++ destroy

<verbatim class="js">.masonry( 'destroy' )</verbatim>

Removes Masonry functionality completely. Returns element back to pre-initialized state.

---+++ layout

<verbatim class="js">.masonry( 'layout', $items, callback )</verbatim>

Positions specified item elements in layout.

=layout= will only position specified elements, and those elements will be positioned at the end of layout. Whereas =.masonry()= will position all items in the Masonry instance.

---+++ option

<verbatim class="js">.masonry( 'option', options )</verbatim>

Sets options for plugin instance. Unlike passing options through .masonry(), using the option method will not trigger layout.

<verbatim class="js">
// set multiple options
.masonry( 'option', { columnWidth: 120, isAnimated: false } )
</verbatim>

---+++ reloadItems

<verbatim class="js">.masonry( 'reloadItems' )</verbatim>

Re-collects all item elements in their current order in the DOM.

---+++ reload

<verbatim class="js">.masonry( 'reload' )</verbatim>

Convenience method for triggering reloadItems then .masonry(). Useful for prepending or inserting items.

---+++ remove

<verbatim class="js">.masonry( 'remove', $items )</verbatim>

Removes specified item elements from Masonry instance and the DOM.

---++ Examples
%JQREQUIRE{"Masonry"}%

See more demos at http://masonry.desandro.com/

<div class="wrap jqMasonry {columnWidth:100, itemSelector:'.box'}">
  <div class="box">
    Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec odio.
    Quisque volutpat mattis eros. Nullam malesuada erat ut turpis. Suspendisse urna
    nibh, viverra non, semper suscipit, posuere a, pede.
  </div>

  <div class="box">
     Donec nec justo eget felis facilisis fermentum. Aliquam porttitor mauris
     sit amet orci.
  </div>

  <div class="box">
    Fusce accumsan mollis eros. Pellentesque a diam sit amet mi ullamcorper
    vehicula
  </div>

  <div class="box">
    Sit amet mi ullamcorper vehicula
  </div>

  <div class="box">
    adipiscing in, lacinia vel, tellus. Suspendisse ac urna. Etiam pellentesque
    mauris ut lectus.
  </div>

  <div class="box">
    Sit amet mi ullamcorper vehicula
  </div>

  <div class="box">
    Phasellus pede arcu, dapibus eu, fermentum et, dapibus sed, urna.
  </div>

  <div class="box">
    Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Donec odio.
    Quisque volutpat mattis eros. Nullam malesuada erat ut turpis. Suspendisse urna
    nibh, viverra non, semper suscipit, posuere a, pede.
  </div>

  <div class="box">
     Donec nec justo eget felis facilisis fermentum. Aliquam porttitor mauris
     sit amet orci.
  </div>

  <div class="box">
    Fusce accumsan mollis eros. Pellentesque a diam sit amet mi ullamcorper
    vehicula
  </div>

  <div class="box">
    Sit amet mi ullamcorper vehicula
  </div>

  <div class="box">
    adipiscing in, lacinia vel, tellus. Suspendisse ac urna. Etiam pellentesque
    mauris ut lectus.
  </div>

  <div class="box">
    Sit amet mi ullamcorper vehicula
  </div>

  <div class="box">
    Phasellus pede arcu, dapibus eu, fermentum et, dapibus sed, urna.
  </div>

  <br class="foswikiClear" />
</div>

<literal>
<style type="text/css">
.box {
    margin: 5px;
    padding: 5px;
    background: #D8D5D2;
    -moz-border-radius: 5px;
    -webkit-border-radius: 5px;
    border-radius: 5px;
    float: left;
    width:80px;
}
.wrap {
    padding: 10px;
    width:300px;
}
</style>
</literal>
This topic: System > JQueryPlugin > JQueryMasonry
Topic revision: 08 Sep 2011, ProjectContributor (raw view)
Copyright © by the contributing authors. All material on this site is the property of the contributing authors.
Ideas, requests, problems regarding Foswiki? Send feedback