jQuery Widget Template

gistfile1.coffee

# Name of Widget
# some general notes about purpose and usage


# naming convention is: ccWidgetName.coffee

# Getter and setter methods, return and chaining implications: 

# 	There are two kinds of plugin functions: getters and setters. 

# 	Setters manipulate elements and can be chained in jQuery code; they just return the jQuery object they started with. 

# 	Getters return information and break the chain. widget() distinguishes between the two by the return value: 
# 	If your function returns any value other than undefined, it assumes that it is a getter and returns that value 
# 	( for the first element in the jQuery object, just like all jQuery getter functions). If it does not return a value, 
# 	then it is assumed to be a setter and is called on each element in the jQuery object, and the jQuery object itself 
# 	is returned for chaining.
	
# This:

# 	Inside the prototype object, "this" is not the html element being called on, rather it is the widget object 
# 	returned from the widget factory, the html element we called the widget on is "this.element"
	
# Default methods available for objects created by the widget factory which can all be overwritten using 
# $.Widget.prototype.methodToOverride.apply( this, arguments ).

# 	destroy()
# 		Removes the instance from the encapsulated DOM element, which was stored on instance creation
	
# 	option(String key[, String value])
# 		Gets or sets an option for this instance
	
# 	enable()
# 		Set disabled option to false, it's up to the instance to respect the option
	
# 	disable()
# 		Set disabled option to true, it's up to the instance to respect the option 

# Default properties for each instance of an object created by the widget factory:

# 	options
# 		The options for this widget instance, a mix of defaults with settings provided by the user
		
# 	element
# 		A jQuery object always containing a single DOMElement, which can be accessed with this.element[0]
		
# Private methods:
# 	Method names begining with an underscore have their scope restricted to the widget object: they are private methods
	
# Other:
# 	Adding callbacks is possible
# 	Extending to expose other ui.widgets is possible: $.ui.mouse widget 
	
 
ccWidgetName = class 

	# this is the constructor function and is called once, and first, upon construction
	_create: -> 
		# Prepare the new object for use and set any member variables. 
		# "this" is the widget object. 
		# "this.element" is the html element we called the widget on.			

		$( "<p>widget create method called</p>" ).appendTo( this.element );
  									

	# called after construction and re-initialisation
	_init: ->
			
		# Use to do any set-up or house keeping after the object is created. 
		# "this" is the widget object. 
		# "this.element" is the html element we called the widget on.

		$( "<p>_init method called</p>" ).appendTo( this.element )
		this.customMethodOne()

	# Use the _setOption method to respond to changes to options
	_setOption: ( key, value ) ->
		console.log("_setOption called")

	# Use the destroy method to clean up any modifications your widget has made to the DOM
	destroy: ->
		# In jQuery UI 1.8, you must invoke the destroy method from the base widget
		$.Widget.prototype.destroy.call( this );
		# In jQuery UI 1.9 and above, you would define _destroy instead of destroy and not call the base method
      
	# custom method one
	customMethodOne: ->
			
		# Custom methods are where we do things. "this" is the widget object. 
		# "this.element" is the html element we called the widget on.
		
		# Tight or loose callbacks are possible				
		
		$( "<p>widget customMethodOne method called</p>" ).appendTo( this.element );
		this.customMethodTwo()
		
	# custom method two
	customMethodTwo: ->
			
		# Custom methods are where we do things. "this" is the widget object. 
		# "this.element" is the html element we called the widget on.
		
		# Tight or loose callbacks are possible				
		
		$( "<p>widget customMethodTwo method called</p>" ).appendTo( this.element );


	# Widget Options: the default options for the widget
	options: 
		optionOne: "optionOne"
		optionTwo: "optionTwo"
		
	# Widget css class names.
	css:
		cssOne: "ccWidgetName"
		cssTwo: "wrapper"
		
$.widget "cc.ccWidgetName", new ccWidgetName