Documentation

include MVC MVC.Animate MVC.Class MVC.Controller MVC.Controller.Action MVC.Controller.Action.Drag MVC.Controller.Action.Drop MVC.Controller.Action.EnterLeave MVC.Controller.Action.Event MVC.Controller.Action.Hover MVC.Controller.Action.Lasso MVC.Controller.Action.Selectable MVC.Controller.Action.Subscribe MVC.Controller.Comet MVC.Controller.Params MVC.Controller.Params.Drag MVC.Controller.Params.Drop MVC.Controller.Stateful MVC.Delegator MVC.Doc MVC.Element MVC.Event MVC.File MVC.History MVC.IO MVC.IO.Ajax MVC.IO.Comet MVC.IO.JsonP MVC.IO.WindowName MVC.IO.XDoc MVC.Model MVC.Model.Ajax MVC.Model.Cookie MVC.Model.JsonP MVC.Model.JsonRest MVC.Model.WindowName MVC.Model.XmlRest MVC.Native MVC.Native.Array MVC.Native.Date MVC.Native.Function MVC.Native.Number MVC.Native.Object MVC.Native.String MVC.Options MVC.Store MVC.SyntheticEvent MVC.Test MVC.Test.Assertions MVC.Test.Controller MVC.Test.Functional MVC.Test.Runner MVC.Test.Unit MVC.Timer MVC.Timer.Easings MVC.Vector MVC.View MVC.View.Helpers OpenAjax

MVC.Controller

Inherits: MVC.Class
Controllers respond to events. If something happens in your application, be it a click, or a Model being updated, a controller should respond to it.

Example

//Instead of:
$('.tasks').click(function(e){ ... })
//do this
TasksController = MVC.Controller.extend('tasks',{
  click: function(params){...}
})

Actions

To respond to events, controllers simply name their event handling functions to match an Action.

In the previous example, TasksController's click action is matched by the Event Action. Event matches functions that are combination of CSS selector and event name. Here's another example: 
TasksController = MVC.Controller.extend('tasks',{
  ".delete mouseover": function(params){ ... }
})

Types of Actions

There are many types of Actions. By default, Controller will match Event and Subscribe actions. To match other actions, include their plugins.

ActionFormatDescription
Event [CSS] [change|click|...] Matches standard DOM events
Subscribe [OpenAjax.hub event] subscribe Subscribes this action to OpenAjax hub.
Drag [CSS] [dragstart|dragging|...] Matches events on a dragged object
Drop [CSS] [dropadd|dropover|...] Matches events on a droppable object
EnterLeave [CSS] [mouseenter|mouseleave.] Similar to mouseover, mouseout, but handles nested elements.
Hover [CSS] [hoverenter|hoverleave.] Similar to mouseenter, but only gets called if the user stops on an element.
Lasso [CSS] [lassostart|...] Allows you to lasso elements.
Selectable [CSS] [selectadd|...] Matches events on elements that can be selected by the lasso.


Naming Controllers

Controllers use their name to limit the DOM they act upon. Depending if the controller name is plural, singular or main, it changes which elements it responds to.

Singular Controllers

Singluar controllers respond to events in or on an element with an id that matches the controller name. 
//matches <div id="file_manager"></div>
FileManagerController = MVC.Controller.extend('file_manager')

Plural Controllers

Plural controllers respond to events in or on elements with classNames that match the singular controller name. 
//matches <div class="task"></div>
TasksController = MVC.Controller.extend('tasks')
If you want to match events on an element with the id, add '#' to the start of your action. For example: 
TasksController = MVC.Controller.extend('tasks',{
  click : function(){ .. }     //matches <div class="task"></div>
  "# click" : function(){ .. } //matches <div id="tasks"></div>
})

Main Controllers

Controllers with the name 'main' can match events anywhere in the DOM.

Params

Controller actions get called with an instance of MVC.Controller.Params. Params provide aditional functionality based on the param data. Killing events is a good example. Some actions get called with classes that inherit from MVC.Controller.Params. Check your action's params for the data that gets passed to your event handling functions.

Static Methods

_listening

A flag if controllers can respond to events.

dispatch

dispatch(action_name, params) -> undefined
Calls the Controller prototype function specified by action_name with the given params.
{String} - The name of the action to be called.
{Controller.Params} - The params the action will be called with.

init

init() -> undefined
Looks for controller actions and hooks them up to delegator

modelName

The name of the model this controller can uses for param functions like element_instance

Prototype Methods

'dom/history'

_get_history_point

_get_history_point(options) -> undefined
Creates a history point from given options. Resultant history point is like #controller/action¶m1=value1
{Object} - an object that will turned into history point

continue_to

continue_to(action) -> Function
Returns a function that when called, calls the action with parameters passed to the function. This is very useful for creating callbacks for Ajax functionality. The callback is called on the same controller instance that created the callback. This allows you to easily pass objects between request and response without resorting to closures. Example: 
Controller('todos',{
   "a click" : function(params){ 
      this.element = params.element;
	  this.element.innerHTML = 'deleting ...';
	  new Ajax('delete', {onComplete: this.continue_to('deleted')}
   },
   deleted : function(response){
      this.element.parentNode.removeChild(this.element);
   }
});
{String} - Name of prototype function you want called
{Function} - function that when called, directs to another controller function

delay

delay(delay, action_name, params) -> undefined
Calls an action after some delay
{Object} -
{Object} -
{Object} -
'dom/history'

history_add

history_add(options, data) -> undefined
Adds history point to browser history.
{Object} - an object that will turned into a url like #controller/action¶m1=value1
{Object} - extra data saved in history
'dom/history'

path

path() -> undefined
Creates MVC.Path wrapper for current window.location
'dom/history'

path_data

path_data() -> undefined
Provides current window.location parameters as object properties.

publish

publish(message, data) -> undefined
Publishes a message to OpenAjax.hub. Other controllers
{String} -
{Object} -
'dom/history'

redirect_to

redirect_to(options) -> undefined
Redirects to another page.
{Object} - an object that will turned into a url like #controller/action¶m1=value1
controller/view

render

render(options) -> String
Renders a View template with the controller instance. If action or partial are not supplied in the options, it looks for a view in app/views/controller_name/action_name.ejs 
 TasksController = MVC.Controller.extend('tasks',{
   click : function(params){
     this.data = "Hello_world"                             // can display with <%= data %>
     this.render({after: params.element, action: "under"}) // renders with views/tasks/under.ejs
     this.render({to: "element_id"})                       // renders with views/tasks/click.ejs
     this.render({top: "another_e", partial: "bee/sugar")) // renders with views/bee/_sugar.ejs
   }
 })
{Object} - A hash with the following properties
OptionDefaultDescription
action null If present, looks for a template in app/views/controller_name/action.ejs
partial null A string value that looks like: 'folder/template' or 'template'. If a folder is present, it looks for a template in app/views/folder/_template.ejs; otherwise, it looks for a template in app/views/controller_name/template.ejs.
to null If present, a HTMLElement or element ID whose text will be replaced by the render.
before, after, top, bottom null If present, the content will be placed relative to the HTMLElement or element ID. The dom/element plugin is required for this functionality.
text null Instead of using a view to generate text, it uses the text as the rendered text.
using null If present, renders with the data in using instead of the controller instance. This is important for stateful controllers.
{String} - the result of the render.