Mercutio is a layout plugin for jQuery. Think of it as the flip side of CSS floats. Whereas floating arranges elements horizontally then vertically, Mercutio 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.
Molequul is a layout plugin for jQuery. Think of it as the flip side of CSS floats. Whereas floating arranges elements horizontally then vertically, Molequul 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.
The primer in docs/index.html has all the documentation to get you started.
<p>Alternatively, you can rely on CSS3 transitions to animate layout rearrangements. CSS transitions are supported by Firefox 4, Chrome 5, Safari 4, and Opera 10.5.</p>
<p> In your script, leave out the <code>animate</code> option. </p>
<p>In the CSS, add transition properties. Mercutio will add a class of <code>masoned</code> to the container after the first arrangement so transitions can be applied afterward.</p>
<p>In the CSS, add transition properties. Molequul will add a class of <code>masoned</code> to the container after the first arrangement so transitions can be applied afterward.</p>
<p>Animation options are set with <code>animationOptions</code>. See the <ahref="http://api.jquery.com/animate/#animate-properties-options">jQuery API for animate options</a> for details on available animation options.</p>
<p>New elements can be appended to ‘masoned’ containers and then arranged to the layout using the <code>appendedContent</code> option. <code>appendedContent</code> accepts the a jQuery object of the newly appended elements. In this example, each time <ahref="#append_new_bricks">the button</a> is clicked, new <code>box</code> elements are created and then together made into a jQuery object. This object is first appended to the wrapping container, then the boxes are rearranged with a <code>.mercutio()</code> call. Finally, using the callback function, the new boxes are dynamically styled. </p>
<p>In the click function, <code>appendedContent</code> was the only option to specify in the mercutio configuration since Mercutio saves all previous options. Using <code>appendedContent</code>, the Mercutio script saves some processing time as it only rearranges the box(es) inside that appended container.</p>
<p>New elements can be appended to ‘masoned’ containers and then arranged to the layout using the <code>appendedContent</code> option. <code>appendedContent</code> accepts the a jQuery object of the newly appended elements. In this example, each time <ahref="#append_new_bricks">the button</a> is clicked, new <code>box</code> elements are created and then together made into a jQuery object. This object is first appended to the wrapping container, then the boxes are rearranged with a <code>.molequul()</code> call. Finally, using the callback function, the new boxes are dynamically styled. </p>
<p>In the click function, <code>appendedContent</code> was the only option to specify in the molequul configuration since Molequul saves all previous options. Using <code>appendedContent</code>, the Molequul script saves some processing time as it only rearranges the box(es) inside that appended container.</p>
<p>This example demonstrates the basic effect of jQuery Mercutio. All ‘bricks’ have outerWidths (width + padding + border + margin) that are multiples of 100 pixels. <code>columnWidth</code> is set to <code>100</code>.</p>
<p>This example demonstrates the basic effect of jQuery Molequul. All ‘bricks’ have outerWidths (width + padding + border + margin) that are multiples of 100 pixels. <code>columnWidth</code> is set to <code>100</code>.</p>
<p>This example demonstrates the basic effect of jQuery Mercutio. All ‘bricks’ have the same width, so <code>singleMode</code> is set to <code>true</code>.</p>
<p>This example demonstrates the basic effect of jQuery Molequul. All ‘bricks’ have the same width, so <code>singleMode</code> is set to <code>true</code>.</p>
<p>Filtering is supported by Mercutio since v1.2. This example demonstrates how to show, hide, and rearrange visible items, using some basic logic. Each control button has a class that matches a class of arrangeable elements: <code>gray</code>, <code>red</code>, and <code>black</code>. When one of these buttons is clicked, the arrangeable elements that have a matching class are shown, and the elements that do not match are hidden. To keep track of what's visible, a class of <code>invis</code> is added and removed to each element. In this example, the mercutio settings have <code>itemSelector</code> as <code><spanclass="string">'.box:not(.invis)'</span></code>, so only visible elements will be arranged in the layout. After the proper elements are hidden and the others shown, <code>.mercutio()</code> is called and the layout is rearranged.</p>
<p>Filtering is supported by Molequul since v1.2. This example demonstrates how to show, hide, and rearrange visible items, using some basic logic. Each control button has a class that matches a class of arrangeable elements: <code>gray</code>, <code>red</code>, and <code>black</code>. When one of these buttons is clicked, the arrangeable elements that have a matching class are shown, and the elements that do not match are hidden. To keep track of what's visible, a class of <code>invis</code> is added and removed to each element. In this example, the molequul settings have <code>itemSelector</code> as <code><spanclass="string">'.box:not(.invis)'</span></code>, so only visible elements will be arranged in the layout. After the proper elements are hidden and the others shown, <code>.molequul()</code> is called and the layout is rearranged.</p>
<p>Mercutio is a layout plugin for jQuery. Think of it as the flip side of CSS floats. Whereas floating arranges elements horizontally then vertically, Mercutio 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.</p>
<p>Molequul is a layout plugin for jQuery. Think of it as the flip side of CSS floats. Whereas floating arranges elements horizontally then vertically, Molequul 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.</p>
<p>Configuring Mercutio is fairly easy. Simply call the <code>.mercutio()</code> method on the container element. Depending on the layout, you’ll most likely need to specify one option.</p>
<p>Configuring Molequul is fairly easy. Simply call the <code>.molequul()</code> method on the container element. Depending on the layout, you’ll most likely need to specify one option.</p>
<p>For layouts with elements that span multiple widths, like the <ahref="basic-multi-column.html">basic multi-column example</a>:</p>
<p>No need to worry about how many columns, or width of gutters, or how big the container is. Thanks to the wonders of jQuery’s <code>outerWidth()</code> and <code>innerWidth()</code> methods, Mercutio appropriately accounts for the space of any margin, padding, and border-width set with CSS.</p>
<p>No need to worry about how many columns, or width of gutters, or how big the container is. Thanks to the wonders of jQuery’s <code>outerWidth()</code> and <code>innerWidth()</code> methods, Molequul appropriately accounts for the space of any margin, padding, and border-width set with CSS.</p>
<p>This plugin is designed to progressively enhance the layout, so ‘brick’ elements should be floated if JavaScript is disabled. Floating also ensures that the bricks width will be measured correctly.</p>
<spanclass="comment">// Disables measuring the width of each floated element.
@ -224,7 +224,7 @@
// Required for Infinite Scroll with window resizing.</span>
resizeable: <spanclass="constant">true</span>,
<spanclass="comment">// Binds a Mercutio call to window resizes
<spanclass="comment">// Binds a Molequul call to window resizes
// so layout appears fluid.
// default: true</span>
@ -240,44 +240,44 @@
// Useful for Infinite Scroll integration.</span>
saveOptions: <spanclass="constant">true</span>,
<spanclass="comment">// Mercutio will use the options from previous Mercutio
<spanclass="comment">// Molequul will use the options from previous Molequul
// calls by default, so you only have to enter in options once
// default: true</span>
}, <spanclass="storage">function</span>() {}
<spanclass="comment">// Optional callback.
// 'this' will refer to the applicable elements Mercutio just rearranged</span>
// 'this' will refer to the applicable elements Molequul just rearranged</span>
);</code></pre>
<h2id="code-repository">Code repository</h2>
<p>This project lives on GitHub at <ahref="http://github.com/desandro/mercutio">github.com/desandro/mercutio</a>, where you can follow progress, download all this documentation, grab the latest version of the script, or fork this project and make it better yourself.</p>
<p>This project lives on GitHub at <ahref="http://github.com/desandro/molequul">github.com/desandro/molequul</a>, where you can follow progress, download all this documentation, grab the latest version of the script, or fork this project and make it better yourself.</p>
<p>There you can find an <ahref="http://github.com/desandro/mercutio/issues">issue tracker</a> where you can look through other people’s <ahref="http://github.com/desandro/mercutio/issues/closed">resolved issues</a> or submit a new one for yourself. If you’re still having trouble, try <ahref="http://wiki.github.com/desandro/mercutio/">looking over the FAQ</a>.</p>
<p>There you can find an <ahref="http://github.com/desandro/molequul/issues">issue tracker</a> where you can look through other people’s <ahref="http://github.com/desandro/molequul/issues/closed">resolved issues</a> or submit a new one for yourself. If you’re still having trouble, try <ahref="http://wiki.github.com/desandro/molequul/">looking over the FAQ</a>.</p>
<h2id="resizing">Window resizing</h2>
<p>By default, Mercutio binds a call to the browser window for resizing. But the rearrangement script is triggered only when the layout adds or loses a column, so you don’t have to worry about Mercutio slowing down window resizes, or with fixed layouts.</p>
<p>By default, Molequul binds a call to the browser window for resizing. But the rearrangement script is triggered only when the layout adds or loses a column, so you don’t have to worry about Molequul slowing down window resizes, or with fixed layouts.</p>
<h2id="images">Handling images & other media</h2>
<p>Since Mercutio measures the height of the elements when placing them, you will need to account for images and other media that haven’t loaded yet. For images, the best method is to specify the width and height of images inline.</p>
<p>Since Molequul measures the height of the elements when placing them, you will need to account for images and other media that haven’t loaded yet. For images, the best method is to specify the width and height of images inline.</p>
<p>If you’re using a PHP-based CMS, you can use the <ahref="http://php.net/manual/en/function.getimagesize.php">getimagesize</a> function.</p>
<p>If this is not possible or if you’re dealing with @font-face fonts, another option is to call Mercutio after all media has loaded. This is done by calling the function inside of <code>$(window).load()</code> instead of <code>$(document).ready()</code>.</p>
<p>If this is not possible or if you’re dealing with @font-face fonts, another option is to call Molequul after all media has loaded. This is done by calling the function inside of <code>$(window).load()</code> instead of <code>$(document).ready()</code>.</p>
<p>Since Mercutio relies on absolute positioning, any anchor links that occur within or after the wrapping element will not work when the page first loads. The following script is one solution.</p>
<p>Since Molequul relies on absolute positioning, any anchor links that occur within or after the wrapping element will not work when the page first loads. The following script is one solution.</p>
<p>In addition to the examples below, see <ahref="http://delicious.com/desandro/jquerymercutio">delicious links tagged with jquerymercutio</a> and <ahref="http://emberapp.com/desandro/collections/jquery-mercutio">jQuery Mercutio Collection on Ember for screenshots</a>.</p>
<p>In addition to the examples below, see <ahref="http://delicious.com/desandro/jquerymolequul">delicious links tagged with jquerymolequul</a> and <ahref="http://emberapp.com/desandro/collections/jquery-molequul">jQuery Molequul Collection on Ember for screenshots</a>.</p>
<ul>
@ -335,12 +335,12 @@
<ul>
<li><ahref="http://paulirish.com">Paul Irish</a> for his <ahref="http://www.infinite-scroll.com">Infinite Scroll</a> plugin, which served as a template I used to produce a plugin of my own. The <code>appendedContent</code> option was design to work specifically with Infinite Scroll. Infinite Scroll is packaged with these docs.</li>
<p>jQuery Mercutio is licensed under the MIT license, just like <ahref="http://jquery.org/license">jQuery itself.</a> It may be used for personal and commercial applications.</p>
<p>jQuery Molequul is licensed under the MIT license, just like <ahref="http://jquery.org/license">jQuery itself.</a> It may be used for personal and commercial applications.</p>
<divclass="license-copy">
<h3>The MIT License</h3>
@ -358,17 +358,17 @@
</div><!-- .copy -->
<pid="footer">
jQuery Mercutio by <ahref="http://desandro.com/">David DeSandro</a>
jQuery Molequul by <ahref="http://desandro.com/">David DeSandro</a>
<p>Mercutio integrates well with auto-paging scripts like <ahref="http://www.infinite-scroll.com/">Infinite Scroll</a> by <ahref="http://paulirish.com">Paul Irish</a>. Using the <code>appendedContent</code> option, Mercutio will only re-position the newly appended elements, and skip over all the previous elements that are already in their proper position, thus saving precious milliseconds of page load time.</p>
<p>Molequul integrates well with auto-paging scripts like <ahref="http://www.infinite-scroll.com/">Infinite Scroll</a> by <ahref="http://paulirish.com">Paul Irish</a>. Using the <code>appendedContent</code> option, Molequul will only re-position the newly appended elements, and skip over all the previous elements that are already in their proper position, thus saving precious milliseconds of page load time.</p>
<p>Setting up the Mercutio call is just the same as normally would be. Since this layout uses both Infinite Scroll and resizable, <code>itemSelector</code> is recommended.</p>
<p>Setting up the Molequul call is just the same as normally would be. Since this layout uses both Infinite Scroll and resizable, <code>itemSelector</code> is recommended.</p>
<p>In the Infinite Scroll configuration, call Mercutio as a callback. Infinite Scroll provides the newly loaded elements as an argument, <code>newElements</code> in the example code. As this argument is an array of the DOM nodes, it needs to be passed in as a jQuery object to be used for the value of <code>appendedContent</code>.</p>
<p>In the Infinite Scroll configuration, call Molequul as a callback. Infinite Scroll provides the newly loaded elements as an argument, <code>newElements</code> in the example code. As this argument is an array of the DOM nodes, it needs to be passed in as a jQuery object to be used for the value of <code>appendedContent</code>.</p>
<p><ahref="./#images">As recommended in the primer,</a> the best solution to handle images is to have the size attributes defined in the <code>img</code> tag, especially when using Infinite Scroll. This is the solution employed in the example below.</p>
<p>Of course, this is not a viable option in some CMSs, most notably <ahref="http://tumblr.com">Tumblr</a>. In this situation, Mercutio needs to be called after the newly-appended images are fully loaded. This is done by delaying the Mercutio callback.</p>
<p>Of course, this is not a viable option in some CMSs, most notably <ahref="http://tumblr.com">Tumblr</a>. In this situation, Molequul needs to be called after the newly-appended images are fully loaded. This is done by delaying the Molequul callback.</p>
<pre><code><spanclass="comment">// call mercutio as a callback, after 1000 milliseconds</span>
<pre><code><spanclass="comment">// call molequul as a callback, after 1000 milliseconds</span>
window.console&&console.error('Column width calculated to be zero. Stopping Mercutio plugin before divide by zero. Check that the width of first child inside the mercutio container is not zero.');
window.console&&console.error('Column width calculated to be zero. Stopping Molequul plugin before divide by zero. Check that the width of first child inside the molequul container is not zero.');
desandro
15 years ago