mithril

<head> <meta charset=UTF-8> <title> Path Handling - Mithril.js</title> <link href="https://fonts.googleapis.com/css?family=Open+Sans" rel=stylesheet> <link href=style.css rel=stylesheet> <link rel=icon type=image/png sizes=32x32 href=favicon.png> <meta name=viewport content="width=device-width,initial-scale=1"> </head> <body> <header> <section> <a class=hamburger href=javascript:;>≡</a> <h1><img src=logo.svg> Mithril <small>2.0.3</small></h1> <nav> <a href=index.html>Guide</a> <a href=api.html>API</a> <a href=https://gitter.im/MithrilJS/mithril.js>Chat</a> <a href=https://github.com/MithrilJS/mithril.js>GitHub</a> </nav> </section> </header> <main> <section> <h1 id=path-handling><a href=#path-handling>Path Handling</a></h1> <ul> <li>Getting Started<ul> <li><a href=index.html>Introduction</a></li> <li><a href=installation.html>Installation</a></li> <li><a href=simple-application.html>Tutorial</a></li> <li><a href=learning-mithril.html>Learning Resources</a></li> <li><a href=support.html>Getting Help</a></li> </ul> </li> <li>Resources<ul> <li><a href=jsx.html>JSX</a></li> <li><a href=es6.html>ES6+ on legacy browsers</a></li> <li><a href=animation.html>Animation</a></li> <li><a href=testing.html>Testing</a></li> <li><a href=examples.html>Examples</a></li> <li><a href=integrating-libs.html>3rd Party Integration</a></li> <li><strong><a href=paths.html>Path Handling</a></strong><ul> <li><a href=#path-types>Path types</a></li> <li><a href=#path-parameters>Path parameters</a></li> <li><a href=#parameter-normalization>Parameter normalization</a></li> <li><a href=#path-normalization>Path normalization</a></li> <li><a href=#path-escaping>Path escaping</a></li> </ul> </li> </ul> </li> <li>Key concepts<ul> <li><a href=vnodes.html>Vnodes</a></li> <li><a href=components.html>Components</a></li> <li><a href=lifecycle-methods.html>Lifecycle methods</a></li> <li><a href=keys.html>Keys</a></li> <li><a href=autoredraw.html>Autoredraw system</a></li> </ul> </li> <li>Social<ul> <li><a href=https://github.com/MithrilJS/mithril.js/wiki/JOBS>Mithril Jobs</a></li> <li><a href=contributing.html>How to contribute</a></li> <li><a href=credits.html>Credits</a></li> <li><a href=code-of-conduct.html>Code of Conduct</a></li> </ul> </li> <li>Misc<ul> <li><a href=framework-comparison.html>Framework comparison</a></li> <li><a href=change-log.html>Change log/Migration</a></li> <li><a href=https://mithril.js.org/archive/v1.1.6/ >v1 Documentation</a></li> <li><a href=https://mithril.js.org/archive/v0.2.5/ >v0.2 Documentation</a></li> </ul> </li> </ul> <hr> <p><a href=route.html><code>m.route</code></a>, <a href=request.html><code>m.request</code></a>, and <a href=jsonp.html><code>m.jsonp</code></a> each have a concept called a path. This is used to generate the URL you route to or fetch from.</p> <h3 id=path-types><a href=#path-types>Path types</a></h3> <p>There are two general types of paths: raw paths and parameterized paths.</p> <ul> <li>Raw paths are simply strings used directly as URLs. Nothing is substituted or even split. It's just normalized with all the parameters appended to the end.</li> <li>Parameterized paths let you insert values into paths, escaped by default for convenience and safety against URL injection.</li> </ul> <p>For <a href=request.html><code>m.request</code></a> and <a href=jsonp.html><code>m.jsonp</code></a>, these can be pretty much any URL, but for <a href=route.html>routes</a>, these can only be absolute URL path names without schemes or domains.</p> <h3 id=path-parameters><a href=#path-parameters>Path parameters</a></h3> <p>Path parameters are themselves pretty simple. They come in two forms:</p> <ul> <li><code>:foo</code> - This injects a simple <code>params.foo</code> into the URL, escaping its value first.</li> <li><code>:foo...</code> - This injects a raw <code>params.foo</code> path into the URL without escaping anything.</li> </ul> <p>You're probably wondering what that <code>params</code> object is supposed to be. It's pretty simple: it's the <code>params</code> in either <a href=route.html#mrouteset><code>m.route.set(path, params)</code></a>, <a href=request.html#signature><code>m.request({url, params})</code></a>, or <a href=jsonp.html#signature><code>m.jsonp({url, params})</code></a>.</p> <p>When receiving routes via <a href=route.html#signature><code>m.route(root, defaultRoute, routes)</code></a>, you can use these parameters to <em>extract</em> values from routes. They work basically the same way as generating the paths, just in the opposite direction.</p> <pre><code class=language-javascript>// Edit a single item m.route(document.body, "/edit/1", { "/edit/:id": { view: function() { return [ m(Menu), m("h1", "Editing user " + m.route.param("id")) ] } }, }) // Edit an item identified by path m.route(document.body, "/edit/pictures/image.jpg", { "/edit/:file...": { view: function() { return [ m(Menu), m("h1", "Editing file " + m.route.param("file")) ] } }, })</code></pre> <p>In the first example, assuming you're navigating to the default route in each, <code>m.route.param("id")</code> would be read as <code>"1"</code> and <code>m.route.param("file")</code> would be read as <code>pictures/image.jpg</code>.</p> <p>Path parameters may be delimited by either a <code>/</code>, <code>-</code>, or <code>.</code>. This lets you have dynamic path segments, and they're considerably more flexible than just a path name. For example, you could match against routes like <code>"/edit/:name.:ext"</code> for editing based on file extension or <code>"/:lang-:region/view"</code> for a localized route.</p> <p>Path parameters are greedy: given a declared route <code>"/edit/:name.:ext"</code>, if you navigate to <code>/edit/file.test.png</code>, the parameters extracted will be <code>{name: "file.test", ext: "png"}</code>, not <code>{name: "file", ext: "test.png"}</code>. Similarly, given <code>"/route/:path.../view/:child..."</code>, if you go to <code>/route/foo/view/bar/view/baz</code>, the parameters extracted will be <code>{path: "foo/view/bar", child: "baz"}</code>.</p> <h3 id=parameter-normalization><a href=#parameter-normalization>Parameter normalization</a></h3> <p>Path parameters that are interpolated into path names are omitted from the query string, for convenience and to keep the path name reasonably readable. For example, this sends a server request of <code>GET /api/user/1/connections?sort=name-asc</code>, omitting the duplicate <code>id=1</code> in the URL string.</p> <pre><code class=language-javascript>m.request({ url: "https://example.com/api/user/:userID/connections", params: { userID: 1, sort: "name-asc" } })</code></pre> <p>You can also specify parameters explicitly in the query string itself, such as in this, which is equivalent to the above:</p> <pre><code class=language-javascript>m.request({ url: "https://example.com/api/user/:userID/connections?sort=name-asc", params: { userID: 1 } })</code></pre> <p>And of course, you can mix and match. This fires a request to <code>GET /api/user/1/connections?sort=name-asc&first=10</code>.</p> <pre><code class=language-javascript>m.request({ url: "https://example.com/api/user/:userID/connections?sort=name-asc", params: { userID: 1, first: 10 } })</code></pre> <p>This even extends to route matching: you can match against a route <em>with</em> explicit query strings. It retains the matched parameter for convenience, so you can still access them via vnode parameters or via <a href=route.html#mrouteparam><code>m.route.param</code></a>. Note that although this <em>is</em> possible, it's not generally recommended, since you should prefer paths for pages. It could sometimes useful if you need to generate a somewhat different view just for a particular file type, but it still logically is a query-like parameter, not a whole separate page.</p> <pre><code class=language-javascript>// Note: this is generally *not* recommended - you should prefer paths for route // declarations, not query strings. m.route(document.body, "/edit/1", { "/edit?type=image": { view: function() { return [ m(Menu), m("h1", "Editing photo") ] } }, "/edit": { view: function() { return [ m(Menu), m("h1", "Editing " + m.route.param("type")) ] } } })</code></pre> <p>Query parameters are implicitly consumed - you don't need to name them to accept them. You can match based on an existing value, like in <code>"/edit?type=image"</code>, but you don't need to use <code>"/edit?type=:type"</code> to accept the value. In fact, Mithril would treat that as you trying to literally match against <code>m.route.param("type") === ":type"</code>, so you probably don't want to do that. In short, use <code>m.route.param("key")</code> or route component attributes to read query parameters.</p> <h3 id=path-normalization><a href=#path-normalization>Path normalization</a></h3> <p>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 <a href=parsePathname.html><code>m.parsePathname(m.route.get()).path</code></a>.)</p> <p>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.</p> <h3 id=path-escaping><a href=#path-escaping>Path escaping</a></h3> <p>There are some characters that, if you want to use them literally, you need to escape. Conveniently, <code>encodeURIComponent</code> 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:</p> <ul> <li><code>:</code> = <code>%3A</code></li> <li><code>/</code> = <code>%2F</code> (required only in paths)</li> <li><code>%</code> = <code>%25</code></li> <li><code>?</code> = <code>%3F</code> (required only in paths)</li> <li><code>#</code> = <code>%23</code></li> </ul> <p>Of course, there's others you have to escape per the URL spec, like spaces. But as already noted, <code>encodeURIComponent</code> 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 <code>m.request("https://example.com/api/user/User%20Name/:field", {params: {field: ...}})</code>.</p> <hr> <small>License: MIT. © Leo Horie.</small> </section> </main> <script src=https://cdnjs.cloudflare.com/ajax/libs/prism/1.6.0/prism.min.js defer></script> <script src=https://cdnjs.cloudflare.com/ajax/libs/prism/1.6.0/components/prism-jsx.min.js defer></script> <script src=https://unpkg.com/mithril@2.0.3/mithril.js async></script> <script> document.querySelector(".hamburger").onclick = function() { document.body.className = document.body.className === "navigating" ? "" : "navigating" document.querySelector("h1 + ul").onclick = function() { document.body.className = '' } } </script>