Sortable

Everything is supposed to be easy – even sorting stuff. Drag'n'sort.

Definition

Name: Util.sortable
Syntax: void = Util.sortable( Node scope [, JSON _options ] );

Description

Applying this method directly to a list (<ul>), will make it's children sortable. Applying it to a scope containing several lists, will make each list a target and all their children sortable, freely between the targets.

The scope node passed to Util.sortable, will be extended with some helper functions listed below.

For additional accessibility, it applies a motion detection algorithm to your draggable elements, to ensure dragging only happens on purpose, and even features a "clickpick" option, to allow users to pick elements by clicking on them rather than dragging them.

You can define targets and draggables, using css selectors.

It can sort a single level or endlessly nested lists.

It can sort from, to and between multiple sources.

It can sort horizontal, vertical and multiline lists, with built-in customised overlap detection.

You can set up callback receivers for when a draggable node is picked, moved and dropped.

You'll be home before dinner.

Parameters

scope

Node scope containing sortable nodes

_options

JSON Optional rules for sorting

Options

picked: Name of callback function when element is picked (default picked)
moved: Name of callback function when element is moved (default moved)
dropped: Name of callback function when element is dropped (default dropped)
draggables: CSS Selector for draggable nodes - only these will be draggable (default all first level LI's of target nodes)
targets: CSS Selector for target nodes - you'll only be able to drag nodes to these elements (default all first level UL's in scope, unless scope is a UL)
layout: Force vertical/horisontal/multiline interpretation of scope (default auto-detect)
allow_nesting: Allow building nested structures when sorting nodes
allow_clickpick: Allow picking a node by clicking on it, rather than dragging it.
sorting_disabled: If set to true, sorting is disabled. Default = false.

Return values

Void

Callbacks

scope.picked(node): when draggable node is picked
scope.moved(node): when draggable node is moved
scope.dropped(node): when draggable node is dropped

Examples

Let's say we have an HTML structure like this:

<ul class="sort-me">
	<li>Item 1</li>
	<li>Item 2</li>
	<li>Item 3</li>
</ul>

We can the apply u.sortable to the list like this:

var ul_sort_me = u.querySelector("ui.sort-me");
u.sortable(ul_sort_me);

Now Item 1, Item 2 and Item 3 can be dragged around and rearranged in the list. To receive callbacks on picked, moved and dropped, you simply register receivers like this:

ul_sort_me.picked = function(node) {
	// node is the picked node
	// Whatever needs to be done on picked
}
ul_sort_me.moved = function(node) {
	// node is the moved node
	// Whatever needs to be done on moved
}
ul_sort_me.dropped = function(node) {
	// node is the dropped node
	// Whatever needs to be done on dropped
}

See the test page for a more implementations and use cases.

Dependencies

JavaScript

switch ... case
for ... in
document.createElement
document.appendChild
document.insertBefore

Manipulator

Util.querySelectorAll
Util.querySelector
Util.appendElement
Util.getComputedStyle
Util.applyStyles
Util.classVar
Util.absoluteY
Util.absoluteX
Util.eventX
Util.eventY
Util.Events.kill
Util.Events.removeWindowEndEvent
Util.Events.removeWindowMoveEvent
Util.Events.addStartEvent
Util.Events.addWindowMoveEvent
Util.Events.addWindowEndEvent

Definition

Name: scope.getNodeOrder
Syntax: Array = scope.getNodeOrder();

Description

Scope node is automatically extended with a getNodeOrder method. It returns an ordered Array of the sortable nodes.

Nodes in the structure will be identified by a ClassVar if available (defaults to item_id values). If a matching ClassVar is not present on the node, the node reference will be returned as the id.

Parameters

_options

JSON Optional settings

Options

class_var: ClassVar identifier to be used to identify nodes. Default: item_id

Return values

Array containing ordered node ClassVars values or node references.

Examples

Let's say we have an HTML structure like this:

<ul class="sort-me">
	<li class="item_id:1"><span>Item 1</span></li>
	<li class="item_id:2"><span>Item 2</span></li>
	<li class="item_id:3"><span>Item 3</span></li>
</ul>

We can the apply u.sortable to the list and get the node order like this:

var ul_sort_me = u.querySelector("ui.sort-me");
u.sortable(ul_sort_me);

var structure = ul_sort_me.getNodeOrder();

Structure would then contain:

