plugin.md

@page jquery.controller.plugin The generated jQuery plugin @parent jQuery.Controller

When you create a controller, it creates a jQuery plugin that can be used to:

• Create controllers on an element or elements
• Call controller methods
• Update a controller

For example, the following controller:

$.Controller("My.Widget",{
  say : function(){
     alert(this.options.message);
  }
})

creates a jQuery.fn.my_widget method that you can use like:

// create my_widget on each .thing
$(".thing").my_widget({message : "Hello"}) 

// alerts "Hello"
$(".thing").my_widget("say");

// updates the message option
$(".thing").my_widget({message : "World"});

// alerts "World"
$(".thing").my_widget("say");

Note that in every case, the my_widget plugin returns the original jQuery collection for chaining ($('.thing')). If you want to get a value from a controller, use the [jQuery.fn.controllers] or [jQuery.fn.controller].

Creating controllers

When a controller's jQuery plugin helper is used on a jQuery collection, it goes to each element and tests if it has a controller instance on the element. If it does not, it creates one.

It calls new YourController with the element and any additional arguments you passed to the jQuery plugin helper. So for example, say there are 2 elements in $('.thing').

This:

$(".thing").my_widget({message : "Hello"})

Does the exact same thing as:

var things = $('.thing'),
    options = {message : "Hello"};
new My.Widget(things[0],options);
new My.Widget(things[1],options);

Note, when a new Class is created, it calls your class's prototype setup and init methods. Read [jQuery.Controller.prototype.setup controller's setup] for the details on what happens when a new controller is created.

Calling methods on controllers

Once a Controller is already on an element, you can call methods on it with the same jQuery helper. The first param to the helper is the name of the method, the following params are passed to the jQuery function. For example:

$.Controller("Adder",{
  sum : function(first, second, third){
     this.element.text(first+second+third);
  }
})

// add an adder to the page
$("#myadder").adder()

// show the sum of 1+2+3
$("#myadder").adder("sum",1,2,3);

Naming

By default, a controller's jQuery helper is the controller name:

• [jQuery.String.underscore underscored]
• "." replaced with "_"
• with Controllers removed.

Here are some examples:

$.Controller("Foo")                 // -> .foo()
$.Controller("Foo.Bar")             // -> .foo_bar()
$.Controller("Foo.Controllers.Bar") // -> .foo_bar()

You can overwrite the Controller's default name by setting a static pluginName property:

$.Controller("My.Tabs",
{
  pluginName: "tabs"
},
{ ... })

$("#tabs").tabs()