jQuerySpecialEventTemplate.js

/**
 * @author  Ray Peters <me@raypeters.com>
 * If this helped you out, please let me know! Happy coding.
 */

/**
 * handleObj
 * 
 * type: String: The type of event, such as "click". When special event mapping
 *   is used via bindType or delegateType, this will be the mapped type.
 *   
 * origType: String: The original type name (in this case, "click") regardless
 *   of whether it was mapped via bindType or delegateType. So when a "pushy"
 *   event is mapped to "click" its origType would be "pushy". See the examples
 *   in those special event properties above for more detail.
 *   
 * namespace: String: Namespace(s), if any, provided when the event was
 *   attached, such as "myPlugin". When multiple namespaces are given, they are
 *   separated by periods and sorted in ascending alphabetical order. If no
 *   namespaces are provided, this property is an empty string.
 *   
 * selector: String: For delegated events, this is the selector used to filter
 *   descendant elements and determine if the handler should be called. In the
 *   example it is "button". For directly bound events, this property is null.
 *   
 * data: Object: The data, if any, passed to jQuery during event binding,
 *   e.g. { myData: 42 }. If the data argument was omitted or undefined, this
 *   property is undefined as well.
 *   
 * handler: function( event: jQuery.Event ): Event handler function passed to
 *   jQuery during event binding; in the example it is a reference to
 *   myHandler. If false was passed during event binding, the handler
 *   refers to a single shared function that simply returns false.
 * 
 */

jQuery.event.special.myPlugin = {
  /**
   * Indicates whether this event type should be bubbled when the .trigger()
   * method is called; by default it is false, meaning that a triggered event
   * will bubble to the element's parents up to the document (if attached to
   * a document) and then to the window. Note that defining noBubble on an
   * event will effectively prevent that event from being used for delegated
   * events with .trigger().
   */
  noBubble: false,

  /**
   * delegateType, bindType:
   * When defined, these string properties specify that a special event should
   * be handled like another event type until the event is delivered.
   */
  delegateType: 'click',
  bindType: 'click',
  
  /**
   * The setup hook is called the first time an event of a particular type is
   * attached to an element; this provides the hook an opportunity to do
   * processing that will apply to all events of this type on this element.
   *
   * @note most functions shouldn't use the namespaces param... because
   * this fires only on the first attachment.
   * 
   * @param {Object} data
   * @param {String} namespaces
   * @param {Function} eventHandle
   */
  setup: function( data, namespaces, eventHandle ) {},

  /**
   * The teardown hook is called when the final event of a particular type is
   * removed from an element.
   * 
   * @note no arguments
   */
  teardown: function() {},

  /**
   * when handlers are registered via `.on()`
   * @param {Object} handleObject See definition above
   */
  add: function( handleObject ) {},

  /**
   * when handlers are unregistered via `.off()`
   * @param {Object} handleObject See definition at top
   */
  remove: function( handleObject ) {},

  /**
   * when `myPlugin` event has occurred 
   * @note great time to modify the Event object before calling original
   * 
   * @param  {jQuery.Event} ev 
   * @param  {Object} data
   */
  handle: function( ev, data ) {
    // use `ev.handleObj.handler`
  },

  /**
   * When a _default hook is specified, the hook is called just prior to
   * checking for and executing the element's default method. If this hook
   * returns the value false the element's default method will be called;
   * otherwise it is not.
   * 
   * @param  {jQuery.Event} ev 
   * @param  {Object} data
   */
  _default: function( ev, data ) {
    // `ev.handleObj` is available
    
    // Return false to call the element's default method
    return true;
  },

  /**
   * When `.trigger()` or `.triggerHandler()` is called directly
   * 
   * @param  {jQuery.Event} ev 
   * @param  {Object} data
   */
  trigger: function( ev, data ) {
    // `ev.handleObj` is available
    
    /**
     * If the hook returns false, jQuery does not perform any further
     * event triggering actions and returns immediately. Otherwise,
     * it performs the normal trigger processing, calling any event
     * handlers for the element and bubbling the event (unless propagation
     * is stopped in advance or noBubble was specified for the special
     * event) to call event handlers attached to parent elements.
     */
    
    return true;
  }
};