["1", "2", "3"]

Dependencies

JavaScript

switch...case
for...in
Array.push

Manipulator

Util.classVar

Definition

Name: scope.getNodeRelations
Syntax: Array = scope.getNodeRelations();

Description

Scope node is automatically extended with a getNodeRelations method. It returns the structure of the sortable nodes in an ordered Array of Objects, each containing id or node reference, position and relation information.

Nodes and relations in the structure will be identified by a ClassVar if available (defaults to item_id values). If a matching ClassVar is not present on the node, the node reference will be returned as the id and relation properties.

Parameters

_options

JSON Optional settings

Options

class_var: ClassVar identifier to be used to identify nodes. Default: item_id

Return values

Array containing ordered Objects, again each containing information about ClassVar value or node reference, position and relation.

Examples

Let's say we have an HTML structure like this:

<div class="sort-me">
	<ul class="sort-me">
		<li class="item_id:1"><span>Item 1</span></li>
		<li class="item_id:2"><span>Item 2</span></li>
		<li class="item_id:3"><span>Item 3</span>
			<ul class="sort-me">
				<li class="item_id:4"><span>Item 4</span></li>
			</ul>
		</li>
	</ul>
</div>

We can the apply u.sortable to the list and get the node relations like this:

var div_sort_me = u.querySelector("div.sort-me");
u.sortable(div_sort_me, {allow_nesting: true});

var structure = div_sort_me.getNodeRelations();

Structure would then contain:

[
	{
		"id":"1",
		"relation":0,
		"position":1
	},
	{
		"id":"2",
		"relation":0,
		"position":2
	},
	{
		"id":"3",
		"relation":0,
		"position":3
	},
	{
		"id":"4",
		"relation":"3",
		"position":1
	}
]

Dependencies

JavaScript

switch...case
for...in
Array.push

Manipulator

Util.inNodeList
Util.classVar

Definition

Name: scope.getNodePositionInList
Syntax: Integer = scope.getNodePositionInList( Node node );

Description

Scope node is automatically extended with a getNodePositionInList method. It returns the current position of the node in the containing list.

Parameters

node: Node Node to get position of

Return values

Interger position in list, starting with 1.

Examples

Let's say we have an HTML structure like this:

<ul class="sort-me">
	<li class="item_1"><span>Item 1</span></li>
	<li class="item_2"><span>Item 2</span></li>
	<li class="item_3"><span>Item 3</span></li>
</ul>

We can the apply u.sortable to the list and get the position of an element like this:

var ul_sort_me = u.querySelector("ui.sort-me");
u.sortable(ul_sort_me);

var item_2 = u.querySelector("li.item_2", ul_sort_me);

var position = ul_sort_me.getNodePositionInList(item_2);

Position would then be:

2

Dependencies

JavaScript

while

Manipulator

Util.previousSibling

Definition

Name: scope.getNodeRelation
Syntax: String|Node = scope.getNodeRelation( Node node );

Description

Scope node is automatically extended with a getNodeRelation method. It returns the current relation of the node. If node is on root level, relation will be 0. If node is nested under another node, the ClassVar value of the container, or the container reference if no ClassVar value is present.

Parameters

node: Node Node to get relation of

Return values

String|Node relation of node in list, starting with 0 for root level. ClassVar or node reference of container for nested nodes.

Examples

Let's say we have an HTML structure like this:

<div class="sort-me">
	<ul class="sort-me">
		<li class="item_1 item_id:1"><span>Item 1</span></li>
		<li class="item_2 item_id:2"><span>Item 2</span></li>
		<li class="item_3 item_id:3"><span>Item 3</span>
			<ul class="sort-me">
				<li class="item_4 item_id:4"><span>Item 4</span></li>
			</ul>
		</li>
	</ul>
</div>

We can the apply u.sortable to the list and get the relation of an element like this:

var div_sort_me = u.querySelector("div.sort-me");
u.sortable(div_sort_me, {allow_nesting: true});

var item_4 = u.querySelector("li.item_4", div_sort_me);

var relation = div_sort_me.getNodeRelation(item_4);

Relation would then be:

3

Dependencies

JavaScript

None

Manipulator

Util.inNodeList
Util.classVar
Util.parentNode

Definition

Name: scope.resetSortableEvents
Syntax: void = scope.resetSortableEvents( Node node );

Description

