221 lines
No EOL
12 KiB
HTML
221 lines
No EOL
12 KiB
HTML
<!doctype html>
|
|
<html>
|
|
<head>
|
|
<title>Mithril</title>
|
|
<link href="http://fonts.googleapis.com/css?family=Open+Sans:300italic" rel="stylesheet" />
|
|
<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="mithril.min.zip">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="api">API (v0.1)</h2>
|
|
<h3 id="core">Core</h3>
|
|
<ul>
|
|
<li><a href="mithril.html">m</a></li>
|
|
<li><a href="mithril.prop.html">m.prop</a></li>
|
|
<li><a href="mithril.withAttr.html">m.withAttr</a></li>
|
|
<li><a href="mithril.module.html">m.module</a></li>
|
|
<li><a href="mithril.trust.html">m.trust</a></li>
|
|
<li><a href="mithril.render.html">m.render</a></li>
|
|
<li><a href="mithril.redraw.html">m.redraw</a></li>
|
|
</ul>
|
|
<h3 id="routing">Routing</h3>
|
|
<ul>
|
|
<li><a href="mithril.route.html">m.route</a>
|
|
<ul>
|
|
<li><a href="mithril.route.html#defining-routes">m.route(rootElement, defaultRoute, routes)</a></li>
|
|
<li><a href="mithril.route.html#redirecting">m.route(path)</a></li>
|
|
<li><a href="mithril.route.html#mode-abstraction">m.route(element)</a></li>
|
|
<li><a href="mithril.route.html#mode">m.route.mode</a></li>
|
|
<li><a href="mithril.route.html#param">m.route.param</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<h3 id="data">Data</h3>
|
|
<ul>
|
|
<li><a href="mithril.request.html">m.request</a></li>
|
|
<li><a href="mithril.deferred.html">m.deferred</a></li>
|
|
<li><a href="mithril.sync.html">m.sync</a></li>
|
|
<li><a href="mithril.computation.html">m.startComputation / m.endComputation</a></li>
|
|
</ul>
|
|
|
|
<h2 id="archive">History</h2>
|
|
<ul>
|
|
<li><a href="roadmap.html">Roadmap</a></li>
|
|
<li><a href="change-log.html">Change log</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="col(9,9,12)">
|
|
<h2 id="m-route">m.route</h2>
|
|
<p>Routing is a system that allows creating Single-Page-Applications (SPA), i.e. applications that can go from a 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>This method overloads 3 different units of functionality:</p>
|
|
<ul>
|
|
<li><p><code>m.route(rootElement, defaultRoute, routes)</code> - defines the available URLs in an application, and their respective modules</p>
|
|
</li>
|
|
<li><p><code>m.route(path)</code> - redirects to another route</p>
|
|
</li>
|
|
<li><p><code>m.route(element)</code> - an extension to link elements that unobtrusively abstracts away the routing mode</p>
|
|
</li>
|
|
</ul>
|
|
<p>Routing is single-page-application (SPA) friendly, and can be implemented using either <code>location.hash</code>, HTML5 URL rewriting or <code>location.querystring</code>. See <a href="#mode"><code>m.route.mode</code></a> for the caveats of each implementation.</p>
|
|
<hr>
|
|
<p><a name="defining-routes"></a></p>
|
|
<h3 id="defining-routes">Defining routes</h3>
|
|
<h4 id="usage">Usage</h4>
|
|
<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.module.html">modules</a> to be rendered.</p>
|
|
<p>The example below defines 3 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 an <code>userID</code> parameter</p>
|
|
<pre><code class="lang-javascript">//a sample module
|
|
var dashboard = {
|
|
controller: function() {
|
|
this.id = m.route.param("userID");
|
|
},
|
|
view: function(controller) {
|
|
m.render("body", controller.id);
|
|
}
|
|
}
|
|
|
|
//define a route
|
|
m.route(document.body, "/dashboard/johndoe", {
|
|
"/dashboard/:userID": dashboard
|
|
});
|
|
|
|
//setup routes to start w/ the `#` symbol
|
|
m.route.mode = "hash";</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 a <code>controller</code> and a <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 route, the app redirects to the default route <code>"/dashboard/johndoe"</code>.</p>
|
|
<p>The string <code>johndoe</code> is bound to the <code>:userID</code> parameter, which can be retrived programmatically in the controller via <code>m.route.param("userID")</code>.</p>
|
|
<p>The <code>m.route.mode</code> defines which part of the URL to use for routing.</p>
|
|
<hr>
|
|
<h4 id="signature">Signature</h4>
|
|
<p><a href="how-to-read-signatures.html">How to read signatures</a></p>
|
|
<pre><code class="lang-clike">void route(DOMElement rootElement, String defaultRoute, Object<Module> routes) { String mode, String param(String key) }
|
|
|
|
where:
|
|
Module :: Object { void controller(), void view(Object controllerInstance) }</code></pre>
|
|
<ul>
|
|
<li><p><strong>DOMElement root</strong></p>
|
|
<p>A DOM element which will contain the view's template.</p>
|
|
</li>
|
|
<li><p><strong>String defaultRoute</strong></p>
|
|
<p>The route to redirect to if the current URL does not match any of the defined routes</p>
|
|
</li>
|
|
<li><p><strong>Object<Module> routes</strong></p>
|
|
<p>A key-value map of possible routes and their respective modules. Keys are expected to be absolute pathnames, but can include dynamic parameters. Dynamic parameters are words preceded by a colon <code>:</code></p>
|
|
<p><code>{'/path/to/page/': pageModule}</code> - a route with a basic pathname</p>
|
|
<p><code>{'/path/to/page/:id': pageModule}</code> - a route with a pathname that contains a dynamic parameter called <code>id</code>. This route would be selected if the URL was <code>/path/to/page/1</code>, <code>/path/to/page/test</code>, etc</p>
|
|
<p><code>{'/user/:userId/book/:bookId': userBookModule}</code> - a route with a pathname that contains two parameters</p>
|
|
<p>Dynamic parameters are wild cards that allow selecting a module based on a URL pattern. The values that replace the dynamic parameters in a URL are available via <code>m.route.param()</code></p>
|
|
<p>Note that the URL component used to resolve routes is dependent on <code>m.route.mode</code>. By default, the querystring is considered the URL component to test against the routes collection</p>
|
|
<p>If the current page URL matches a route, its respective module is activated. See <code>m.module</code> for information on modules.</p>
|
|
</li>
|
|
<li><p><a name="mode"></a></p>
|
|
<h4 id="m-route-mode">m.route.mode</h4>
|
|
<p><strong>String mode</strong></p>
|
|
<p>The <code>m.route.mode</code> property defines which URL portion is used to implement the routing mechanism. Its value can be set to either "search", "hash" or "pathname". 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.</p>
|
|
<p>Example URL: <code>http://server/#/path/to/page</code></p>
|
|
</li>
|
|
<li><p><code>pathname</code> mode allows routing URLs that contains 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 ModRewrite.</p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><p><a name="param"></a></p>
|
|
<h4 id="m-route-param">m.route.param</h4>
|
|
<p><strong>String param(String key)</strong></p>
|
|
<p>Route parameters are dynamic values that can be extracted from the URL based on the signature of the currently active route.</p>
|
|
<p>A route without parameters looks like this:</p>
|
|
<p><code>"/path/to/page/"</code></p>
|
|
<p>A route with parameters might look like this:</p>
|
|
<p><code>"/path/to/page/:id"</code> - here <code>id</code> is the name of the route parameter</p>
|
|
<p>If the currently active route is <code>/dashboard/:userID</code> and the current URL is <code>/dashboard/johndoe</code>, then calling <code>m.route.param("userID")</code> returns <code>"johndoe"</code></p>
|
|
<ul>
|
|
<li><p><strong>String key</strong></p>
|
|
<p>The name of a route parameter</p>
|
|
</li>
|
|
<li><p><strong>returns String value</strong></p>
|
|
<p>The value that maps to the parameter specified by <code>key</code></p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<hr>
|
|
<p><a name="redirecting"></a></p>
|
|
<h3 id="redirecting">Redirecting</h3>
|
|
<h4 id="usage">Usage</h4>
|
|
<p>You can programmatically redirec 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>
|
|
<h4 id="signature">Signature</h4>
|
|
<p><a href="how-to-read-signatures.html">How to read signatures</a></p>
|
|
<pre><code class="lang-clike">void route(String path)</code></pre>
|
|
<ul>
|
|
<li><p><strong>String path</strong></p>
|
|
<p>The route to redirect to. Note that to redirect to a different page outside of the scope of Mithril's routing, you should use <code>window.location</code></p>
|
|
</li>
|
|
</ul>
|
|
<hr>
|
|
<p><a name="mode-abstraction"></a></p>
|
|
<h3 id="mode-abstraction">Mode abstraction</h3>
|
|
<h4 id="usage">Usage</h4>
|
|
<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>
|
|
<h4 id="signature">Signature</h4>
|
|
<p><a href="how-to-read-signatures.html">How to read signatures</a></p>
|
|
<pre><code class="lang-clike">void route(DOMElement element, Boolean isInitialized)</code></pre>
|
|
<ul>
|
|
<li><p><strong>DOMElement element</strong></p>
|
|
<p>an anchor element <code><a></code> with an <code>href</code> attribute that points to a route</p>
|
|
</li>
|
|
<li><p><strong>Boolean isInitialized</strong></p>
|
|
<p>the method does not run if this flag is set to true. This is to make the method compatible with virtual DOM elements' <code>config</code> attribute (see <a href="mithril"><code>m()</code></a>)</p>
|
|
</li>
|
|
</ul>
|
|
|
|
</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> |