cloak.controller/readme.md

Cloak.js controller module

# cloak.controller

Cloak.js is a collection of modules for building modern web applications. Each module is designed to work with the others, but are decoupled to allow you pick and choose which ones you need. Want views but don't need to deal with models or a complex router? You can do that! First, make sure you have `cloak.core` which contains some basic utilities for each module. Then, install the modules you want.

```bash
$ npm install --save cloak.core
$ npm install --save cloak.view
```

Then, in your JavaScript, just start using the components. Cloak is designed to work in a CommonJS environment, so any tools that do so will work (like [common.js](https://github.com/UmbraEngineering/common.js) or [browserify](http://browserify.org/)).

```javascript
var View = require('cloak.view');

var MyView = module.exports = View.extend({
    
    template: 'views/myview/myview.hbs',

    draw: function() {
        this.elem.innerHTML = this.render();
    }

});
```

## Cloak modules

* [cloak.core](https://github.com/UmbraEngineering/cloak.core) - The cloak core: tiny, but used by all the cloak modules
* [cloak.view](https://github.com/UmbraEngineering/cloak.view) - Provides the `View` class
* [cloak.model](https://github.com/UmbraEngineering/cloak.model) - Provides the `Model` and `Collection` classes for handling data
* [cloak.router](https://github.com/UmbraEngineering/cloak.router) - Provides the `Router` class for all you app routing needs
* [cloak.controller](https://github.com/UmbraEngineering/cloak.controller) - Provides a super-minimal `Controller` class for transitioning displaying views
* [cloak.xhr](https://github.com/UmbraEngineering/cloak.xhr) - Provides an easy interface for making HTTP requests by `XMLHttpRequest`; Also provides an interface to define XHR methods on the `Model` and `Controller` classes
* [cloak.localstorage](https://github.com/UmbraEngineering/cloak.localstorage) - Provides an easy interface for storing data in local storage; Also provides an interface to use local storage as your main app storage for `Model` and `Collection` classes
* [cloak.i18n](https://github.com/UmbraEngineering/cloak.i18n) - Provides a simple internationalization interface for storing translated phrases and determining a client's language
* [cloak.socketio](https://github.com/UmbraEngineering/cloak.socketio) - Provides a [socket.io](http://socket.io) interface for models based on the [dagger.js](http://www.daggerjs.com) websocket api
* [cloak.animate](https://github.com/UmbraEngineering/cloak.animate) - Provides animaion methods for controllers and views
* [cloak.forms](https://github.com/UmbraEngineering/cloak.forms) - Provides an extension to `cloak.view` for easier handling of forms
* [cloak.nedb](https://github.com/UmbraEngineering/cloak.nedb) - Provides a NeDB (Node Embedded Database) interface for model storage. A faster, more complete local data implementation than `cloak.localstorage` meant for use in local applications (like node-webkit projects)



## Usage

```bash
$ npm install --save cloak.core cloak.controller cloak.view
```

```javascript
var YourView    = require('views/your-view');
var Controller  = require('cloak.controller');

var YourController = module.exports = Controller.extend({

    //
    // Your initialize method
    //
    initialize: function(scope) {
        this.elem = scope;
    },

    //
    // The predraw method handles things like initial rendering, and is often
    // used for things like displaying loading images before content can
    // be loaded
    //
    predraw: function() {
        showLoadingSpinner();
    },

    //
    // The load method is for loading in data from your server (or where ever)
    // and preparing it for use. This method can return the data directly in
    // the case of a sychronous process, or it can return a promise
    //
    load: function() {
        return loadData();
    },

    //
    // The draw method is for the actual final rendering of the view once the
    // data has been loaded in. It will receive the data from the load method
    // as its first argument
    //
    draw: function(data) {
        var view = this.view = new YourView();

        this.elem.appendChild(view.elem);
        view.draw(data);
    },

    //
    // The undraw method is for when a controller is no longer needed, and
    // should handle the graceful undrawing of the view. This could include
    // exit animations, or resource cleanup, etc.
    //
    undraw: function() {
        this.view.remove();
    }

});

// Then use it ...
var main = document.getElementById('wrapper');
var controller = new YourController(main);
controller.run();
```

Remember, Cloak classes have mixin support, so if you want to have reusable components for things like enter/exit animations for your controllers, or loading spinners, it is an easy matter of declaring them and including them in the definition step:

```javascript
exports.fadeIn =  function() {
    return fadeIn(this.elem, 600);
};

exports.fadeOut = function() {
    return fadeOut(this.elem, 600);
};
```

```javascript
var FadeMethods = require('your-mixins/fade-methods');

var YourController = Controller.extend(FadeMethods, {

    // ...

    draw: function() {
        var self = this;
        var view = this.view = new YourView();

        this.fadeOut()
            .then(function() {
                self.elem.innerHTML = '';
                self.elem.appendChild(view.elem);
                view.draw();
                return self.fadeIn();
            });
    }

});
```