Permalink
Browse files

add app.use() docs. Closes #20

  • Loading branch information...
1 parent 3b4a7a4 commit 1f922ccde98fede7f5c7b499ccf8c1dbe9103584 @tj tj committed Oct 5, 2012
Showing with 149 additions and 2 deletions.
  1. +60 −2 api.html
  2. +87 −0 en/api/app-use.jade
  3. +1 −0 en/api/app.jade
  4. +1 −0 en/api/menu.jade
View
@@ -1,5 +1,5 @@
<!DOCTYPE html><html><head><title>Express - api reference</title><link rel="stylesheet" href="style.css"><link rel="stylesheet" href="//fonts.googleapis.com/css?family=Open+Sans:300,400,600,700&amp;subset=latin,latin-ext"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.0/jquery.min.js"></script><script src="app.js"></script><script src="retina.js"></script></head><body class="inner"><div class="bar"></div><section id="content"><header><section id="logo"><span class="express">express<em>3.0.0</em></span><span class="description">
-web application framework for <a href="http://nodejs.org">node </a></span></section><nav class="clearfix"><a href="/" class=""> Home</a><a href="/api.html" class="active"> API Reference</a><a href="/guide.html" class=""> Guide</a><a href="/applications.html" class=""> Applications</a><a href="/community.html" class=""> Community</a><a href="/faq.html" class=""> FAQ</a></nav></header><ul id="menu"><li id="app-api"> <a href="#express">Application</a><ul id="app-menu"><li><a href="#express">express()</a></li><li><a href="#app.set">app.set()</a></li><li><a href="#app.get">app.get()</a></li><li><a href="#app.enable">app.enable()</a></li><li><a href="#app.disable">app.disable()</a></li><li><a href="#app.enabled">app.enabled()</a></li><li><a href="#app.disabled">app.disabled()</a></li><li><a href="#app.configure">app.configure()</a></li><li><a href="#app.engine">app.engine()</a></li><li><a href="#app.param">app.param()</a></li><li><a href="#app-settings">application settings</a></li><li><a href="#app.VERB">application routing</a></li><li><a href="#app.all">app.all()</a></li><li><a href="#app.locals">app.locals</a></li><li><a href="#app.render">app.render()</a></li><li><a href="#app.routes">app.routes</a></li><li><a href="#app.listen">app.listen()</a></li></ul></li><li id="req-api"> <a href="#req.params">Request</a><ul id="req-menu"><li><a href="#req.params">req.params</a></li><li><a href="#req.query">req.query</a></li><li><a href="#req.body">req.body</a></li><li><a href="#req.files">req.files</a></li><li><a href="#req.param">req.param()</a></li><li><a href="#req.route">req.route</a></li><li><a href="#req.cookies">req.cookies</a></li><li><a href="#req.signedCookies">req.signedCookies</a></li><li><a href="#req.get">req.get()</a></li><li><a href="#req.accepts">req.accepts()</a></li><li><a href="#req.accepted">req.accepted</a></li><li><a href="#req.is">req.is()</a></li><li><a href="#req.ip">req.ip</a></li><li><a href="#req.ips">req.ips</a></li><li><a href="#req.path">req.path</a></li><li><a href="#req.host">req.host</a></li><li><a href="#req.fresh">req.fresh</a></li><li><a href="#req.stale">req.stale</a></li><li><a href="#req.xhr">req.xhr</a></li><li><a href="#req.protocol">req.protocol</a></li><li><a href="#req.secure">req.secure</a></li><li><a href="#req.subdomains">req.subdomains</a></li><li><a href="#req.originalUrl">req.originalUrl</a></li><li><a href="#req.acceptedLanguages">req.acceptedLanguages</a></li><li><a href="#req.acceptedCharsets">req.acceptedCharsets</a></li><li><a href="#req.acceptsCharset">req.acceptsCharset()</a></li><li><a href="#req.acceptsLanguage">req.acceptsLanguage()</a></li></ul></li><li id="res-api"> <a href="#res.status">Response</a><ul id="res-menu"><li><a href="#res.status">res.status()</a></li><li><a href="#res.set">res.set()</a></li><li><a href="#res.get">res.get()</a></li><li><a href="#res.cookie">res.cookie()</a></li><li><a href="#res.clearCookie">res.clearCookie()</a></li><li><a href="#res.redirect">res.redirect()</a></li><li><a href="#res.charset">res.charset</a></li><li><a href="#res.send">res.send()</a></li><li><a href="#res.json">res.json()</a></li><li><a href="#res.jsonp">res.jsonp()</a></li><li><a href="#res.type">res.type()</a></li><li><a href="#res.format">res.format()</a></li><li><a href="#res.attachment">res.attachment()</a></li><li><a href="#res.sendfile">res.sendfile()</a></li><li><a href="#res.download">res.download()</a></li><li><a href="#res.links">res.links()</a></li><li><a href="#res.locals">res.locals</a></li><li><a href="#res.render">res.render()</a></li></ul></li></ul><div id="right"><section><h3 id="express">express()</h3><p>Create an express application.
+web application framework for <a href="http://nodejs.org">node </a></span></section><nav class="clearfix"><a href="/" class=""> Home</a><a href="/api.html" class="active"> API Reference</a><a href="/guide.html" class=""> Guide</a><a href="/applications.html" class=""> Applications</a><a href="/community.html" class=""> Community</a><a href="/faq.html" class=""> FAQ</a></nav></header><ul id="menu"><li id="app-api"> <a href="#express">Application</a><ul id="app-menu"><li><a href="#express">express()</a></li><li><a href="#app.set">app.set()</a></li><li><a href="#app.get">app.get()</a></li><li><a href="#app.enable">app.enable()</a></li><li><a href="#app.disable">app.disable()</a></li><li><a href="#app.enabled">app.enabled()</a></li><li><a href="#app.disabled">app.disabled()</a></li><li><a href="#app.configure">app.configure()</a></li><li><a href="#app.use">app.use()</a></li><li><a href="#app.engine">app.engine()</a></li><li><a href="#app.param">app.param()</a></li><li><a href="#app-settings">application settings</a></li><li><a href="#app.VERB">application routing</a></li><li><a href="#app.all">app.all()</a></li><li><a href="#app.locals">app.locals</a></li><li><a href="#app.render">app.render()</a></li><li><a href="#app.routes">app.routes</a></li><li><a href="#app.listen">app.listen()</a></li></ul></li><li id="req-api"> <a href="#req.params">Request</a><ul id="req-menu"><li><a href="#req.params">req.params</a></li><li><a href="#req.query">req.query</a></li><li><a href="#req.body">req.body</a></li><li><a href="#req.files">req.files</a></li><li><a href="#req.param">req.param()</a></li><li><a href="#req.route">req.route</a></li><li><a href="#req.cookies">req.cookies</a></li><li><a href="#req.signedCookies">req.signedCookies</a></li><li><a href="#req.get">req.get()</a></li><li><a href="#req.accepts">req.accepts()</a></li><li><a href="#req.accepted">req.accepted</a></li><li><a href="#req.is">req.is()</a></li><li><a href="#req.ip">req.ip</a></li><li><a href="#req.ips">req.ips</a></li><li><a href="#req.path">req.path</a></li><li><a href="#req.host">req.host</a></li><li><a href="#req.fresh">req.fresh</a></li><li><a href="#req.stale">req.stale</a></li><li><a href="#req.xhr">req.xhr</a></li><li><a href="#req.protocol">req.protocol</a></li><li><a href="#req.secure">req.secure</a></li><li><a href="#req.subdomains">req.subdomains</a></li><li><a href="#req.originalUrl">req.originalUrl</a></li><li><a href="#req.acceptedLanguages">req.acceptedLanguages</a></li><li><a href="#req.acceptedCharsets">req.acceptedCharsets</a></li><li><a href="#req.acceptsCharset">req.acceptsCharset()</a></li><li><a href="#req.acceptsLanguage">req.acceptsLanguage()</a></li></ul></li><li id="res-api"> <a href="#res.status">Response</a><ul id="res-menu"><li><a href="#res.status">res.status()</a></li><li><a href="#res.set">res.set()</a></li><li><a href="#res.get">res.get()</a></li><li><a href="#res.cookie">res.cookie()</a></li><li><a href="#res.clearCookie">res.clearCookie()</a></li><li><a href="#res.redirect">res.redirect()</a></li><li><a href="#res.charset">res.charset</a></li><li><a href="#res.send">res.send()</a></li><li><a href="#res.json">res.json()</a></li><li><a href="#res.jsonp">res.jsonp()</a></li><li><a href="#res.type">res.type()</a></li><li><a href="#res.format">res.format()</a></li><li><a href="#res.attachment">res.attachment()</a></li><li><a href="#res.sendfile">res.sendfile()</a></li><li><a href="#res.download">res.download()</a></li><li><a href="#res.links">res.links()</a></li><li><a href="#res.locals">res.locals</a></li><li><a href="#res.render">res.render()</a></li></ul></li></ul><div id="right"><section><h3 id="express">express()</h3><p>Create an express application.
</p><pre class="js"><code>var express = require('express');
var app = express();
@@ -63,7 +63,65 @@
// production only
if ('production' == app.get('env')) {
app.set('db uri', 'n.n.n.n/prod');
-}</code></pre></section><section><h3 id="app-settings">settings</h3><p>The following settings are provided to alter how Express will behave:
+}</code></pre></section><section><h3 id="app.use">app.use([path], function)</h3><p>Use the given middleware <code>function</code>, with optional mount <code>path</code>,
+defaulting to "/".
+</p><pre class="js"><code>var express = require('express');
+var app = express();
+
+// simple logger
+app.use(function(req, res, next){
+ console.log('%s %s', req.method, req.url);
+ next();
+});
+
+// respond
+app.use(function(req, res, next){
+ res.send('Hello World');
+});
+
+app.listen(3000);
+</code></pre><p>The "mount" path is stripped and is <strong>not</strong> visible
+to the middleware <code>function</code>. The main effect of this feature is that
+mounted middleware may operate without code changes regardless of its "prefix"
+pathname.
+</p><p>Here's a concrete example, take the typical use-case of serving files in ./public
+using the <code>express.static()</code> middleware:
+</p><pre class="js"><code>// GET /javascripts/jquery.js
+// GET /style.css
+// GET /favicon.ico
+app.use(express.static(__dirname + '/public'));
+</code></pre><p>Say for example you wanted to prefix all static files with "/static", you could
+use the "mounting" feature to support this. Mounted middleware functions are <strong>not</strong>
+invoked unless the <code>req.url</code> contains this prefix, at which point
+it is stripped when the function is invoked. This affects this function only,
+subsequent middleware will see <code>req.url</code> with "/static" included
+unless they are mounted as well.
+</p><pre class="js"><code>// GET /static/javascripts/jquery.js
+// GET /static/style.css
+// GET /static/favicon.ico
+app.use('/static', express.static(__dirname + '/public'));
+</code></pre><p>The order of which middleware are "defined" using <code>app.use()</code> is
+very important, they are invoked sequentially, thus this defines middleware
+precedence. For example usually <code>express.logger()</code> is the very
+first middleware you would use, logging every request:
+</p><pre class="js"><code>app.use(express.logger());
+app.use(express.static(__dirname + '/public'));
+app.use(function(req, res){
+ res.send('Hello');
+});
+</code></pre><p>Now suppose you wanted ignore logging requests for static files, but to
+continue logging routes and middleware defined after <code>logger()</code>,
+you would simply move <code>static()</code> above:
+</p><pre class="js"><code>app.use(express.static(__dirname + '/public'));
+app.use(express.logger());
+app.use(function(req, res){
+ res.send('Hello');
+});
+</code></pre><p>Another concrete example would be serving files from multiple directories,
+giving precedence to "./public" over the others:
+</p><pre class="js"><code>app.use(express.static(__dirname + '/public'));
+app.use(express.static(__dirname + '/files'));
+app.use(express.static(__dirname + '/uploads'));</code></pre></section><section><h3 id="app-settings">settings</h3><p>The following settings are provided to alter how Express will behave:
</p><ul><li><code>env </code>Environment mode, defaults to <code>process.env.NODE_ENV</code> or "development"</li><li><code>trust proxy </code>Enables reverse proxy support, disabled by default</li><li><code>jsonp callback name </code>Changes the default callback name of <code>?callback=</code></li><li><code>json replacer </code>JSON replacer callback, null by default</li><li><code>json spaces </code>JSON response spaces for formatting, defaults to <code>2</code> in development, <code>0</code> in production</li><li><code>case sensitive routing </code>Enable case sensitivity, disabled by default, treating "/Foo" and "/foo" as the same</li><li><code>strict routing </code>Enable strict routing, by default "/foo" and "/foo/" are treated the same by the router </li><li><code>view cache </code>Enables view template compilation caching, enabled in production by default</li><li><code>view engine </code>The default engine extension to use when omitted</li><li><code>views </code>The view directory path</li></ul></section><section><h3 id="app.engine">app.engine(ext, callback)</h3><p>Register the given template engine <code>callback</code> as <code>ext</code>
By default will <code>require()</code> the engine based on the
View
@@ -0,0 +1,87 @@
+section
+ h3(id='app.use') app.use([path], function)
+
+ p.
+ Use the given middleware <code>function</code>, with optional mount <code>path</code>,
+ defaulting to "/".
+
+ +js.
+ var express = require('express');
+ var app = express();
+
+ // simple logger
+ app.use(function(req, res, next){
+ console.log('%s %s', req.method, req.url);
+ next();
+ });
+
+ // respond
+ app.use(function(req, res, next){
+ res.send('Hello World');
+ });
+
+ app.listen(3000);
+
+ p.
+ The "mount" path is stripped and is <strong>not</strong> visible
+ to the middleware <code>function</code>. The main effect of this feature is that
+ mounted middleware may operate without code changes regardless of its "prefix"
+ pathname.
+
+ p.
+ Here's a concrete example, take the typical use-case of serving files in ./public
+ using the <code>express.static()</code> middleware:
+
+ +js.
+ // GET /javascripts/jquery.js
+ // GET /style.css
+ // GET /favicon.ico
+ app.use(express.static(__dirname + '/public'));
+
+ p.
+ Say for example you wanted to prefix all static files with "/static", you could
+ use the "mounting" feature to support this. Mounted middleware functions are <strong>not</strong>
+ invoked unless the <code>req.url</code> contains this prefix, at which point
+ it is stripped when the function is invoked. This affects this function only,
+ subsequent middleware will see <code>req.url</code> with "/static" included
+ unless they are mounted as well.
+
+ +js.
+ // GET /static/javascripts/jquery.js
+ // GET /static/style.css
+ // GET /static/favicon.ico
+ app.use('/static', express.static(__dirname + '/public'));
+
+ p.
+ The order of which middleware are "defined" using <code>app.use()</code> is
+ very important, they are invoked sequentially, thus this defines middleware
+ precedence. For example usually <code>express.logger()</code> is the very
+ first middleware you would use, logging every request:
+
+ +js.
+ app.use(express.logger());
+ app.use(express.static(__dirname + '/public'));
+ app.use(function(req, res){
+ res.send('Hello');
+ });
+
+ p.
+ Now suppose you wanted ignore logging requests for static files, but to
+ continue logging routes and middleware defined after <code>logger()</code>,
+ you would simply move <code>static()</code> above:
+
+ +js.
+ app.use(express.static(__dirname + '/public'));
+ app.use(express.logger());
+ app.use(function(req, res){
+ res.send('Hello');
+ });
+
+ p.
+ Another concrete example would be serving files from multiple directories,
+ giving precedence to "./public" over the others:
+
+ +js.
+ app.use(express.static(__dirname + '/public'));
+ app.use(express.static(__dirname + '/files'));
+ app.use(express.static(__dirname + '/uploads'));
View
@@ -5,6 +5,7 @@ include ./app-disable
include ./app-enabled
include ./app-disabled
include ./app-configure
+include ./app-use
include ./app-settings
include ./app-engine
include ./app-param
View
@@ -10,6 +10,7 @@ ul#menu
li: a(href='#app.enabled') app.enabled()
li: a(href='#app.disabled') app.disabled()
li: a(href='#app.configure') app.configure()
+ li: a(href='#app.use') app.use()
li: a(href='#app.engine') app.engine()
li: a(href='#app.param') app.param()
li: a(href='#app-settings') application settings

0 comments on commit 1f922cc

Please sign in to comment.