ifnode/manual.txt

Module:
    ifnode([options: Object])

Options:
    alias: String             "Nice" name of application                                      [optional] By default: equal to id
    project_folder: String    Full path to application root project folder                    [optional] By default: equal to process.argv[1]
    environment: String       Name of application config (folder ${project_folder}/config)    [optional]

    projectFolder             Alias of option .project_folder
    env: String               Alias of option .environment

Example:
var app = ifnode({
        project_folder: __dirname,
        alias: 'application',
        env: 'dev'
    });


Result of ifnode() (application instance):

Constants:
    .config                 Application config
    .server                 Instance of http.createServer
    .listener               Instance of express()
    .components             Hash of application components
    .models                 Hash of application models
    .controllers            Hash of application controllers
    .id                     Application id (is auto-generated by GUID function)
    .alias                  "Nice" name of application                                              By default: equal to id
    .project_folder         Full path to application root project folder                            By default: equal to process.argv[1]
    .backend_folder         Full path to application backend folder (folder with all components)    By default: ${project_folder}/protected

    .projectFolder          Alias of .project_folder
    .backendFolder          Alias of .backend_folder

Methods:
    .load()                                                           Load of application components (models, components and controllers)
    .run([callback: Function])                                        Run application server. Invoke .load() method if not invoked early
    .down([callback: Function])                                       Stop application server
    .extension(name: String)                                          Get application`s extension by name
    .register(name: String|module: Module|list_of_names: Array)       Attach modules for ifnode application. Module must be added to /node_modules folder or extensions (own application independent modules)
        Example: ifnode-auth, ifnode-mongoose, etc

        Usage:
        var ifnode = require('ifnode'),
            app = ifnode();

        app.register('ifnode-auth');

    .ext()                                                Alias of .extension()
    .require()                                            Alias of .extension()




Config:
    Description                  json object with all application options. Can contain any options (same of options parse by ifnode)
    Path to config`s folder      ${project_folder}/config

Example:

module.exports = {
    site: {
        port: 1010
    }
};

ifnode options:
    site:                         Description of site url
        local:                    Local url (use for start server)
            host:                 [optional] By default: localhost
            port:                 [optional] By default: 8080
        global:                   Global url ("nice" domain of site)
            host:                 [optional] By default: localhost
            port:                 [optional] By default: null
        ssl:                      SSL support (check https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener)
            key:                  Full or relative (at project_folder) path to key.pem  (just path, not need read as file)
            cert:                 Full or relative (at project_folder) path to cert.pem (just path, not need read as file)
            pfx:                  Full or relative (at project_folder) path to pfx.pem  (just path, not need read as file)
        Note: ifnode generate config option .site with options:
            .origin                   Equal to: http(s)://${host}[:${port}] (if set site.ssl - https, other - http)
            .url(pathname: String)    Method for generate link

        Example:
            // config/dev.js
            site:
                local:
                    port: 1010
                global:
                    host: 'nicedomainname.io'
                ssl:
                    key: 'ssl/key.pem',
                    cert: 'ssl/cert.pem'

            // app.js
            var app = ifnode({ env: 'dev' }),
                site = app.config.site;

            site.local.origin // https://localhost:1010
            site.local.url('/u/1') // https://localhost:1010/u/1
            site.global.origin // https://nicedomainname.io
            site.global.url('u/1') // https://nicedomainname.io/u/1

    application:                 Application (and express()) settings
        environment:             Name of environment. By default: name of config file (if config by file) or "local"
        express:                 Hash of express application settings (list: http://expressjs.com/4x/api.html#app.set)
            view engine:         By default: jade
            views:               By default: ${backend_folder}/views
            x-powered-by         By default: false (sorry, express :) )
            env:                 By default: name of config file (if config by file) or "local"
        folders:
            extensions:          Folder of extensions.  By default: ${backend_folder}/extensions
            components:          Folder of components.  By default: ${backend_folder}/components
            views:               Folder of views.       By default: ${backend_folder}/views
            controllers:         Folder of controllers. By default: ${backend_folder}/controllers
            models:              Folder of models.      By default: ${backend_folder}/models


    middleware:                             External middleware modules (examples: connect-multiparty, cookie-parser etc)
        ifnode middlewares:
            body:                           Build on body-parser module
                '${parser}': options        ${parser} - name of parser, options - hash of parser options. See here: https://github.com/expressjs/body-parser
            statics:                        Build on serve-statics module. Three variants of initializing of static files
                path: String                Options see here: https://github.com/expressjs/serve-static
                variants: Object
                    path1: options,
                    path2: options,
                    ...
                variant: Array
                    path,
                    path1,
                    { path2: options },
                    ...

    db:                                     Initialize options of databases (models schemas)
        name_of_db:                         Name of database connect
            schema: name of schema          Schema name (for choose of schema)
            config: schema config           Config of database connection

    components:                             Initialize options for components of ifnode
        name_of_component: options





Controller:
    app.Controller([options: Object])

    Controller can be extended by external plugins (example: ifnode-auth, ifnode-permissions etc)

