Copy 5x documentation files

_includes/api/en/5x/app-METHOD.md

@@ -0,0 +1,62 @@
+<h3 id='app.METHOD'>app.METHOD(path, callback [, callback ...])</h3>
+
+Routes an HTTP request, where METHOD is the HTTP method of the request, such as GET,
+PUT, POST, and so on, in lowercase. Thus, the actual methods are `app.get()`,
+`app.post()`, `app.put()`, and so on.  See [Routing methods](#routing-methods) below for the complete list.
+
+{% include api/en/4x/routing-args.html %}
+
+#### Routing methods
+
+Express supports the following routing methods corresponding to the HTTP methods of the same names:
+
+<table style="border: 0px; background: none">
+<tr>
+<td style="background: none; border: 0px;" markdown="1">
+* `checkout`
+* `copy`
+* `delete`
+* `get`
+* `head`
+* `lock`
+* `merge`
+* `mkactivity`
+</td>
+<td style="background: none; border: 0px;" markdown="1">
+* `mkcol`
+* `move`
+* `m-search`
+* `notify`
+* `options`
+* `patch`
+* `post`
+</td>
+<td style="background: none; border: 0px;" markdown="1">
+* `purge`
+* `put`
+* `report`
+* `search`
+* `subscribe`
+* `trace`
+* `unlock`
+* `unsubscribe`
+</td>
+</tr>
+</table>
+
+The API documentation has explicit entries only for the most popular HTTP methods `app.get()`,
+`app.post()`, `app.put()`, and `app.delete()`.
+However, the other methods listed above work in exactly the same way.
+
+To route methods that translate to invalid JavaScript variable names, use the bracket notation. For example, `app['m-search']('/', function ...`.
+
+<div class="doc-box doc-info" markdown="1">
+  The `app.get()` function is automatically called for the HTTP `HEAD` method in addition to the `GET`
+  method if `app.head()` was not called for the path before `app.get()`.
+</div>
+
+The method, `app.all()`, is not derived from any HTTP method and loads middleware at
+the specified path for _all_ HTTP request methods.
+For more information, see [app.all](#app.all).
+
+For more information on routing, see the [routing guide](/guide/routing.html).

_includes/api/en/5x/app-all.md

@@ -0,0 +1,44 @@
+<h3 id='app.all'>app.all(path, callback [, callback ...])</h3>
+
+This method is like the standard [app.METHOD()](#app.METHOD) methods,
+except it matches all HTTP verbs.
+
+{% include api/en/4x/routing-args.html %}
+
+#### Examples
+
+The following callback is executed for requests to `/secret` whether using
+GET, POST, PUT, DELETE, or any other HTTP request method:
+
+```js
+app.all('/secret', function (req, res, next) {
+  console.log('Accessing the secret section ...')
+  next() // pass control to the next handler
+})
+```
+
+The `app.all()` method is useful for mapping "global" logic for specific path prefixes or arbitrary matches.  For example, if you put the following at the top of all other
+route definitions, it requires that all routes from that point on
+require authentication, and automatically load a user. Keep in mind
+that these callbacks do not have to act as end-points: `loadUser`
+can perform a task, then call `next()` to continue matching subsequent
+routes.
+
+```js
+app.all('*', requireAuthentication, loadUser)
+```
+
+Or the equivalent:
+
+```js
+app.all('*', requireAuthentication)
+app.all('*', loadUser)
+```
+
+Another example is white-listed "global" functionality.
+The example is similar to the ones above, but it only restricts paths that start with
+"/api":
+
+```js
+app.all('/api/*', requireAuthentication)
+```

_includes/api/en/5x/app-delete-method.md

@@ -0,0 +1,14 @@
+<h3 id='app.delete.method'>app.delete(path, callback [, callback ...])</h3>
+
+Routes HTTP DELETE requests to the specified path with the specified callback functions.
+For more information, see the [routing guide](/guide/routing.html).
+
+{% include api/en/4x/routing-args.html %}
+
+#### Example
+
+```js
+app.delete('/', function (req, res) {
+  res.send('DELETE request to homepage')
+})
+```

_includes/api/en/5x/app-disable.md

@@ -0,0 +1,12 @@
+<h3 id='app.disable'>app.disable(name)</h3>
+
+Sets the Boolean setting `name` to `false`, where `name` is one of the properties from the [app settings table](#app.settings.table).
+Calling `app.set('foo', false)` for a Boolean property is the same as calling `app.disable('foo')`.
+
+For example:
+
+```js
+app.disable('trust proxy')
+app.get('trust proxy')
+// => false
+```

_includes/api/en/5x/app-disabled.md

@@ -0,0 +1,13 @@
+<h3 id='app.disabled'>app.disabled(name)</h3>
+
+Returns `true` if the Boolean setting `name` is disabled (`false`), where `name` is one of the properties from
+the [app settings table](#app.settings.table).
+
+```js
+app.disabled('trust proxy')
+// => true
+
+app.enable('trust proxy')
+app.disabled('trust proxy')
+// => false
+```

_includes/api/en/5x/app-enable.md

@@ -0,0 +1,10 @@
+<h3 id='app.enable'>app.enable(name)</h3>
+
+Sets the Boolean setting `name` to `true`, where `name` is one of the properties from the [app settings table](#app.settings.table).
+Calling `app.set('foo', true)` for a Boolean property is the same as calling `app.enable('foo')`.
+
+```js
+app.enable('trust proxy')
+app.get('trust proxy')
+// => true
+```

_includes/api/en/5x/app-enabled.md

@@ -0,0 +1,13 @@
+<h3 id='app.enabled'>app.enabled(name)</h3>
+
+Returns `true` if the setting `name` is enabled (`true`), where `name` is one of the
+properties from the [app settings table](#app.settings.table).
+
+```js
+app.enabled('trust proxy')
+// => false
+
+app.enable('trust proxy')
+app.enabled('trust proxy')
+// => true
+```

_includes/api/en/5x/app-engine.md

@@ -0,0 +1,36 @@
+<h3 id='app.engine'>app.engine(ext, callback)</h3>
+
+Registers the given template engine `callback` as `ext`.
+
+By default, Express will `require()` the engine based on the file extension.
+For example, if you try to render a "foo.pug" file, Express invokes the
+following internally, and caches the `require()` on subsequent calls to increase
+performance.
+
+```js
+app.engine('pug', require('pug').__express)
+```
+
+Use this method for engines that do not provide `.__express` out of the box,
+or if you wish to "map" a different extension to the template engine.
+
+For example, to map the EJS template engine to ".html" files:
+
+```js
+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 don't need to do anything.
+
+Some template engines do not follow this convention.  The
+[consolidate.js](https://github.com/tj/consolidate.js) library maps Node template engines to follow this convention,
+so they work seamlessly with Express.
+
+```js
+var engines = require('consolidate')
+app.engine('haml', engines.haml)
+app.engine('html', engines.hogan)
+```

_includes/api/en/5x/app-get-method.md

@@ -0,0 +1,15 @@
+<h3 id='app.get.method'>app.get(path, callback [, callback ...])</h3>
+
+Routes HTTP GET requests to the specified path with the specified callback functions.
+
+{% include api/en/4x/routing-args.html %}
+
+For more information, see the [routing guide](/guide/routing.html).
+
+#### Example
+
+```js
+app.get('/', function (req, res) {
+  res.send('GET request to homepage')
+})
+```

_includes/api/en/5x/app-get.md

@@ -0,0 +1,13 @@
+<h3 id='app.get'>app.get(name)</h3>
+
+Returns the value of `name` app setting, where `name` is one of the strings in the
+[app settings table](#app.settings.table). For example:
+
+```js
+app.get('title')
+// => undefined
+
+app.set('title', 'My Site')
+app.get('title')
+// => "My Site"
+```

_includes/api/en/5x/app-listen.md

@@ -0,0 +1,55 @@
+<h3 id='app.listen_path_callback'>app.listen(path, [callback])</h3>
+
+Starts a UNIX socket and listens for connections on the given path.
+This method is identical to Node's [http.Server.listen()](https://nodejs.org/api/http.html#http_server_listen).
+
+```js
+var express = require('express')
+var app = express()
+app.listen('/tmp/sock')
+```
+
+<h3 id='app.listen'>app.listen([port[, host[, backlog]]][, callback])</h3>
+
+Binds and listens for connections on the specified host and port.
+This method is identical to Node's [http.Server.listen()](https://nodejs.org/api/http.html#http_server_listen).
+
+If port is omitted or is 0, the operating system will assign an arbitrary unused
+port, which is useful for cases like automated tasks (tests, etc.).
+
+```js
+var express = require('express')
+var app = express()
+app.listen(3000)
+```
+
+The `app` returned by `express()` is in fact a JavaScript
+`Function`, designed to be passed to Node's HTTP servers as a callback
+to handle requests. This makes it easy to provide both HTTP and HTTPS versions of
+your app with the same code base, as the app does not inherit from these
+(it is simply a callback):
+
+```js
+var express = require('express')
+var https = require('https')
+var http = require('http')
+var app = express()
+
+http.createServer(app).listen(80)
+https.createServer(options, app).listen(443)
+```
+
+The `app.listen()` method returns an [http.Server](https://nodejs.org/api/http.html#http_class_http_server) object and (for HTTP) is a convenience method for the following:
+
+```js
+app.listen = function () {
+  var server = http.createServer(this)
+  return server.listen.apply(server, arguments)
+}
+```
+
+<div class="doc-box doc-info" markdown="1">
+NOTE: All the forms of Node's
+[http.Server.listen()](https://nodejs.org/api/http.html#http_server_listen)
+method are in fact actually supported.
+</div>

_includes/api/en/5x/app-locals.md

@@ -0,0 +1,25 @@
+<h3 id='app.locals'>app.locals</h3>
+
+The `app.locals` object has properties that are local variables within the application.
+
+```js
+console.dir(app.locals.title)
+// => 'My App'
+
+console.dir(app.locals.email)
+// => '[email protected]'
+```
+
+Once set, the value of `app.locals` properties persist throughout the life of the application,
+in contrast with [res.locals](#res.locals) properties that
+are valid only for the lifetime of the request.
+
+You can access local variables in templates rendered within the application.
+This is useful for providing helper functions to templates, as well as application-level data.
+Local variables are available in middleware via `req.app.locals` (see [req.app](#req.app))
+
+```js
+app.locals.title = 'My App'
+app.locals.strftime = require('strftime')
+app.locals.email = '[email protected]'
+```

_includes/api/en/5x/app-mountpath.md

@@ -0,0 +1,45 @@
+<h3 id='app.mountpath'>app.mountpath</h3>
+
+The `app.mountpath` property contains one or more path patterns on which a sub-app was mounted.
+
+<div class="doc-box doc-info" markdown="1">
+  A sub-app is an instance of `express` that may be used for handling the request to a route.
+</div>
+
+```js
+var express = require('express')
+
+var app = express() // the main app
+var admin = express() // the sub app
+
+admin.get('/', function (req, res) {
+  console.log(admin.mountpath) // /admin
+  res.send('Admin Homepage')
+})
+
+app.use('/admin', admin) // mount the sub app
+```
+
+It is similar to the [baseUrl](#req.baseUrl) property of the `req` object, except `req.baseUrl`
+returns the matched URL path, instead of the matched patterns.
+
+If a sub-app is mounted on multiple path patterns, `app.mountpath` returns the list of
+patterns it is mounted on, as shown in the following example.
+
+```js
+var admin = express()
+
+admin.get('/', function (req, res) {
+  console.log(admin.mountpath) // [ '/adm*n', '/manager' ]
+  res.send('Admin Homepage')
+})
+
+var secret = express()
+secret.get('/', function (req, res) {
+  console.log(secret.mountpath) // /secr*t
+  res.send('Admin Secret')
+})
+
+admin.use('/secr*t', secret) // load the 'secret' router on '/secr*t', on the 'admin' sub app
+app.use(['/adm*n', '/manager'], admin) // load the 'admin' router on '/adm*n' and '/manager', on the parent app
+```

_includes/api/en/5x/app-onmount.md

@@ -0,0 +1,29 @@
+<h3 id='app.onmount'>app.on('mount', callback(parent))</h3>
+
+The `mount` event is fired on a sub-app, when it is mounted on a parent app. The parent app is passed to the callback function.
+
+<div class="doc-box doc-info" markdown="1">
+**NOTE**
+
+Sub-apps will:
+
+* Not inherit the value of settings that have a default value.  You must set the value in the sub-app.
+* Inherit the value of settings with no default value.
+
+For details, see [Application settings](/en/4x/api.html#app.settings.table).
+</div>
+
+```js
+var admin = express()
+
+admin.on('mount', function (parent) {
+  console.log('Admin Mounted')
+  console.log(parent) // refers to the parent app
+})
+
+admin.get('/', function (req, res) {
+  res.send('Admin Homepage')
+})
+
+app.use('/admin', admin)
+```