jquery-fsortable

A fixed layout sortable plugin for jQuery UI.

Demo

Check http://nighttrax.github.io/jquery-fsortable/ for a demo.

IMPORTANT NOTE

The jQuery UI sortable plugin (which fsortable builds upon) currently has 2 bugs that affect fsortable when working with connected sortables.

The first bug causes over and out events to not be triggered properly when using connected sortables. See http://bugs.jqueryui.com/ticket/9335 for more details.

The second bug causes change events to trigger on the sender list, rather than on the current list, when dragging an item from a connected sortable. See http://bugs.jqueryui.com/ticket/9760 for more details.

If you don't need connected sortables then you can use this plugin as is. However, if you do require that functionality, then please use the following repo until the fixes land upstream. https://github.com/NiGhTTraX/jquery-ui/tree/experimental

Usage

Include jquery-fsortable.js in your project and call $("#my-div").fsortable(). fsortable creates a sortable instance for you. You can call it on an existing instance by passing existingSortable: true in the options at creation time.

After you create the fsortable instance you can call methods on the underlying sortable instance by passing them through the .sortable() wrapper. The plugin will still fire sort instance just like a normal sortable plugin.

Creating a fixed layout

There's some necessary markup you need to use to let fsortable know about your layout. Since it assumes your sortable has a fixed capacity you need to tell it how many items it can hold. It takes that information from the HTML itself by counting the number of items in your sortable and the number of empty positions.

Any item that matches the items option of the sortable plugin will be counted as being part of the layout. Any item that has the emptyClass class will be counted as being a free slot. The sum of both will be the total capacity of the sortable.

Let's take an example.

<div id="mysortable">
  <div>Item 1</div>
  <div>Item 2</div>
  <div class="fsortable-empty"></div>
  <div>Item 3</div>
</div>

We've defined a layout with a total capacity of 4, that contains 3 items and 1 free slot. Once that free slot will be occupied (i.e. dragging a draggable over it) the fsortable will become full and it will be marked as being so by having the full class set on it.

If you need to change the size of the fsortable you can do so, but remember to call the refresh method on it so it recalculates the items and free slots.

To connect draggables with your fsortable you need to do the following.

$(".my-draggable").draggable({
  connectToSortable: ".fsortable:not(.full)"
});

Note the :not(.full) selector. That tells the draggables to not connect with full fsortables.

Building

Fsortable uses the Grunt build system. To build Fsortable, you must have node.js installed and then run the following commands:

# Install the Grunt CLI.
npm install -g grunt-cli

# Clone the repository.
git clone [email protected]:NiGhTTraX/jquery-fsortable.git
cd jquery-fsortable

# Install node module dependencies.
npm install

# Run the build task.
grunt

If all went well, you will find a minified version of the plugin in the build/ folder.

Testing

Run grunt test to run the tests in PhantomJS or open tests/index.html to run them in your browser. Tests are written using the QUnit framework and the jQuery Event Unit Testing Helpers.

To enable coverage, place the resources/ and tests/ folders in your webserver and run the tests from there with the coverage option in QUnit checked (running coverage locally will throw a cross-domain error). Coverage is done using blanket.js.