name: Controller

class: Marionette.Controller

extends: 
  - Backbone.Events
  - Backbone.extend

description: |
  A Controller is a white-label Marionette Object. Its name can be a cause for
  confusion, as it actually has nothing to do with the popular MVC architectural pattern.
  Instead, it's better to think of the Controller as a base object from which you can build.
  
  Controllers should be used when you have a task that you would like an object to be responsible for,
  but none of the other Marionette Classes quite make sense to do it. It's a base object for you to use to
  create a new Class altogether.
  
examples:
  -
    name: Basic Use
    example: |
      A `Marionette.Controller` can be extended, like other
      Backbone and Marionette objects. It supports the standard
      `initialize` method, has a built-in `EventBinder`, and
      can trigger events, itself.
      
      ```js
      // define a controller
      var MyController = Marionette.Controller.extend({
      
        initialize: function(options){
          this.stuff = options.stuff;
        },
        
        doStuff: function(){
          this.trigger("stuff:done", this.stuff);
        }
      });
      
      // use the built in EventBinder
      c.listenTo(c, "stuff:done", function(stuff){
        console.log(stuff);
      });
      
      // do some stuff
      c.doStuff();
      ```

constructor: 
  description: |
    Creates a new Controller.
    
    The constructor function calls initialize if it exists, 
    and sets the properties of the Controller. 
    
  examples:
    -
      name: Basic Use
      example: |
        ```js
        var c = new MyController({
          stuff: "some stuff"
        });
        ```
        
functions:
  
  initialize: 
    description: |
      Initialize is called after a controller has been instanciated.
      
      The `options` parameter can take any key/value pair and set it on the Controller instance.
          
      @param {...*} options - Options to be available on the Controller instance directly.
        
    examples:
      -
        name: Basic Use
        example: |
          ```js
          // define a controller
          var MyController = Marionette.Controller.extend({
          
            initialize: function(options){
              this.stuff = options.stuff;
            },
            
            doStuff: function(){
              this.trigger("stuff:done", this.stuff);
            }
          });
          ```
            
  destroy:
    description: | 
      Each Controller instance has a built in `destroy` method that handles
      unbinding all of the events that are directly attached to the controller
      instance, as well as those that are bound using the EventBinder from
      the controller.
      Invoking the `destroy` method will trigger the "before:destroy" and "destroy" events and the
      corresponding `onBeforeDestroy` and `onDestroy` method calls. These calls will be passed any arguments `destroy`
      was invoked with.
      
    examples:
      -
        name: Basic Use
        example: |
          ```js
          // define a controller with an onDestroy method
          var MyController = Marionette.Controller.extend({
            onBeforeDestroy: function(arg1, arg2){
              // put custom code here, before destroying this controller
            },
            onDestroy: function(arg1, arg2){
              // put custom code here, to destroy this controller
            }
          });
          
          // create a new controller instance
          var contr = new MyController();
          
          // add some event handlers
          contr.on("before:destroy", function(arg1, arg2){ ... });
          contr.on("destroy", function(arg1, arg2){ ... });
          contr.listenTo(something, "bar", function(){...});
          
          // destroy the controller: unbind all of the
          // event handlers, trigger the "destroy" event and
          // call the onDestroy method
          contr.destroy(arg1, arg2);
          ```