Scope node is automatically extended with an resetSortableEvents method. It can be used to restore the event chain of a draggable node, ie. if you also have a click eventlistner inside a draggable node, and you don't want the click to also invoke a pick.

Parameters

node: Node Node to reset event listeners of

Return values

Void

Examples

No examples

Dependencies

JavaScript

None

Manipulator

Util.Events.removeMoveEvent
Util.Events.removeEndEvent
Util.Events.removeOverEvent
Util.Events.removeWindowMoveEvent
Util.Events.removeWindowEndEvent
Util.Events.removeOutEvent

Definition

Name: scope.detectSortableLayout
Syntax: void = scope.detectSortableLayout();

Description

Scope node is automatically extended with an detectSortableLayout method. It inspects each of your targets and evaluates target layout to be either horizontal, vertical or multiline. This can be used to update the internal target layouts, should these change during use.

The individual target layout is used to decide which overlap detection method to use, when you drag nodes around.

Parameters

No parameters

Return values

Void

Examples

No examples

Dependencies

JavaScript

None

Manipulator

Util.childNodes

Definition

Name: scope.updateDraggables
Syntax: void = scope.updateDraggables();

Description

Scope node is automatically extended with an updateDraggables method. It allows you to update the internal draggables list of your scope. This can be used if new draggables are added programatically or if existing ones are removed.

This method will re-initialize all draggables – and de-initalize any element no longer present in the draggables list.

Parameters

No parameters

Return values

Void

Examples

No examples

Dependencies

JavaScript

Array.prototype.slice
String.toLowerCase
Function.prototype.call
Array.concat
parseInt

Manipulator

Util.Events.removeStartEvent
Util.Events.removeOverEvent
Util.Events.addStartEvent
Util.querySelector
Util.getComputedStyle
Util.childNodes

Definition

Name: scope.updateTargets
Syntax: void = scope.updateTargets();

Description

Scope node is automatically extended with an updateTargets method. It allows you to update the internal target list of your scope. This can be used if new targets are added programatically, or if existing ones are removed.

Parameters

No parameters

Return values

Void

Examples

No examples

Dependencies

JavaScript

Array.prototype.slice
String.toLowerCase
Function.prototype.call
Array.push
Array.unshift

Manipulator

Util.elementMatches
Util.querySelectorAll
Util.parentNode
Util.contains

Main file

u-sortable.js

Segment support files

none

desktop: u-sortable.js + u-dom.js + u-geometry.js + u-events.js + u-events-browser.js
desktop_ie11: u-sortable.js + u-dom.js + u-geometry.js + u-events.js + u-events-browser.js
desktop_ie10: u-sortable.js + u-dom.js + u-dom-desktop_ie.js + u-geometry.js + u-events.js + u-events-browser.js
desktop_ie9: u-sortable.js + u-dom.js + u-dom-desktop_ie.js + u-geometry.js + u-events.js + u-events-browser.js
desktop_light: not supported
tablet: u-sortable.js + u-dom.js + u-geometry.js + u-events.js + u-events-browser.js
tablet_light: u-sortable.js + u-dom.js + u-geometry.js + u-events.js + u-events-browser.js
smartphone: u-sortable.js + u-dom.js + u-geometry.js + u-events.js + u-events-browser.js
mobile: not supported
mobile_light: not supported
tv: not tested
seo: not supported

Sortable

Functions

Util.sortable

Definition

Description

Parameters

Options

Return values

Callbacks

Examples

Dependencies

JavaScript

Manipulator

scope.getNodeOrder

Definition

Description

Parameters

Options

Return values

Examples

Dependencies

JavaScript

Manipulator

scope.getNodeRelations

Definition

Description

Parameters

Options

Return values

Examples

Dependencies

JavaScript

Manipulator

scope.getNodePositionInList

Definition

Description

Parameters

Return values

Examples

Dependencies

JavaScript

Manipulator

scope.getNodeRelation

Definition

Description

Parameters

Return values

Examples

Dependencies

JavaScript

Manipulator

scope.resetSortableEvents

Definition

Description

Parameters

Return values

Examples

Dependencies

JavaScript

Manipulator

scope.detectSortableLayout

Definition

Description

Parameters

Return values

Examples

Dependencies

JavaScript

Manipulator

scope.updateDraggables

Definition

Description

Parameters

Return values

Examples

Dependencies

JavaScript

Manipulator

scope.updateTargets

Definition