v0.5.0: filter/onFilter and closest (#72)

README.md

@@ -33,27 +33,27 @@ new Sortable(el, {
  group: "name",
  store: null, // @see Store
  handle: ".my-handle", // Restricts sort start click/touch to the specified element
+ filter: ".ignor-elements", // Selectors that do not lead to dragging (String or Function)
  draggable: ".item", // Specifies which items inside the element should be sortable
  ghostClass: "sortable-ghost",
 
- onStart: function (/**Event*/evt) { // dragging
- var itemEl = evt.item;
- },
-
- onEnd: function (/**Event*/evt) { // dragging
- var itemEl = evt.item;
- },
+ onStart: function (/**Event*/evt) { /* dragging */ },
+ onEnd: function (/**Event*/evt) { /* dragging */ },
 
  onAdd: function (/**Event*/evt){
- var itemEl = evt.item;
+ var itemEl = evt.item; // dragged HTMLElement
  },
 
  onUpdate: function (/**Event*/evt){
- var itemEl = evt.item; // the current dragged HTMLElement
+ var itemEl = evt.item; // dragged HTMLElement
  },
 
  onRemove: function (/**Event*/evt){
- var itemEl = evt.item;
+ var itemEl = evt.item; // dragged HTMLElement
+ },
+
+ onFilter: function (/**Event*/evt){
+ var itemEl = evt.item; // HTMLElement on which was `nousedown|tapstart` event.
  }
 });
 ```
@@ -63,8 +63,28 @@ new Sortable(el, {
 
 ### Method
 
+##### closest(el:`String`[, selector:`HTMLElement`]):`HTMLElement|null`
+For each element in the set, get the first element that matches the selector by testing the element itself and traversing up through its ancestors in the DOM tree.
+
+```js
+var editableList = new Sortable(list, {
+ filter: ".js-remove, .js-edit",
+ onFilter: function (evt) {
+ var el = editableList.closest(evt.item); // list item
+
+ if (editableList.closest(evt.item, ".js-remove")) { // Click on remove button
+ el.parentNode.removeChild(el); // remove sortable item
+ }
+ else if (editableList.closest(evt.item, ".js-edit")) { // Click on edit link
+ // ...
+ }
+ }
+})
+```
+
+
 ##### toArray():`String[]`
-Serializes the sortable's item data-id's into an array of string.
+Serializes the sortable's item `data-id`'s into an array of string.
 
 
 ##### sort(order:`String[]`)
@@ -84,6 +104,14 @@ sortable.sort(order.reverse()); // apply
 ### Store
 Saving and restoring of the sort.
 
+```html
+<ul>
+ <li data-id="1">order</li>
+ <li data-id="2">save</li>
+ <li data-id="3">restore</li>
+</ul>
+```
+
 ```js
 new Sortable(el, {
  group: "localStorage-example",

Sortable.js

@@ -51,6 +51,12 @@
  return evt;
  }
 
+ , _dispatchEvent = function (rootEl, name, targetEl) {
+ rootEl.dispatchEvent(_createEvent(name, targetEl || rootEl));
+ }
+
+ , _customEvents = 'onAdd onUpdate onRemove onStart onEnd onFilter'.split(' ')
+
  , noop = function (){}
  , slice = [].slice
 
@@ -70,17 +76,26 @@
 
 
  // Defaults
- options.group = options.group || Math.random();
- options.store = options.store || null;
- options.handle = options.handle || null;
- options.draggable = options.draggable || el.children[0] && el.children[0].nodeName || (/[uo]l/i.test(el.nodeName) ? 'li' : '*');
- options.ghostClass = options.ghostClass || 'sortable-ghost';
- options.ignore = options.ignore || 'a, img';
+ var defaults = {
+ group: Math.random(),
+ store: null,
+ handle: null,
+ draggable: el.children[0] && el.children[0].nodeName || (/[uo]l/i.test(el.nodeName) ? 'li' : '*'),
+ ghostClass: 'sortable-ghost',
+ ignore: 'a, img',
+ filter: null
+ };
+
+ // Set default options
+ for (var name in defaults) {
+ options[name] = options[name] || defaults[name];
+ }
 
 
  // Define events
- 'onAdd onUpdate onRemove onStart onEnd'.split(' ').forEach(function (name) {
+ _customEvents.forEach(function (name) {
  options[name] = _bind(this, options[name] || noop);
+ _on(el, name.substr(2).toLowerCase(), options[name]);
  });
 
 
@@ -97,12 +112,6 @@
 
 
  // Bind events
- _on(el, 'add', options.onAdd);
- _on(el, 'update', options.onUpdate);
- _on(el, 'remove', options.onRemove);
- _on(el, 'start', options.onStart);
- _on(el, 'stop', options.onEnd);
-
  _on(el, 'mousedown', this._onTapStart);
  _on(el, 'touchstart', this._onTapStart);
  supportIEdnd && _on(el, 'selectstart', this._onTapStart);
@@ -132,8 +141,25 @@
  , target = (touch || evt).target
  , options = this.options
  , el = this.el
+ , filter = options.filter
  ;
 
+ // Check filter
+ if( typeof filter === 'function' && filter.call(this, target, this) ){
+ _dispatchEvent(el, 'filter', target);
+ return; // cancel dnd
+ }
+ else if( filter ){
+ filter = filter.split(',').filter(function (criteria) {
+ return _closest(target, criteria.trim(), el);
+ });
+
+ if (filter.length) {
+ _dispatchEvent(el, 'filter', target);
+ return; // cancel dnd
+ }
+ }
+
  if( options.handle ){
  target = _closest(target, options.handle, el);
  }
@@ -192,7 +218,7 @@
  } catch (err){ }
 
 
- dragEl.dispatchEvent(_createEvent('start', dragEl));
+ _dispatchEvent(dragEl, 'start');
  }
  },
 
@@ -381,17 +407,17 @@
 
  if( !rootEl.contains(dragEl) ){
  // Remove event
- rootEl.dispatchEvent(_createEvent('remove', dragEl));
+ _dispatchEvent(rootEl, 'remove', dragEl);
 
  // Add event
- dragEl.dispatchEvent(_createEvent('add', dragEl));
+ _dispatchEvent(dragEl, 'add');
  }
  else if( dragEl.nextSibling !== nextEl ){
  // Update event
- dragEl.dispatchEvent(_createEvent('update', dragEl));
+ _dispatchEvent(dragEl, 'update');
  }
 
- dragEl.dispatchEvent(_createEvent('stop', dragEl));
+ _dispatchEvent(dragEl, 'end');
  }
 
  // Set NULL
