Mazagran

Opinionated node.js framework

Installation

npm install mazagran --save

Getting started

create a server.js file

//require mazagran
var mazagran = require('mazagran');

var configuration = mazagran.configuration;
configuration.addConfig('config.json'); //add a config file

//create DI container
var DIFactory = mazagran.DIFactory;
var configurator = new DIFactory(configuration);
configurator.basePath = __dirname; //DI will look for the services realtive to this path,
var di = configurator.create();

//add routes
var router = mazagran.router;

router.match('/').to('homepage.index');
router.match('/:controller/:action(/:id)');


var App = mazagran.App;
var app = new App(di, router);

//run the application!
app.run();

and that's it

Now all you need to do is add controllers and templates

Recommended file structure

These are also assumed defaults:

root/
    - server.js
    - controllers/
    - templates/
    - logs/
    - www/

Routing

Routing uses https://github.com/kieran/barista so refer to that for documentation The routing system is unique in node.js world You don't have to specify a separate route for each controller, you can use one allmighty route

router.match('/:controller/:action(/:id)');

This will match any existing controller in your application If the controller name or action doesn't exist a 404 error will be thrown

Controllers

should look like this:

//assuming a route router.match('/:controller/:action(/:id)');

function Homepage() {

    /*
        will match /homepage/index
        name will come from either POST body or GET query ?name=Martin
    */
    this.index = function(name) {

        var data = {
                name: name
            };

        this.view.render('index', data);
    };

    //will match /homepage/list
    this.list = function() {
        var data = [
            {id: 1, name: 'peto'},
            {id: 2, name: 'miso'},
            {id: 3, name: 'tomas'},
            {id: 4, name: 'mato'},
            {id: 5, name: 'juro'}
        ];
        this.view.render('list', {persons: data});
    };

    //will match /homepage/user/1 id will be 1
    this.user = function(id) {
        this.view.render('user', {id: id});
    };
};

module.exports = Homepage;

Middleware

Mazagran is built on top of connect so it can accept any middleware compatible

just add to server.js

app.use(middleware);

default middlewares:

connect.static
connect.query
passport
quip
body-parser
connect-powered-by
connect-flash

Templating

Templating uses nunjucks engine http://jlongster.github.io/nunjucks/ Templates reside by default in templates/ directory and have extension of .html Templates support layouts, inheritance and blocks

You can generate urls in views using the url helper

<a href="{{helpers.url('main:index', {param: 'value', param2: 'value2'})}}">Main page</a>

or without parameters

<a href="{{helpers.url('main:index')}}">Main page</a>

The view engine is easily replacable it just needs to conform to the default view interface, see source

Dependency injection

Mazagran uses dependency injection https://github.com/sakren/node-dependency-injection Configuration https://github.com/sakren/node-easy-configuration

Mazagran also uses Configuration and DI for its internal services configuration

//default parameters, you can override them in your config.json
"parameters": {
        "server": {
            "host": "0.0.0.0",
            "port": 8080
        },
        "templates": {
            "path" : "./templates/",
            "defaultExtension" : "html"
        },
        "controllers": {
            "path": "./controllers"
        },
        "statics": {
            "path": "./www",
            "maxAge": 86400000
        },
        "logs": {
            "dir": "./logs"
        }
    },

default overridable services:

view
nunjucks
logger
async

Controllers and DI

You can require any service defined in DI config in your controllers by their names, they will be automatically autowired

function Homepage(view, logger) {
    console.log(view, logger);
}

Logging

Mazagran uses winston for logging By default there are 3 log files created access.log - logs accesses error.log - logs all error types info.log - logs info and debug messages

Async

Mazagran uses async library https://github.com/caolan/async to organize its code It's also available in DI container by default, so you can use it in your controllers

TODO

• implement error controller
• create sandbox