138 lines
7.9 KiB
HTML
138 lines
7.9 KiB
HTML
<!doctype html>
|
|
<html>
|
|
<head>
|
|
<title>Routing
|
|
- Mithril</title>
|
|
<meta name="description" value="Mithril.js - a Javascript Framework for Building Brilliant Applications" />
|
|
<link href="lib/prism/prism.css" rel="stylesheet" />
|
|
<link href="style.css" rel="stylesheet" />
|
|
</head>
|
|
<body>
|
|
<header>
|
|
<nav class="container">
|
|
<a href="index.html" class="logo"><span>○</span> Mithril</a>
|
|
<a href="getting-started.html">Guide</a>
|
|
<a href="mithril.html">API</a>
|
|
<a href="community.html">Community</a>
|
|
<a href="http://lhorie.github.io/mithril-blog">Learn</a>
|
|
<a href="installation.html">Download</a>
|
|
<a href="http://github.com/lhorie/mithril.js" target="_blank">Github</a>
|
|
</nav>
|
|
</header>
|
|
<main>
|
|
<section class="content">
|
|
<div class="container">
|
|
<div class="row">
|
|
<div class="col(3,3,12)">
|
|
<h2 id="core-topics">Core Topics</h2>
|
|
<ul>
|
|
<li><a href="installation.html">Installation</a></li>
|
|
<li><a href="getting-started.html">Getting Started</a></li>
|
|
<li><a href="routing.html">Routing</a></li>
|
|
<li><a href="web-services.html">Web Services</a></li>
|
|
<li><a href="components.html">Components</a></li>
|
|
</ul>
|
|
<h2 id="advanced-topics.html">Advanced Topics</h2>
|
|
<ul>
|
|
<li><a href="auto-redrawing.html">The Auto-Redrawing System</a></li>
|
|
<li><a href="integration.html">Integrating with Other Libraries</a></li>
|
|
<li><a href="optimizing-performance.html">Compiling Templates</a></li>
|
|
</ul>
|
|
<h2 id="misc">Misc</h2>
|
|
<ul>
|
|
<li><a href="comparison.html">Differences from Other MVC Frameworks</a></li>
|
|
<li><a href="benchmarks.html">Benchmarks</a></li>
|
|
<li><a href="practices.html">Good Practices</a></li>
|
|
<li><a href="tools.html">Useful Tools</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="col(9,9,12)">
|
|
<h2 id="routing">Routing</h2>
|
|
<p>Routing is a system that allows creating Single-Page-Applications (SPA), i.e. applications that can go from one page to another without causing a full browser refresh.</p>
|
|
<p>It enables seamless navigability while preserving the ability to bookmark each page individually, and the ability to navigate the application via the browser's history mechanism.</p>
|
|
<p>Mithril provides utilities to handle three different aspect of routing:</p>
|
|
<ul>
|
|
<li>defining a list of routes</li>
|
|
<li>programmatically redirecting between routes</li>
|
|
<li>making links in templates routed transparently and unobtrusively</li>
|
|
</ul>
|
|
<hr>
|
|
<h3 id="defining-routes">Defining routes</h3>
|
|
<p>To define a list of routes, you need to specify a host DOM element, a default route and a key-value map of possible routes and respective <a href="mithril.mount.html">modules</a> to be rendered.</p>
|
|
<p>The example below defines three routes, to be rendered in <code><body></code>. <code>home</code>, <code>login</code> and <code>dashboard</code> are modules. We'll see how to define a module in a bit.</p>
|
|
<pre><code class="lang-javascript">m.route(document.body, "/", {
|
|
"/": home,
|
|
"/login": login,
|
|
"/dashboard": dashboard,
|
|
});
|
|
</code></pre>
|
|
<p>Routes can take arguments, by prefixing words with a colon <code>:</code>.</p>
|
|
<p>The example below shows a route that takes a <code>userID</code> parameter.</p>
|
|
<pre><code class="lang-javascript">//a sample module
|
|
var dashboard = {
|
|
controller: function() {
|
|
return {id: m.route.param("userID")};
|
|
},
|
|
view: function(controller) {
|
|
return m("div", controller.id);
|
|
}
|
|
}
|
|
|
|
//setup routes to start w/ the `#` symbol
|
|
m.route.mode = "hash";
|
|
|
|
//define a route
|
|
m.route(document.body, "/dashboard/johndoe", {
|
|
"/dashboard/:userID": dashboard
|
|
});
|
|
</code></pre>
|
|
<p>This redirects to the URL <code>http://server/#/dashboard/johndoe</code> and yields:</p>
|
|
<pre><code class="lang-markup"><body>johndoe</body>
|
|
</code></pre>
|
|
<p>Above, <code>dashboard</code> is a module. It contains <code>controller</code> and <code>view</code> properties. When the URL matches a route, the respective module's controller is instantiated and passed as a parameter to the view.</p>
|
|
<p>In this case, since there's only one route, the app redirects to the default route <code>"/dashboard/johndoe"</code> and, under the hood, it calls <code>m.mount(document.body, dashboard)</code>.</p>
|
|
<p>The string <code>johndoe</code> is bound to the <code>:userID</code> parameter, which can be retrieved programmatically in the controller via <code>m.route.param("userID")</code>.</p>
|
|
<p>The <code>m.route.mode</code> property defines which URL portion is used to implement the routing mechanism. It should be set before any calls to <code>m.route</code>. Its value can be set to either "search", "hash" or "pathname". The default value is "search".</p>
|
|
<ul>
|
|
<li><p><code>search</code> mode uses the querystring. This allows named anchors (i.e. <code><a href="#top">Back to top</a></code>, <code><a name="top"></a></code>) to work on the page, but routing changes causes page refreshes in IE8, due to its lack of support for <code>history.pushState</code>.</p>
|
|
<p>Example URL: <code>http://server/?/path/to/page</code></p>
|
|
</li>
|
|
<li><p><code>hash</code> mode uses the hash. It's the only mode in which routing changes do not cause page refreshes in any browser. However, this mode does not support named anchors and browser history lists.</p>
|
|
<p>Example URL: <code>http://server/#/path/to/page</code></p>
|
|
</li>
|
|
<li><p><code>pathname</code> mode allows routing URLs that contain no special characters, however this mode requires server-side setup in order to support bookmarking and page refreshes. It also causes page refreshes in IE8.</p>
|
|
<p>Example URL: <code>http://server/path/to/page</code></p>
|
|
<p>The simplest server-side setup possible to support pathname mode is to serve the same content regardless of what URL is requested. In Apache, this URL rewriting can be achieved using <a href="https://httpd.apache.org/docs/current/mod/mod_rewrite.html">mod_rewrite</a>.</p>
|
|
</li>
|
|
</ul>
|
|
<hr>
|
|
<h3 id="redirecting">Redirecting</h3>
|
|
<p>You can programmatically redirect to another page. Given the example in the "Defining Routes" section:</p>
|
|
<pre><code class="lang-javascript">m.route("/dashboard/marysue");
|
|
</code></pre>
|
|
<p>redirects to <code>http://server/#/dashboard/marysue</code></p>
|
|
<hr>
|
|
<h3 id="mode-abstraction">Mode abstraction</h3>
|
|
<p>This method is meant to be used with a virtual element's <code>config</code> attribute. For example:</p>
|
|
<pre><code class="lang-javascript">//Note that the '#' is not required in `href`, thanks to the `config` setting.
|
|
m("a[href='/dashboard/alicesmith']", {config: m.route});
|
|
</code></pre>
|
|
<p>This makes the href behave correctly regardless of which <code>m.route.mode</code> is selected. It's a good practice to always use the idiom above, instead of hardcoding <code>?</code> or <code>#</code> in the href attribute.</p>
|
|
<p>See <a href="mithril.html"><code>m()</code></a> for more information on virtual elements.</p>
|
|
<hr>
|
|
<h3 id="redrawing-semantics-of-routing">Redrawing semantics of routing</h3>
|
|
<p>By default, changing routes causes templates to be re-rendered from scratch. This behavior can be changed either via the <a href="mithril.html#persisting-dom-elements-across-route-changes">retain flag in a config's context object</a>, or the <a href="mithril.redraw.html#changing-redraw-strategy"><code>m.redraw.strategy("diff")</code> hint</a>.</p>
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
</main>
|
|
<footer>
|
|
<div class="container">
|
|
Released under the <a href="http://opensource.org/licenses/MIT" target="_blank">MIT license</a>
|
|
<br />© 2014 Leo Horie
|
|
</div>
|
|
</footer>
|
|
<script src="lib/prism/prism.js"></script>
|
|
</body>
|
|
</html>
|