@@ -455,17 +481,27 @@
  },
 
 
+ /**
+ * For each element in the set, get the first element that matches the selector by testing the element itself and traversing up through its ancestors in the DOM tree.
+ * @param {HTMLElement} el
+ * @param {String} [selector] default: `options.draggable`
+ * @returns {HTMLElement|null}
+ */
+ closest: function (el, selector) {
+ return _closest(el, selector || this.options.draggable, this.el);
+ },
+
+
  /**
  * Destroy
  */
  destroy: function () {
  var el = this.el, options = this.options;
 
- _off(el, 'add', options.onAdd);
- _off(el, 'update', options.onUpdate);
- _off(el, 'remove', options.onRemove);
- _off(el, 'start', options.onStart);
- _off(el, 'stop', options.onEnd);
+ _customEvents.forEach(function (name) {
+ _off(el, name.substr(2).toLowerCase(), options[name]);
+ });
+
  _off(el, 'mousedown', this._onTapStart);
  _off(el, 'touchstart', this._onTapStart);
  _off(el, 'selectstart', this._onTapStart);
@@ -610,9 +646,11 @@
  i = str.length,
  sum = 0
  ;
+
  while (i--) {
  sum += str.charCodeAt(i);
  }
+
  return sum.toString(36);
  }
 
@@ -625,13 +663,15 @@
  find: _find,
  bind: _bind,
  closest: _closest,
- toggleClass: _toggleClass
+ toggleClass: _toggleClass,
+ createEvent: _createEvent,
+ dispatchEvent: _dispatchEvent
  };
 
 
- Sortable.version = '0.4.1';
+ Sortable.version = '0.5.0';
 
 
  // Export
- return Sortable;
+ return Sortable;
 });