From f2e62c73f5c7c5ce27b2af8cd757d63ad30ba203 Mon Sep 17 00:00:00 2001 From: Sebastian Beltran Date: Fri, 20 Sep 2024 20:09:48 -0500 Subject: [PATCH 1/6] update route guide --- en/guide/routing.md | 75 ++++++++++++++++++++++++++------------------- 1 file changed, 44 insertions(+), 31 deletions(-) diff --git a/en/guide/routing.md b/en/guide/routing.md index 6402ab61c0..30ddc2778b 100755 --- a/en/guide/routing.md +++ b/en/guide/routing.md @@ -13,7 +13,7 @@ For an introduction to routing, see [Basic routing](/{{ page.lang }}/starter/bas You define routing using methods of the Express `app` object that correspond to HTTP methods; for example, `app.get()` to handle GET requests and `app.post` to handle POST requests. For a full list, -see [app.METHOD](/{{ page.lang }}/4x/api.html#app.METHOD). You can also use [app.all()](/{{ page.lang }}/4x/api.html#app.all) to handle all HTTP methods and [app.use()](/{{ page.lang }}/4x/api.html#app.use) to +see [app.METHOD](/{{ page.lang }}/5x/api.html#app.METHOD). You can also use [app.all()](/{{ page.lang }}/5x/api.html#app.all) to handle all HTTP methods and [app.use()](/{{ page.lang }}/5x/api.html#app.use) to specify middleware as the callback function (See [Using middleware](/{{ page.lang }}/guide/using-middleware.html) for details). These routing methods specify a callback function (sometimes called "handler functions") called when the application receives a request to the specified route (endpoint) and HTTP method. In other words, the application "listens" for requests that match the specified route(s) and method(s), and when it detects a match, it calls the specified callback function. @@ -38,7 +38,7 @@ app.get('/', (req, res) => { A route method is derived from one of the HTTP methods, and is attached to an instance of the `express` class. -The following code is an example of routes that are defined for the GET and the POST methods to the root of the app. +The following code is an example of routes that are defined for the `GET` and the `POST` methods to the root of the app. ```js // GET method route @@ -53,9 +53,9 @@ app.post('/', (req, res) => { ``` Express supports methods that correspond to all HTTP request methods: `get`, `post`, and so on. -For a full list, see [app.METHOD](/{{ page.lang }}/4x/api.html#app.METHOD). +For a full list, see [app.METHOD](/{{ page.lang }}/5x/api.html#app.METHOD). -There is a special routing method, `app.all()`, used to load middleware functions at a path for _all_ HTTP request methods. For example, the following handler is executed for requests to the route "/secret" whether using GET, POST, PUT, DELETE, or any other HTTP request method supported in the [http module](https://nodejs.org/api/http.html#http_http_methods). +There is a special routing method, `app.all()`, used to load middleware functions at a path for _all_ HTTP request methods. For example, the following handler is executed for requests to the route `"/secret"` whether using `GET`, `POST`, `PUT`, `DELETE`, or any other HTTP request method supported in the [http module](https://nodejs.org/api/http.html#http_http_methods). ```js app.all('/secret', (req, res, next) => { @@ -68,19 +68,21 @@ app.all('/secret', (req, res, next) => { Route paths, in combination with a request method, define the endpoints at which requests can be made. Route paths can be strings, string patterns, or regular expressions. -The characters `?`, `+`, `*`, and `()` are subsets of their regular expression counterparts. The hyphen (`-`) and the dot (`.`) are interpreted literally by string-based paths. +{% capture caution-character %} In express 5, the characters `?`, `+`, `*`, `[]`, and `()` are handled differently than in version 4, please review the [migration guide](/{{ page.lang }}/guide/migrating-5.html#path-syntax) for more information.{% endcapture %} -If you need to use the dollar character (`$`) in a path string, enclose it escaped within `([` and `])`. For example, the path string for requests at "`/data/$book`", would be "`/data/([\$])book`". +{% include admonitions/caution.html content=caution-character %} -
+If you need to use the dollar character (`$`) in a path string, escape it with `\`. For example, the path string for requests at `/data/$book`, would be `/data/\$book`. + +{% capture note-path-to-regexp %} Express uses [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) for matching the route paths; see the path-to-regexp documentation for all the possibilities in defining route paths. [Express Route Tester](http://forbeslindesay.github.io/express-route-tester/) is a handy tool for testing basic Express routes, although it does not support pattern matching. -
+{% endcapture %} -
-Query strings are not part of the route path. -
+{% include admonitions/note.html content=note-path-to-regexp %} -Here are some examples of route paths based on strings. +{% include admonitions/warning.html content="Query strings are not part of the route path." %} + +### Route paths based on strings This route path will match requests to the root route, `/`. @@ -106,7 +108,13 @@ app.get('/random.text', (req, res) => { }) ``` -Here are some examples of route paths based on string patterns. +### Route paths based on string patterns + +{% capture caution-string-patterns %} The string patterns in Express 5 no longer work. Please refer to the [migration guide](/{{ page.lang }}/guide/migrating-5.html#path-syntax) for more information.{% endcapture %} + +{% include admonitions/caution.html content=caution-string-patterns %} + +{% include admonitions/caution.html content="The string patterns in Express 5 no longer work. Please refer to the migration guide for more information" %} This route path will match `acd` and `abcd`. @@ -140,7 +148,7 @@ app.get('/ab(cd)?e', (req, res) => { }) ``` -Examples of route paths based on regular expressions: +### Route paths based on regular expressions This route path will match anything with an "a" in it. @@ -194,6 +202,11 @@ Request URL: http://localhost:3000/plantae/Prunus.persica req.params: { "genus": "Prunus", "species": "persica" } ``` +{% capture warning-regexp %} +In express 5, Regexp characters are not supported in route paths, for more information please refer to the [migration guide](/{{ page.lang }}/guide/migrating-5.html#path-syntax).{% endcapture %} + +{% include admonitions/caution.html content=warning-regexp %} + To have more control over the exact string that can be matched by a route parameter, you can append a regular expression in parentheses (`()`): ``` @@ -202,13 +215,13 @@ Request URL: http://localhost:3000/user/42 req.params: {"userId": "42"} ``` -
-Because the regular expression is usually part of a literal string, be sure to escape any \ characters with an additional backslash, for example \\d+. -
+{% include admonitions/warning.html content="Because the regular expression is usually part of a literal string, be sure to escape any `\` characters with an additional backslash, for example `\\d+`." %} -
-In Express 4.x, the * character in regular expressions is not interpreted in the usual way. As a workaround, use {0,} instead of *. This will likely be fixed in Express 5. -
+{% capture warning-version %} +In Express 4.x, the `*` character in regular expressions is not interpreted in the usual way. As a workaround, use `{0,}` instead of `*`. This will likely be fixed in Express 5. +{% endcapture %} + +{% include admonitions/warning.html content=warning-version %}

Route handlers

@@ -282,20 +295,20 @@ The methods on the response object (`res`) in the following table can send a res | Method | Description | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -| [res.download()](/{{ page.lang }}/4x/api.html#res.download) | Prompt a file to be downloaded. | -| [res.end()](/{{ page.lang }}/4x/api.html#res.end) | End the response process. | -| [res.json()](/{{ page.lang }}/4x/api.html#res.json) | Send a JSON response. | -| [res.jsonp()](/{{ page.lang }}/4x/api.html#res.jsonp) | Send a JSON response with JSONP support. | -| [res.redirect()](/{{ page.lang }}/4x/api.html#res.redirect) | Redirect a request. | -| [res.render()](/{{ page.lang }}/4x/api.html#res.render) | Render a view template. | -| [res.send()](/{{ page.lang }}/4x/api.html#res.send) | Send a response of various types. | -| [res.sendFile()](/{{ page.lang }}/4x/api.html#res.sendFile) | Send a file as an octet stream. | -| [res.sendStatus()](/{{ page.lang }}/4x/api.html#res.sendStatus) | Set the response status code and send its string representation as the response body. | +| [res.download()](/{{ page.lang }}/5x/api.html#res.download) | Prompt a file to be downloaded. | +| [res.end()](/{{ page.lang }}/5x/api.html#res.end) | End the response process. | +| [res.json()](/{{ page.lang }}/5x/api.html#res.json) | Send a JSON response. | +| [res.jsonp()](/{{ page.lang }}/5x/api.html#res.jsonp) | Send a JSON response with JSONP support. | +| [res.redirect()](/{{ page.lang }}/5x/api.html#res.redirect) | Redirect a request. | +| [res.render()](/{{ page.lang }}/5x/api.html#res.render) | Render a view template. | +| [res.send()](/{{ page.lang }}/5x/api.html#res.send) | Send a response of various types. | + | [res.sendFile()](/{{ page.lang }}/5x/api.html#res.sendFile) | Send a file as an octet stream. | +| [res.sendStatus()](/{{ page.lang }}/5x/api.html#res.sendStatus) | Set the response status code and send its string representation as the response body. |

app.route()

You can create chainable route handlers for a route path by using `app.route()`. -Because the path is specified at a single location, creating modular routes is helpful, as is reducing redundancy and typos. For more information about routes, see: [Router() documentation](/{{ page.lang }}/4x/api.html#router). +Because the path is specified at a single location, creating modular routes is helpful, as is reducing redundancy and typos. For more information about routes, see: [Router() documentation](/{{ page.lang }}/5x/api.html#router). Here is an example of chained route handlers that are defined by using `app.route()`. @@ -355,7 +368,7 @@ app.use('/birds', birds) The app will now be able to handle requests to `/birds` and `/birds/about`, as well as call the `timeLog` middleware function that is specific to the route. -But if the parent route `/birds` has path parameters, it will not be accessible by default from the sub-routes. To make it accessible, you will need to pass the `mergeParams` option to the Router constructor [reference](https://expressjs.com/en/4x/api.html#app.use). +But if the parent route `/birds` has path parameters, it will not be accessible by default from the sub-routes. To make it accessible, you will need to pass the `mergeParams` option to the Router constructor [reference](/{{ page.lang }}/5x/api.html#app.use). ```js const router = express.Router({ mergeParams: true }) From 782a5f968bfec5923ed16ff66a563e995c3b337d Mon Sep 17 00:00:00 2001 From: Sebastian Beltran Date: Fri, 20 Sep 2024 20:16:25 -0500 Subject: [PATCH 2/6] remove duplicate note --- en/guide/routing.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/en/guide/routing.md b/en/guide/routing.md index 30ddc2778b..ab01aae691 100755 --- a/en/guide/routing.md +++ b/en/guide/routing.md @@ -114,8 +114,6 @@ app.get('/random.text', (req, res) => { {% include admonitions/caution.html content=caution-string-patterns %} -{% include admonitions/caution.html content="The string patterns in Express 5 no longer work. Please refer to the migration guide for more information" %} - This route path will match `acd` and `abcd`. ```js From c64a387d83fa22369ce94eaa74e2664f91caaa92 Mon Sep 17 00:00:00 2001 From: Sebastian Beltran Date: Wed, 16 Oct 2024 18:07:39 -0500 Subject: [PATCH 3/6] Update en/guide/routing.md Co-authored-by: Blake Embrey --- en/guide/routing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/guide/routing.md b/en/guide/routing.md index ab01aae691..4005d1737c 100755 --- a/en/guide/routing.md +++ b/en/guide/routing.md @@ -300,7 +300,7 @@ The methods on the response object (`res`) in the following table can send a res | [res.redirect()](/{{ page.lang }}/5x/api.html#res.redirect) | Redirect a request. | | [res.render()](/{{ page.lang }}/5x/api.html#res.render) | Render a view template. | | [res.send()](/{{ page.lang }}/5x/api.html#res.send) | Send a response of various types. | - | [res.sendFile()](/{{ page.lang }}/5x/api.html#res.sendFile) | Send a file as an octet stream. | +| [res.sendFile()](/{{ page.lang }}/5x/api.html#res.sendFile) | Send a file as an octet stream. | | [res.sendStatus()](/{{ page.lang }}/5x/api.html#res.sendStatus) | Set the response status code and send its string representation as the response body. |

app.route()

From 0c38485046c3758d6e6243d34c8496e6e6296b72 Mon Sep 17 00:00:00 2001 From: Sebastian Beltran Date: Wed, 16 Oct 2024 18:20:33 -0500 Subject: [PATCH 4/6] update dollar message --- en/guide/routing.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/en/guide/routing.md b/en/guide/routing.md index 4005d1737c..936512670e 100755 --- a/en/guide/routing.md +++ b/en/guide/routing.md @@ -72,7 +72,10 @@ Route paths, in combination with a request method, define the endpoints at which {% include admonitions/caution.html content=caution-character %} -If you need to use the dollar character (`$`) in a path string, escape it with `\`. For example, the path string for requests at `/data/$book`, would be `/data/\$book`. +{% capture note-dollar-character %}In express 5, you don't need to escape the dollar character (`$`) with `\`. +{% endcapture %} + +{% include admonitions/note.html content=note-dollar-character %} {% capture note-path-to-regexp %} Express uses [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) for matching the route paths; see the path-to-regexp documentation for all the possibilities in defining route paths. [Express Route Tester](http://forbeslindesay.github.io/express-route-tester/) is a handy tool for testing basic Express routes, although it does not support pattern matching. From a577b3368f5ed7bf4afa0d445f504a719fb60291 Mon Sep 17 00:00:00 2001 From: Sebastian Beltran Date: Wed, 16 Oct 2024 18:52:02 -0500 Subject: [PATCH 5/6] improve route guide --- en/guide/routing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/en/guide/routing.md b/en/guide/routing.md index 936512670e..5c89cf2989 100755 --- a/en/guide/routing.md +++ b/en/guide/routing.md @@ -72,13 +72,13 @@ Route paths, in combination with a request method, define the endpoints at which {% include admonitions/caution.html content=caution-character %} -{% capture note-dollar-character %}In express 5, you don't need to escape the dollar character (`$`) with `\`. +{% capture note-dollar-character %}In express 4, regular expression characters such as `$` need to be escaped with a `\`. {% endcapture %} -{% include admonitions/note.html content=note-dollar-character %} +{% include admonitions/caution.html content=note-dollar-character %} {% capture note-path-to-regexp %} - Express uses [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) for matching the route paths; see the path-to-regexp documentation for all the possibilities in defining route paths. [Express Route Tester](http://forbeslindesay.github.io/express-route-tester/) is a handy tool for testing basic Express routes, although it does not support pattern matching. + Express uses [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) for matching the route paths; see the path-to-regexp documentation for all the possibilities in defining route paths. {% endcapture %} {% include admonitions/note.html content=note-path-to-regexp %} From 79b7b7b28f38964e608a8d9251a76ab3fee80296 Mon Sep 17 00:00:00 2001 From: Sebastian Beltran Date: Thu, 12 Dec 2024 15:48:36 -0500 Subject: [PATCH 6/6] add back express playground router --- en/guide/routing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/guide/routing.md b/en/guide/routing.md index 38a0f624a6..574ec2e4c8 100755 --- a/en/guide/routing.md +++ b/en/guide/routing.md @@ -79,7 +79,7 @@ Route paths, in combination with a request method, define the endpoints at which {% include admonitions/caution.html content=note-dollar-character %} {% capture note-path-to-regexp %} - Express uses [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) for matching the route paths; see the path-to-regexp documentation for all the possibilities in defining route paths. + Express uses [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) for matching the route paths; see the path-to-regexp documentation for all the possibilities in defining route paths. [Express Playground Router](https://bjohansebas.github.io/playground-router/) is a handy tool for testing basic Express routes, although it does not support pattern matching. {% endcapture %} {% include admonitions/note.html content=note-path-to-regexp %}