Q (cue) rapid dev library

Q.PluginFactory.Base

While PluginFactory provides you with a comfortable way of creating and registering new plugins, it would be incomplete without a set of base plugins that can be further extended. Q.PluginFactory.Base is the most basic plugin blueprint. All other plugins are based on it and inherit its properties and methods.

Q.PluginFactory.Base is a part of the Q.PluginFactory and does not require any additional files.

Tip: Use direct this references for callbacks

When developing a plugin, we encounter one of the greatest problems with handling events. In Javascript, event handlers are anonymous functions, so-called closures, which run in their own isolated context and have no reference of the class instance that called them. This, naturally, results in many complicated solutions to re-discovering the this context.

We can save all the pain by introducing a mandatory parameter instance to every event handler. The handler function would then use event.data.instance as reference to its relevant instance. When the event handler is called, provide this as value of the parameter.

  1. myElement.bind(
  2. "click",
  3. {instance:this},
  4. function(event){
  5. alert(event.data.instance);
  6. }
  7. );

User Interface

Base plugin is a barebone plugin without any User Interface. It only introduces important events and methods, necessary for development of more advanced plugins.

Properties

PluginFactory does not provide any properties of its own. Instead, look into individual plugins' properties.

$e (jQuery Object) this.$e

This property contains a jQuery reference to a DOM element on the page. Reference provided by this.$e points to the DOM element the instance was initialized for.

name (String) this.name

This property contains name of a Q plugin. It may be anything the creator of the plugin decides, though it is recommended to keep the naming convention "Q.PluginFactory.PluginName". A plugin's name property will be used by Q's stack method to help you identify the origin of a stack trace record.

Default: "Q.PluginFactory.Base"

id (String) this.id

ID is a unique identifier of the instance. It is either inherited from its DOM counterpart (for plugins that are tied to a HTML element), or auto-generated using Q.GUID() method. While it is false in a prototype plugin, it gets populated during initialization of the plugin, therefore it always has a unique value.

Default: false (see description)

options (Object) this.options

Collection of configuration variables, which can be passed on to a plugin during initialization time. These are merged with default_options (see below) and override their values.

Note: Only use the options for initialization of plugins.

Default: empty Object

super (reference) this.super

This is a reserved property.

Note: This property is currently not used. It will be used in the future for reverse inheritance features.

Default: false

cache (Object) this.cache

This object serves as data cache for plugins that work with external data.

Default: empty object

default_options (Object) this.default_options

This object contains default values of options. It is merged with supplied options during initialization.

Default: { super:false, bubbleEvents:{} }

Events

This Base plugin comes with several key events and a mechanism for handling multiple event handlers already in place.

onInit this.onInit() this.onInit( (function) )

The onInit event is triggered after the supplied options have been loaded and applied, but before the this.init() method was executed. This provides you with an option to process data and perform operations before the plugin was first loaded.

onReady this.onReady() this.onReady( (function) )

The onReady event is triggered after the this.init() method was executed. The premise of this.init() method is to run all necessary operations to retrieve data, perform initial calculations, and manipulate DOM structures in order to prepare the plugin for use. Once that is done, onReady event is triggered.

onDestroy this.onDestroy() this.onDestroy( (function) )

The onDestroy event is triggered before execution of the this.destroy() method. This gives you the opportunity to retrieve and/or submit any vital data before the plugin is unregistered, events destroyed and all of its DOM structures removed.

Methods

Following methods provide vital functionality to Base plugin and ensure that all plugins based on it would be equipped in the same way.

__init (void) this.__init( {HTMLElement}, {options} )

  Returns no value.

  This method is reserved for native plugin initialization.

HTMLElement
A jQuery representation of a DOM element. This element would become the canvas for your new plugin, and can be called at any point from within the instance as this.$e.
options
An object, containing configuration properties. The options are used during initialization and runtime to provide values for various configurables.
init (void) this.init( {HTMLElement}, {options} )

  Returns no value.

This method is empty by default, ready to be used by your custom initialization routine.

HTMLElement
A jQuery representation of a DOM element. This element would become the canvas for your new plugin, and can be called at any point from within the instance as this.$e.
options
An object, containing configuration properties. The options are used during initialization and runtime to provide values for various configurables.
destroy (void) this.destroy()

  Returns no value.

  This method accepts no parameters.

When this.destroy() is called, the event onDestroy gets triggered first, allowing you to retrieve potentially critical data and perform additional operations. Next, all event handlers are unlinked from the DOM element and its children, and all custom data related to the plugin are removed.

eventTrigger (void) this.eventTrigger( "eventType", {data} )

  Returns no value.

In order to deliver a custom, fully customizable and highly effective event mechanism, Q introduces several methods that ensure this requirement is met. this.eventTrigger is among them.

Upon receiving a call, this method loops over all event handlers registered under the appropriate event, and executes them within context of this, passing any received parameters.

eventType
A string name of the event to be triggered.
data
An object, containing parameters to be passed to event handlers. This object will be available as event.data within the handler methods.
  1. // Let's register a new event handler on initialization
  2. this.onInit(
  3. function(event) {
  4. alert(event.data.message);
  5. }
  6. );
  7.  
  8. // Let's trigger the onInit event queue with a message
  9. this.eventTrigger("onInit",{message:"Hello World!"});
  10.  
  11. // The page displays an alert with "Hello World!" message.
dropEvent (void) this.dropEvent( "eventType" ) (void) this.dropEvent( "eventType", (function) )

  Returns no value.

This method is another of several that ensure completely flexible and customizable event model of Q.

By calling this.dropEvent("myEvent"), you will remove all event handlers linked to event "myEvent". By supplying a second parameter in the form of an anonymous function (closure), you will limit the removal only to that particular closure.

This can be used to selectively remove outdated event handlers. Keep in mind though that you need to exactly match the closure you wish to remove.

eventType
A string name of the event to be triggered.
function
A closure (anonymous function), exactly matching the event handler to be removed.
  1. // Let's register a simple event handler:
  2. this.onInit(
  3. function(event) { alert("Hello World!"); }
  4. );
  5.  
  6. // And now we can remove it:
  7. this.dropEvent("onInit",
  8. function(event) { alert("Hello World!"); }
  9. );
  10.  
  11. // Omitting the 2nd parameter will clear all handlers:
  12. this.dropEvent("onInit");