Added some documentation to the new SwipeListItemView

Author: SonoIo

lib/listviews/SwipeListItemView.js

@@ -36,7 +36,6 @@ let getPageY = function getPageY(ev){
 	return pageY;
 };
 
-
 /**
  * Class rapresent a list item with left and right swipe effect.
  * It's composed by a swipeable drawer and two actions panels positioned behind
@@ -71,8 +70,8 @@ let getPageY = function getPageY(ev){
  *   }
  *   onSelectItem(item, done) {
  *     if (item) {
- *       // Element clicked, you should check if it is the left, or right, action
- *       // button and ignore the drawer
+ *       // Element clicked, you should check if it is the left, or right,
+ *       // action button and ignore the drawer
  *       console.log(item.element);
  *     }
  *     return done();
@@ -81,6 +80,32 @@ let getPageY = function getPageY(ev){
  */
 export default class SwipeListItemView extends ListItemView {
 
+	/**
+	 * Triggered when the user stop dragging the drawer with the left action
+	 * active
+	 * @event SwipeListItemView#swipe:left
+	 * @property {SwipeListItemView} item - Self
+	 */
+
+	/**
+	 * Triggered when the user stop dragging the drawer with the right action
+	 * active
+	 * @event SwipeListItemView#swipe:right
+	 * @property {SwipeListItemView} item - Self
+	 */
+
+	/**
+	 * Triggered when the user end dragging
+	 * @event SwipeListItemView#dragging:end
+	 * @property {SwipeListItemView} item - Self
+	 */
+
+	/**
+	 * Triggered when the user stop dragging
+	 * @event SwipeListItemView#dragging:start
+	 * @property {SwipeListItemView} item - Self
+	 */
+
 	constructor(options) {
 		super(options);
 
@@ -99,7 +124,7 @@ export default class SwipeListItemView extends ListItemView {
 			activeClassName: 'action-active'
 		});
 
-		if (!this.options.parent) {
+		if (!this.options.parentList) {
 			throw new Error('Parent list view is required for SwipeListItemView');
 		}
 
@@ -122,6 +147,13 @@ export default class SwipeListItemView extends ListItemView {
 		this.listenTo(this.parent, 'dragging:start', this.onListItemDraggingStart);
 	}
 
+	/**
+	 * Render the view
+	 * @version 2.1.0
+	 * @private
+	 * @param {bool} rendered - Indicate if the view was already rendered
+	 * @return {SwipeListItemView} - Self
+	 */
 	onRender(rendered) {
 		if (!rendered) {
 			this.cache.$leftAction = $('<div class="ui-swipe-list-item-actions ui-swipe-list-item-actions-left">');
@@ -142,6 +174,12 @@ export default class SwipeListItemView extends ListItemView {
 		return this;
 	}
 
+	/**
+	 * Called when the user touch the view
+	 * @version 2.1.0
+	 * @private
+	 * @param  {object} e - jQuery touch event
+	 */
 	onTouchStart(e) {
 		if (this.status === STATUS_DRAGGING) return;
 
@@ -164,6 +202,17 @@ export default class SwipeListItemView extends ListItemView {
 		this.trigger('dragging:start', this);
 	}
 
+	/**
+	 * Called when the user move the finger on the view for the first time.
+	 * It's used to check if the movement is horizontal or vertical. If it's
+	 * horizontal it attaches a touchmove and touchend event to the document,
+	 * stops the parentList scroll and start move the drawer. If it's vertical
+	 * ignore the event.
+	 * @version 2.1.0
+	 * @private
+	 * @param  {[type]} e [description]
+	 * @return {[type]}   [description]
+	 */
 	onCheckDirectionTouchMove(e) {
 		const x = getPageX(e);
 		const y = getPageY(e);
@@ -186,6 +235,14 @@ export default class SwipeListItemView extends ListItemView {
 		document.removeEventListener('touchmove', this.onCheckDirectionTouchMove);
 	}
 
+	/**
+	 * Called when the user removes the finger from the screen. It check the
+	 * position of the drawer and react to toggleLeft, toggleRight options.
+	 * It also trigger swipe:left, swipe:right, dragging:end events.
+	 * @version 2.1.0
+	 * @private
+	 * @param {object} e - DOM touch event
+	 */
 	onTouchEnd(e) {
 		this.parent.resume();
 		document.removeEventListener('touchmove',   this.onTouchMove);
@@ -226,6 +283,13 @@ export default class SwipeListItemView extends ListItemView {
 		this.trigger('dragging:end', this);
 	}
 
+	/**
+	 * Called when the user moves a finger on the screen. It handles the
+	 * drawer movement and also adds the options.activeClassName to the view.
+	 * @param {object} e - DOM touch event
+	 * @version 2.1.0
+	 * @private
+	 */
 	onTouchMove(e) {
 		const x = getPageX(e);
 		let deltaX = this.deltaX = x - this.startX;
@@ -269,6 +333,7 @@ export default class SwipeListItemView extends ListItemView {
 				this.vibrate();
 			} else if (deltaX < this.options.leftWidth && this.hasActiveClass) {
 				this.removeActiveClass();
+				this.vibrate();
 			}
 		}
 
@@ -279,17 +344,32 @@ export default class SwipeListItemView extends ListItemView {
 				this.vibrate();
 			} else if (deltaX > -this.options.rightWidth && this.hasActiveClass) {
 				this.removeActiveClass();
+				this.vibrate();
 			}
 		}
 
 		translate3d(this.cache.$drawer, deltaX, 0, 0);
 	}
 
+	/**
+	 * Called when another SwipeListItemView start dragging. It closes the
+	 * drawer to prevent multiple drawers opened on the same list.
+	 * NOTE: This method receives his dragging:start event.
+	 * @private
+	 * @version 2.1.0
+	 * @param {SwipeListItemView} item - Item that triggered the event
+	 */
 	onListItemDraggingStart(item) {
 		if (item === this) return;
 		this.closeDrawer();
 	}
 
+	/**
+	 * Close the drawer
+	 * @public
+	 * @version 2.1.0
+	 * @param {bool} [animated] [true] - Close the drawer with an animation
+	 */
 	closeDrawer(animated = true) {
 		if (this.status === STATUS_NORMAL) return;
 		if (animated) {
@@ -303,25 +383,46 @@ export default class SwipeListItemView extends ListItemView {
 		this.status = STATUS_NORMAL;
 	}
 
+	/**
+	 * Ensure that a model sostitution closes the drawer (without animation)
+	 * @private
+	 * @version 2.1.0
+	 * @param {Model} newModel - The new model
+	 */
 	setModel(newModel) {
 		this.closeDrawer(false);
 		return super.setModel(newModel);
 	}
 
+	/**
+	 * Helper method used to add the activeClassName only when necessary
+	 * @private
+	 * @version 2.1.0
+	 */
 	addActiveClass() {
 		if (!this.hasActiveClass) {
 			this.$el.addClass(this.options.activeClassName);
 			this.hasActiveClass = true;
 		}
 	}
 
+	/**
+	 * Helper method used to remove the activeClassName only when necessary
+	 * @private
+	 * @version 2.1.0
+	 */
 	removeActiveClass() {
 		if (this.hasActiveClass) {
 			this.$el.removeClass(this.options.activeClassName);
 			this.hasActiveClass = false;
 		}
 	}
 
+	/**
+	 * Helper method called when it's the time to launch a vibration
+	 * @private
+	 * @version 2.1.0
+	 */
 	vibrate() {
 		if (this.options.vibrateCallback) {
 			this.options.vibrateCallback();