Skip to content

Latest commit

 

History

History
executable file
·
179 lines (149 loc) · 7.85 KB

README.md

File metadata and controls

executable file
·
179 lines (149 loc) · 7.85 KB
Raw

nestedSortable jQuery plugin

nestedSortable is a jQuery plugin that extends jQuery Sortable UI functionalities to nested lists.

Meteor Installation

meteor add ilikenwf:nested-sortable

What's new in version 2.0

The biggest change is that your nested list can now behave as a tree with expand/collapse funcionality. Simply set isTree to true in the options and you are good to go! Check the demo out to see what can be done with nestedSortable and a little CSS. (Note that all nestedSortable does is to assign/remove classes on the fly)
Also:

  • isAllowed function finally works as expected, see the docs below
  • Fixed: a small bug in the protectRoot function
  • Changed: no drop zone will appear at all if you try to nest an item under another one that has the no-nesting class.
  • Added: doNotClear option to prevent the plugin from deleting empty lists

Features

  • Designed to work seamlessly with the nested set model (have a look at the toArray method)
  • Items can be sorted in their own list, moved across the tree, or nested under other items.
  • Sublists are created and deleted on the fly
  • All jQuery Sortable options, events and methods are available
  • It is possible to define elements that will not accept a new nested item/list and a maximum depth for nested items
  • The root level can be protected
  • The parentship of items can be locked, just as if it was a family tree.

Usage

<ol class="sortable">
	<li><div>Some content</div></li>
	<li>
		<div>Some content</div>
		<ol>
			<li><div>Some sub-item content</div></li>
			<li><div>Some sub-item content</div></li>
		</ol>
	</li>
	<li><div>Some content</div></li>
</ol>

	$(document).ready(function(){

		$('.sortable').nestedSortable({
			handle: 'div',
			items: 'li',
			toleranceElement: '> div'
		});

	});

Please note: every <li> must have either one or two direct children, the first one being a container element (such as <div> in the above example), and the (optional) second one being the nested list. The container element has to be set as the 'toleranceElement' in the options, and this, or one of its children, as the 'handle'.

Also, the default list type is <ol>.

This is the bare minimum to have a working nestedSortable. Check the demo out to see what can be accomplished with a little more.

Custom Options

disableParentChange (2.0)
Set this to true to lock the parentship of items. They can only be re-ordered within theire current parent container.
doNotClear (2.0)
Set this to true if you don't want empty lists to be removed. Default: false
expandOnHover (2.0)
How long (in ms) to wait before expanding a collapsed node (useful only if isTree: true). Default: 700
isAllowed (function)
You can specify a custom function to verify if a drop location is allowed. Default: function (placeholder, placeholderParent, currentItem) { return true; }
isTree (2.0)
Set this to true if you want to use the new tree functionality. Default: false
listType
The list type used (ordered or unordered). Default: ol
maxLevels
The maximum depth of nested items the list can accept. If set to '0' the levels are unlimited. Default: 0
protectRoot
Whether to protect the root level (i.e. root items can be sorted but not nested, sub-items cannot become root items). Default: false
rootID
The id given to the root element (set this to whatever suits your data structure). Default: null
rtl
Set this to true if you have a right-to-left page. Default: false
startCollapsed (2.0)
Set this to true if you want the plugin to collapse the tree on page load. Default: false
tabSize
How far right or left (in pixels) the item has to travel in order to be nested or to be sent outside its current list. Default: 20
excludeRoot
Exlude the root item from the toArray output

Custom Classes (you will set them in the options as well)

branchClass (2.0)
Given to all items that have children. Default: mjs-nestedSortable-branch
collapsedClass (2.0)
Given to branches that are collapsed. It will be switched to expandedClass when hovering for more then expandOnHover ms. Default: mjs-nestedSortable-collapsed
disableNestingClass
Given to items that will not accept children. Default: mjs-nestedSortable-no-nesting
errorClass
Given to the placeholder in case of error. Default: mjs-nestedSortable-error
expandedClass (2.0)
Given to branches that are expanded. Default: mjs-nestedSortable-expanded
hoveringClass (2.0)
Given to collapsed branches when dragging an item over them. Default: mjs-nestedSortable-hovering
leafClass (2.0)
Given to items that do not have children. Default: mjs-nestedSortable-leaf
disabledClass (2.0)
Given to items that should be skipped when sorting over them. For example, non-visible items that are still part of the list. Default: mjs-nestedSortable-disabled

Custom Methods

serialize
Serializes the nested list into a string like setName[item1Id]=parentId&setName[item2Id]=parentId, reading from each item's id formatted as 'setName_itemId' (where itemId is a number). It accepts the same options as the original Sortable method (key, attribute and expression).
toArray
Builds an array where each element is in the form: 
setName[n] =>
{
	'item_id': itemId,
	'parent_id': parentId,
	'depth': depth,
	'left': left,
	'right': right,
}
It accepts the same options as the original Sortable method (attribute and expression) plus the custom startDepthCount, that sets the starting depth number (default is 0).
toHierarchy
Builds a hierarchical object in the form: 
'0' ...
	'id' => itemId
'1' ...
	'id' => itemId
	'children' ...
		'0' ...
			'id' => itemId
		'1' ...
			'id' => itemId
'2' ...
	'id' => itemId
Similarly to toArray, it accepts attribute and expression options. Optionally adding `data-` attributes will cause them to show up in the hierarchy. See demo for example.

Events

change
Fires when the item is dragged to a new location. This triggers for each location it is dragged into not just the ending location.
sort
Fires when the item is dragged.
revert
Fires once the object has moved if the new location is invalid.
relocate
Only fires once when the item is done bing moved at its final location.

Known Bugs

nestedSortable doesn't work properly with connected draggables, because of the way Draggable simulates Sortable mouseStart and mouseStop events. This bug might or might not be fixed some time in the future (it's not specific to this plugin).

Requirements

jQuery UI Sortable 1.10+ (might work with 1.9, but not tested)

Browser Compatibility

Tested with: Firefox, Chrome
NOTE: This is still an alpha version, please test thoroughly in whichever version of IE you target

License

This work is licensed under the MIT License.
Which means you can do pretty much whatever you want with it.