Application prototype.
Proxy connect#use()
to apply settings to
mounted applications.
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 seemlessly within Express.
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 samesignature 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'));
}
});
});
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.
Check if setting
is enabled (truthy).
app.enabled('foo')
// => false
app.enable('foo')
app.enabled('foo')
// => true
Check if setting
is disabled.
app.disabled('foo')
// => true
app.enable('foo')
app.disabled('foo')
// => false
Enable setting
.
Disable setting
.
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.
app.configure(function(){
// executed for all envs
});
app.configure('stage', function(){
// executed staging env
});
app.configure('stage', 'production', function(){
// executed for stage and production
});
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;
}
Special-cased "all" method, applying the given route path
,
middleware, and callback to every HTTP method.
Render the given view name
name with options
and a callback accepting an error and the
rendered template string.
app.render('email', { name: 'Tobi' }, function(err, html){
// ...
})
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);
http.createServer({ ... }, app).listen(443);
Request prototype.
Return request header.
The Referrer
header field is special-cased,
both Referrer
and Referer
are interchangeable.
req.get('Content-Type');
// => "text/plain"
req.get('content-type');
// => "text/plain"
req.get('Something');
// => undefined
Aliased as req.header()
.
Check if the given type(s)
is acceptable, returning
the best match when true, otherwise undefined
, in which
case you should respond with 406 "Not Acceptable".
The type
value may be a single mime type string
such as "application/json", the extension name
such as "json", a comma-delimted list such as "json, html, text/plain",
or an array ["json", "html", "text/plain"]
. When a list
or array is given the best match, if any is returned.
// Accept: text/html
req.accepts('html');
// => "html"
// Accept: text/*, application/json
req.accepts('html');
// => "html"
req.accepts('text/html');
// => "text/html"
req.accepts('json, text');
// => "json"
req.accepts('application/json');
// => "application/json"
// Accept: text/*, application/json
req.accepts('image/png');
req.accepts('png');
// => undefined
// Accept: text/*;q=.5, application/json
req.accepts(['html', 'json']);
req.accepts('html, json');
// => "json"
Check if the given charset
is acceptable,
otherwise you should respond with 406 "Not Acceptable".
Check if the given lang
is acceptable,
otherwise you should respond with 406 "Not Acceptable".
Return the value of param name
when present or defaultValue
.
- Checks route placeholders, ex: /user/:id
- Checks body params, ex: id=12, {"id":12}
- Checks query string params, ex: ?id=12
To utilize request bodies, req.body
should be an object. This can be done by using
the connect.bodyParser()
middleware.
Check if the incoming request contains the "Content-Type"
header field, and it contains the give mime type
.
// With Content-Type: text/html; charset=utf-8
req.is('html');
req.is('text/html');
req.is('text/*');
// => true
// When Content-Type is application/json
req.is('json');
req.is('application/json');
req.is('application/*');
// => true
req.is('html');
// => false
Response prototype.
Set status code
.
Send a response.
res.send(new Buffer('wahoo'));
res.send({ some: 'json' });
res.send('<p>some html</p>');
res.send(404, 'Sorry, cant find that');
res.send(404);
Send JSON response.
res.json(null);
res.json({ user: 'tj' });
res.json(500, 'oh noes!');
res.json(404, 'I dont have that');
Transfer the file at the given path
.
Automatically sets the Content-Type response header field.
The callback fn(err)
is invoked when the transfer is complete
or when an error occurs. Be sure to check res.sentHeader
if you wish to attempt responding, as the header and some data
may have already been transferred.
- `maxAge` defaulting to 0
- `root` root directory for relative filenames
The following example illustrates how res.sendfile()
may
be used as an alternative for the static()
middleware for
dynamic situations. The code backing res.sendfile()
is actually
the same code, so HTTP cache support etc is identical.
app.get('/user/:uid/photos/:file', function(req, res){
var uid = req.params.uid
, file = req.params.file;
req.user.mayViewFilesFrom(uid, function(yes){
if (yes) {
res.sendfile('/uploads/' + uid + '/' + file);
} else {
res.send(403, 'Sorry! you cant see that.');
}
});
});
Transfer the file at the given path
as an attachment.
Optionally providing an alternate attachment filename
,
and optional callback fn(err)
. The callback is invoked
when the data transfer is complete, or when an error has
ocurred. Be sure to check res.headerSent
if you plan to respond.
This method uses res.sendfile()
.
Respond to the Acceptable formats using an obj
of mime-type callbacks.
This method uses req.accepted
, an array of
acceptable types ordered by their quality values.
When "Accept" is not present the first callback
is invoked, otherwise the first match is used. When
no match is performed the server responds with
406 "Not Acceptable".
Content-Type is set for you, however if you choose
you may alter this within the callback using res.type()
or res.set('Content-Type', ...)
.
res.format({
'text/plain': function(){
res.send('hey');
},
'text/html': function(){
res.send('<p>hey</p>');
},
'appliation/json': function(){
res.send({ message: 'hey' });
}
});
In addition to canonicalized MIME types you may also use extnames mapped to these types:
res.format({
text: function(){
res.send('hey');
},
html: function(){
res.send('<p>hey</p>');
},
json: function(){
res.send({ message: 'hey' });
}
});
By default Express passes an Error
with a .status
of 406 to next(err)
if a match is not made, however you may
provide an optional callback fn
to
be invoked instead.
Set Content-Disposition header to attachment with optional filename
.
Set header field
to val
, or pass
an object of header fields.
res.set('Accept', 'application/json');
res.set({ Accept: 'text/plain', 'X-API-Key': 'tobi' });
Aliased as res.header()
.
Get value for header field
.
Clear cookie name
.
Set cookie name
to val
, with the given options
.
- `maxAge` max-age in milliseconds, converted to `expires`
- `signed` sign the cookie
- `path` defaults to "/"
// "Remember Me" for 15 minutes
res.cookie('rememberme', '1', { expires: new Date(Date.now() + 900000), httpOnly: true });
// save as above
res.cookie('rememberme', '1', { maxAge: 900000, httpOnly: true })
Redirect to the given url
with optional response status
defaulting to 302.
The given url
can also be the name of a mapped url, for
example by default express supports "back" which redirects
to the Referrer or Referer headers or "/".
res.redirect('/foo/bar');
res.redirect('http://example.com');
res.redirect(301, 'http://example.com');
res.redirect('../login'); // /blog/post/1 -> /blog/login
When an application is mounted, and `res.redirect()`
is given a path that does _not_ lead with "/". For
example suppose a "blog" app is mounted at "/blog",
the following redirect would result in "/blog/login":
res.redirect('login');
While the leading slash would result in a redirect to "/login":
res.redirect('/login');
Render view
with the given options
and optional callback fn
.
When a callback function is given a response will not be made
automatically, otherwise a response of 200 and text/html is given.
status
Response status code (res.statusCode
)charset
Set the charset (res.charset
)
cache
boolean hinting to the engine it should cachefilename
filename of the view being rendered