dox-foundation-demo node_modules/express/lib/application.js

connect

declaration
connect

    Description

    Module dependencies.

    Source

    var connect = require('connect')
      , Router = require('./router')
      , methods = require('methods')
      , middleware = require('./middleware')
      , debug = require('debug')('express:application')
      , locals = require('./utils').locals
      , View = require('./view')
      , utils = connect.utils
      , path = require('path')
      , http = require('http')
      , join = path.join;

    app

    declaration
    app

      Description

      Application prototype.

      Source

      var app = exports = module.exports = {};

      use

      method
      app.use()
      • @param: {String,Function,Server}route
      • @param: {Function,Server}fn
      • @return: {app}for chaining

      Description

      Proxy connect#use() to apply settings to
      mounted applications.

      Source

      app.use = function(route, fn){
        var app;
      
        // default route to '/'
        if ('string' != typeof route) fn = route, route = '/';
      
        // express app
        if (fn.handle && fn.set) app = fn;
      
        // restore .app property on req and res
        if (app) {
          app.route = route;
          fn = function(req, res, next) {
            var orig = req.app;
            app.handle(req, res, function(err){
              req.__proto__ = orig.request;
              res.__proto__ = orig.response;
              next(err);
            });
          };
        }
      
        connect.proto.use.call(this, route, fn);
      
        // mounted an app
        if (app) {
          app.parent = this;
          app.emit('mount', this);
        }
      
        return this;
      };

      engine

      method
      app.engine()
      • @param: {String}ext
      • @param: {Function}fn
      • @return: {app}for chaining

      Description

      Register the given template engine callback fn
      as ext.

      By default will require() the engine based on the
      file extension. For example if you try to render
      a "foo.jade" file Express will invoke the following internally:

      app.engine('jade', require('jade').__express);
      

      For engines that do not provide .__express out of the box,
      or if you wish to "map" a different extension to the template engine
      you may use this method. For example mapping the EJS template engine to
      ".html" files:

      app.engine('html', require('ejs').renderFile);
      

      In this case EJS provides a .renderFile() method with
      the same signature that Express expects: (path, options, callback),
      though note that it aliases this method as ejs.__express internally
      so if you're using ".ejs" extensions you dont need to do anything.

      Some template engines do not follow this convention, the
      Consolidate.js
      library was created to map all of node's popular template
      engines to follow this convention, thus allowing them to
      work seamlessly within Express.

      Source

      app.engine = function(ext, fn){
        if ('function' != typeof fn) throw new Error('callback function required');
        if ('.' != ext[0]) ext = '.' + ext;
        this.engines[ext] = fn;
        return this;
      };

      param

      method
      app.param()
      • @param: {String,Array}name
      • @param: {Function}fn
      • @return: {app}for chaining

      Description

      Map the given param placeholder name(s) to the given callback(s).

      Parameter mapping is used to provide pre-conditions to routes
      which use normalized placeholders. For example a :user_id parameter
      could automatically load a user's information from the database without
      any additional code,

      The callback uses the same signature as middleware, the only differencing
      being that the value of the placeholder is passed, in this case the id
      of the user. Once the next() function is invoked, just like middleware
      it will continue on to execute the route, or subsequent parameter functions.

       app.param('user_id', function(req, res, next, id){
         User.find(id, function(err, user){
           if (err) {
             next(err);
           } else if (user) {
             req.user = user;
             next();
           } else {
             next(new Error('failed to load user'));
           }
         });
       });
      

      Source

      app.param = function(name, fn){
        var self = this
          , fns = [].slice.call(arguments, 1);
      
        // array
        if (Array.isArray(name)) {
          name.forEach(function(name){
            fns.forEach(function(fn){
              self.param(name, fn);
            });
          });
        // param logic
        } else if ('function' == typeof name) {
          this._router.param(name);
        // single
        } else {
          if (':' == name[0]) name = name.substr(1);
          fns.forEach(function(fn){
            self._router.param(name, fn);
          });
        }
      
        return this;
      };

      set

      method
      app.set()
      • @param: {String}setting
      • @param: {String}val
      • @return: {Server}for chaining

      Description

      Assign setting to val, or return setting's value.

      app.set('foo', 'bar');
      app.get('foo');
      // => "bar"

      Mounted servers inherit their parent server's settings.

      Source

      app.set = function(setting, val){
        if (1 == arguments.length) {
          return this.settings[setting];
        } else {
          this.settings[setting] = val;
          return this;
        }
      };

      enabled

      method
      app.enabled()
      • @param: {String}setting
      • @return: {Boolean}

      Description

      Check if setting is enabled (truthy).

      app.enabled('foo')
      // => false

      app.enable('foo')
      app.enabled('foo')
      // => true

      Source

      app.enabled = function(setting){
        return !!this.set(setting);
      };

      disabled

      method
      app.disabled()
      • @param: {String}setting
      • @return: {Boolean}

      Description

      Check if setting is disabled.

      app.disabled('foo')
      // => true

      app.enable('foo')
      app.disabled('foo')
      // => false

      Source

      app.disabled = function(setting){
        return !this.set(setting);
      };

      enable

      method
      app.enable()
      • @param: {String}setting
      • @return: {app}for chaining

      Description

      Enable setting.

      Source

      app.enable = function(setting){
        return this.set(setting, true);
      };

      disable

      method
      app.disable()
      • @param: {String}setting
      • @return: {app}for chaining

      Description

      Disable setting.

      Source

      app.disable = function(setting){
        return this.set(setting, false);
      };

      configure

      method
      app.configure()
      • @param: {String}env...
      • @param: {Function}fn
      • @return: {app}for chaining

      Description

      Configure callback for zero or more envs,
      when no env is specified that callback will
      be invoked for all environments. Any combination
      can be used multiple times, in any order desired.

      Examples:

      app.configure(function(){
      // executed for all envs
      });

      app.configure('stage', function(){
      // executed staging env
      });

      app.configure('stage', 'production', function(){
      // executed for stage and production
      });

      Note:

      These callbacks are invoked immediately, and
      are effectively sugar for the following:

      var env = process.env.NODE_ENV || 'development';
      
       switch (env) {
         case 'development':
           ...
           break;
         case 'stage':
           ...
           break;
         case 'production':
           ...
           break;
       }
      

      Source

      app.configure = function(env, fn){
        var envs = 'all'
          , args = [].slice.call(arguments);
        fn = args.pop();
        if (args.length) envs = args;
        if ('all' == envs || ~envs.indexOf(this.settings.env)) fn.call(this);
        return this;
      };

        Description

        Delegate .VERB(...) calls to router.VERB(...).

        Source

        methods.forEach(function(method){
          app[method] = function(path){
            if ('get' == method && 1 == arguments.length) return this.set(path);
        
            // deprecated
            if (Array.isArray(path)) {
              console.trace('passing an array to app.VERB() is deprecated and will be removed in 4.0');
            }
        
            // if no router attached yet, attach the router
            if (!this._usedRouter) this.use(this.router);
        
            // setup route
            this._router[method].apply(this._router, arguments);
            return this;
          };
        });

        all

        method
        app.all()
        • @param: {String}path
        • @param: {Function}...
        • @return: {app}for chaining

        Description

        Special-cased "all" method, applying the given route path,
        middleware, and callback to every HTTP method.

        Source

        app.all = function(path){
          var args = arguments;
          methods.forEach(function(method){
            app[method].apply(this, args);
          }, this);
          return this;
        };
        
        // del -> delete alias
        
        app.del = app.delete;

        render

        method
        app.render()
        • @param: {String}name
        • @param: {String,Function}optionsor fn
        • @param: {Function}fn

        Description

        Render the given view name name with options
        and a callback accepting an error and the
        rendered template string.

        Example:

        app.render('email', { name: 'Tobi' }, function(err, html){
        // ...
        })

        Source

        app.render = function(name, options, fn){
          var opts = {}
            , cache = this.cache
            , engines = this.engines
            , view;
        
          // support callback function as second arg
          if ('function' == typeof options) {
            fn = options, options = {};
          }
        
          // merge app.locals
          utils.merge(opts, this.locals);
        
          // merge options._locals
          if (options._locals) utils.merge(opts, options._locals);
        
          // merge options
          utils.merge(opts, options);
        
          // set .cache unless explicitly provided
          opts.cache = null == opts.cache
            ? this.enabled('view cache')
            : opts.cache;
        
          // primed cache
          if (opts.cache) view = cache[name];
        
          // view
          if (!view) {
            view = new (this.get('view'))(name, {
              defaultEngine: this.get('view engine'),
              root: this.get('views'),
              engines: engines
            });
        
            if (!view.path) {
              var err = new Error('Failed to lookup view "' + name + '"');
              err.view = view;
              return fn(err);
            }
        
            // prime the cache
            if (opts.cache) cache[name] = view;
          }
        
          // render
          try {
            view.render(opts, fn);
          } catch (err) {
            fn(err);
          }
        };

        listen

        method
        app.listen()
        • @return: {http.Server}

        Description

        Listen for connections.

        A node http.Server is returned, with this
        application (which is a Function) as its
        callback. If you wish to create both an HTTP
        and HTTPS server you may do so with the "http"
        and "https" modules as shown here:

        var http = require('http')
        , https = require('https')
        , express = require('express')
        , app = express();

        http.createServer(app).listen(80);
        https.createServer({ ... }, app).listen(443);

        Source

        app.listen = function(){
          var server = http.createServer(this);
          return server.listen.apply(server, arguments);
        };