From 76e8eaab5e5aef8fc6aeec5e5ae284215cff6cbe Mon Sep 17 00:00:00 2001 From: Isiah Meadows Date: Sat, 6 Jul 2019 02:45:12 -0400 Subject: [PATCH] Clarify need for escaping, to avoid confusion (#2456) Nobody has asked yet, but I'd like to not form assumptions about the reader. Also, it's come up on rare occasion a while back, on both GitHub and Gitter. --- docs/paths.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/paths.md b/docs/paths.md index cc9a7639..8618dc6e 100644 --- a/docs/paths.md +++ b/docs/paths.md @@ -4,6 +4,7 @@ - [Path parameters](#path-parameters) - [Parameter normalization](#parameter-normalization) - [Path normalization](#path-normalization) +- [Path escaping](#path-escaping) ----- @@ -130,3 +131,15 @@ Query parameters are implicitly consumed - you don't need to name them to accept Parsed paths are always returned with all the duplicate parameters and extra slashes dropped, and they always start with a slash. These little differences often get in the way, and it makes routing and path handling a lot more complicated than it should be. Mithril internally normalizes paths for routing, but it does not expose the current, normalized route directly. (You could compute it via [`m.parsePathname(m.route.get()).path`](parsePathname.md).) When parameters are deduplicated during matching, parameters in the query string are preferred over parameters in the path name, and parameters towards the end of the URL are preferred over parameters closer to the start of the URL. + +### Path escaping + +There are some characters that, if you want to use them literally, you need to escape. Conveniently, `encodeURIComponent` encodes these (and more), and when you substitute parameters and add query parameters, they're encoded as necessary using this. Here's the ones Mithril interprets: + +- `:` = `%3A` +- `/` = `%2F` (required only in paths) +- `%` = `%25` +- `?` = `%3F` (required only in paths) +- `#` = `%23` + +Of course, there's others you have to escape per the URL spec, like spaces. But as already noted, `encodeURIComponent` does that for you, and Mithril uses that implicitly when you substitute parameters. So you only really need to care if you're specifying parameters explicitly like in `m.request("https://example.com/api/user/User%20Name/:field", {params: {field: ...}})`.