#Yolo Yolo is MVC webframework written in Nodejs heavily inspired by ruby on rails. It powers our Heythere servers.

##Install Yolo requires nodejs, couchdb and redis to run

$ npm install yolo-server

#Scaffolding Scaffolding for app structure, models and controllers is available via the yolo-cli. ##Start Your app needs a special structure in order to get yolo running for you:

app/
	models/
	controllers/
	views/
	public/
config/
	production.js
	development.js
	routes.js

Require yolo where ever you want and pass the those folders to the run method like so:

var Yolo = require('yolo-server'),
	server = new Yolo();

server.run({
	app : 'app/',
	config : 'config/'
});

After calling run Yolo will boot up and look up all models files in /app/models and all controllers in /app/controllers. It will bind all routes configured in the /config/routes.js file for you. Be Aware that Yolo can be used in libary fashion but its a framework and it will register a global variable named "Yolo".

#Models Yolo.Model is basiclly a Backbone.Model extended with validation and a couchdb layer. Models go into app/models and are loaded automaticlly if Yolo boots. Note for now we only support couchdb as database.

You define a model by extending the Yolo.Model:

module.exports = Yolo.Model.extend({ 		
	//…
});

###Attributes You can define attributes for each model with default values and validation rules:

attributes : {
		firstName : {
			required : true
		},
		lastName : {
			required : true,
		},
		email : {
			pattern : 'email',
		},
		password : {
			required : true,
			minLength : 5,
			sanitize : false
		},
		bio : {
			required : false,
			maxLength : 180
		},
		lastLogin : {
			"default" : new Date()
		},
		friends : {
			"default" : [],
		}
	}

Default values will be set if the attribute is not set with a value and validators will be checked before the model is saved to db or manual via .isValid().

Full list of available validations: https://github.com/thedersen/backbone.validation#required

###Views Views are the couchdb way to query the database. Views consists of a map and a reduce function. However, views for each attribute will be autogenerated while booting. For example if your model has a attribute firstName we generate Model.findByFirstName for you. You can define additional views with the 'views' property which will be callable after booting:

views : {
	myCustomView : {
		map : function(doc){
			// for eg emit(doc)
		},
		reduce : function(){
			
		}
	}
}

This view would then be callabble via Model.myCustomView. The views will be saved as design document to couchdb. ###Working with Models ####get Use Model.get(key) to get attributes from a model:

var user = new User();
user.get('firstName');

####set Use Model.set(key, value) or Model.set({ key1: value1}) to set attributes to the model:

var user = new User();
user.set('firstName');

If you initialize a new model you can pass an object of keys and values which will be set, to the constructor:

var user = new User({
	name : params.name,
	email : params.email
});
user.get('name');

####save Save a model with save(options) to the database like so:

var user = new User({
	name : params.name,
	email : params.email
});

user.save({
	success : function(){
		console.log("saved");
	},
	error : function(){
		console.log("save failed");
	}
});

Note: Only valid models will be saved to database. You should call Model.isValid() before to check that. ####isValid To check if a model is valid:

if( ! user.isValid() ){
	console.log(model.validationError)
}

####attach(name, mimeType, buffer) You can attach files to models which will be stored as attachments to couchdb via:

user.attach('profile', 'image/jpeg', imgBuffer);

After saving this to database you can get those attachments, for example in a template via:

user.attachments('profile').url

##Controllers Controllers take the main part in handling incoming requests and processing them.

A controller consists of a group of methods which handle one type of request defined in the route. Example:

module.exports = Yolo.Controller.extend({
	index : function(params){
		this.renderHTML("dashboard/index", {user : user });
	}
});

The params object passed to each method contains every parameter that might be passed to the server. In the methods you have access to the following methods: ###this.renderHTML(path, options = {}) Renders and returns a Html Template at path. Everything into the options object will be available as variable in the template. ###this.html(path, options {}); Shortcut for this.renderHTML. This Method is chainable.

###this.renderJSON(data = {}) Returns a JSON Object containing the options.

###this.json(data = {}) Shortcut for this.renderJSON. This Method is chainable.

###this.status(code) Sets the HTTP Status for that request. For Exmaple this.status(200). This Method is chainable.

###this.redirect(path) Redirects the Request to path

###this.error(code [, message]) Returns an http error with the given code and optional with the message.

###this.authorize(data = {}) authorizes/logins the request. data will be saved associated with the session.

###this.deAuthorize(cb) deAuthorizes and destroys the session and deletes the associated data. cb gets called after the destory has finished.

##Routes The routes file in the config directory contains all the individual routes to the controllers. A route consists of a key and a value. The key is the string we pass as "path" variable to express the path can also contain dynamic parts - read more about more here http://expressjs.com/api.html#app.VERB .

The value is either a object or an array of objects if the path should match different http methods.

###Example:

"user/:id" : { 	
	//routes to the controller named 'User' and the method named 'set'
	to : 'User.set',
	
	//the http method the route should match. can be either get, post, put or delete
	via : 'post',

	//set false if the request dont have to be authorized
	authorized : false
}

You can even match two routes to the same path but with different http methods like so:

'user/register' : [{
	to : 'Users.registerForm',
	via : 'get',
},
{
	to : 'Users.register',
	via : 'post',

}]

Note: Each route will be checked while booting Yolo if the to parameters matches a controller.

##Templates We use the ejs Template Engine extend with ejs-locals. Ejs lets you write javascript code into Templates like so:

<% if (currentUser) { %>
    <h2><%= currentUser.get("name") %></h2>
<% } %>

Unbuffered code for conditionals etc <% code %> Escapes html by default with <%= code %> Unescaped buffering with <%- code %>

Documentation can be found here: https://github.com/visionmedia/ejs and here: https://github.com/publicclass/express-partials