Default options:
    root: String                 Root path to request                                    [optional] By default: /path/to/controller/
    name: String                 Name of controller                                      [optional] By default: path/to/controller
    router: Object               express.Router options.                                 [optional] By default: {}
                                 See here: http://expressjs.com/4x/api.html#router
    map: Object                  Mapping system for describe controller                  [optional] By default: null

    ajax: null|Boolean                   AJAX settings of controller`s actions                   [optional] By default: undefined
    before: String|Function|Array        Handlers which invoke before route handlers             [optional] By default: []

Note: controller`s filename !.js or ~.js are special. Those filenames not participate in forming name and root options.
    !.js: always initialize first in folder. Next loaded controllers into folders, and next files
    ~.js: always initialize last in folder

Example:
    /protected/controllers/api/v1/!.js
    var controller = app.Controller();
    controller.name // api/v1
    controller.root // /api/v1/

    /protected/controllers/api/v1/user.js
    var controller = app.Controller({ root: '/user' );
    controller.name // api/v1/user
    controller.root // /user

Static methods (use for creating controller`s plugins):
    .process_config              Add handler for controller`s config
    .populate                    Add route middleware for populate arguments own options
    .middleware                  Add route middleware for process request

    Example: see ifnode-auth plugin

Constants:
    .id                     Application id (is auto-generated by GUID function)
    .root                   Controller`s root path
    .name                   Controller`s name
    .router                 express.Router() instance

Instance methods:
    .param(param: String, handler: Function)            Analog of express`s app.param. See here: http://expressjs.com/4x/api.html#app.param
    .method(method: String [, path: String] [, options: Object], callback: Function [, callback: Function...])                 Method for creating controller`s route.
        method          Name of method. Current available: get, post, put, patch, delete
        path            Next part of url.                                                            [optional] By default: /
                        See here: http://expressjs.com/4x/api.html#router.METHOD
                        Note: instead of express`s variant of set, cannot be regular expression
        options         Special options for route                                                    [optional] By default: equal to controller`s options
        callback        Handler(s) of request

    "Syntax sugar" for .method():
    .get()
    .post()
    .put()
    .patch()
    .delete()
    .del()

    .end()                                                                  End of controller (if request cannot have handler invoke response.not_found() method. By default go to next controller to find request handler)
    .use([path: String,] callback: Function [, callback: Function...])      See here: http://expressjs.com/4x/api.html#app.use
    .error(handler: Function)                                               Invoke .error() handler when any request handler`s next() method of controller get instance of Error class. By default try find parent error handler, and if not find throw error in node.js

Note: All handlers request and response methods populated by same options.
    request:
        .data                                   "Syntax sugar". Return request.body, or request.query or null

    response:
        .ok([data: String|Object])              Set status 200 and return data
        .fail([data: String|Object])            Set status 400 and return data or text "Bad Request"
        .error([data: String|Object])           Set status 500 and return data or text "Server Internal Error"
        .unauthorized([data: String|Object])    Set status 401 and return data
        .forbidden([data: String|Object])       Set status 403 and return data
        .not_found([data: String|Object])       Set status 404 and return data

        .bad_request()                          Alias of .fail()
        .badRequest()                           Alias of .fail()
        .err()                                  Alias of .error()
        .notFound()                             Alias of .not_found()





Model:
    app.Model(model_options: Object [, schema_options: Object])

    All model`s schemas must be added by plugins

    model_options:              Options to create model. Specified by model`s schema. Recommended options:
        .name: String           Name of model
        .table: String          Name of table (for SQL databases: MySQL, PostgreSQL, etc)
        .collection: String     Name of collection (for NoSQL databases: mongodb, redis, etc)
        .columns: Object        Describe table or collection columns (example: mongoose columns)

    schema_options:             Options for build model`s schema. Specified by model`s schema.
        .db: String             Name of database (from config.db)                                          By default: first in config.db or "virtual" type
        .alias: String|Array    Aliases of model (in app.models)


Create own Schema for creating models:
    .schema                                 Name of schema
    .driver(db_config: Object)              Static method for initialize database driver. Add to Schema.fn returned driver   [optional]

    .fn                                     Alias of Schema.prototype
    .fn.initialize(model_config: Object)    Create model instance by schema                                                  [optional]
    .fn.compile()                           Return final model instance (this model can access by app.models)

    .fn.init()                              Alias of .fn.initialize()

Example:
    own-schema.js
    exports.schema = function(app, Schema) {
        Schema.schema = 'name-of-schema';
        Schema.driver = function(db_config) {
            ...
            return driver;
        };

        Schema.fn.initialize = function(model_config) { ... };
        Schema.fn.compile = function() {
            ...
            return ifnode_model;
        };
    };


    knex.js
    var _ = require('lodash'),
        knex = require('knex');

    exports.schema = function(app, Schema) {
        Schema.schema = 'knex';
        Schema.driver = function(db_config) {
            return knex(db_config);
        };

        Schema.fn.initialize = function(model_config) {
            this.table = model_config.table;
            this.driver = this._driver;
            this.all = function() {
                return this.driver(this.table);
            };
        };
        Schema.fn.compile = function() {
            return this;
        };
    };





Components:
    app.Component([options: Object])

    Special module for application. Initialize after models and can use them

Default options:
    name: String                   Name of controller                                      [optional] By default: id

Methods:
    .initialize(config: Object)    Function to initialize component (get config from ifnode config)