##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