195 lines
No EOL
10 KiB
HTML
195 lines
No EOL
10 KiB
HTML
<!doctype html>
|
|
<html>
|
|
<head>
|
|
<title>Mithril</title>
|
|
<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">Blog</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.21)</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>
|
|
<ul>
|
|
<li><a href="mithril.redraw.html#strategy">m.redraw.strategy(strategy)</a></li>
|
|
</ul>
|
|
</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, params)</a></li>
|
|
<li><a href="mithril.route.html#reading-current-route">m.route()</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-deferred">m.deferred</h2>
|
|
<p>This is a low-level method in Mithril. It's a modified version of the Thenable API.</p>
|
|
<p>A deferred is an asynchrony monad. It exposes a <code>promise</code> property which can <em>bind</em> callbacks to build a computation tree.</p>
|
|
<p>The deferred object can then <em>apply</em> a value by calling either <code>resolve</code> or <code>reject</code>, which then dispatches the value to be processed to the computation tree.</p>
|
|
<p>Each computation function takes a value as a parameter and is expected to return another value, which in turns is forwarded along to the next computation function (or functions) in the tree.</p>
|
|
<p>The deferred object returned by <code>m.deferred</code> has two methods: <code>resolve</code> and <code>reject</code>, and one property called <code>promise</code>. The methods can be called to dispatch a value to the promise tree. The <code>promise</code> property is the root of the promise tree. It has a method <code>then</code> which takes a <code>successCallback</code> and a <code>errorCallback</code> callbacks. Calling the <code>then</code> method attaches the computations represented by <code>successCallback</code> and <code>errorCallback</code> to the promise, which will be called when either <code>resolve</code> or <code>reject</code> is called. The <code>then</code> method returns a child promise, which, itself, can have more child promises, recursively.</p>
|
|
<p>The <code>promise</code> object is actually a function - specifically, it's an <a href="mithril.prop.html"><code>m.prop</code></a> getter-setter, which gets populated with the value returned by <code>successCallback</code> if the promise is resolved successfully.</p>
|
|
<p>Note that Mithril promises are not automatically integrated to its automatic redrawing system. If you wish to use third party asynchronous libraries (for example, <code>jQuery.ajax</code>), you should also consider using <a href="mithril.computation.html"><code>m.startComputation</code> / <code>m.endComputation</code></a> if you want views to redraw after requests complete.</p>
|
|
<hr>
|
|
<h3 id="usage">Usage</h3>
|
|
<pre><code class="lang-javascript">//standalone usage
|
|
var greetAsync = function() {
|
|
var deferred = m.deferred();
|
|
setTimeout(function() {
|
|
deferred.resolve("hello");
|
|
}, 1000);
|
|
return deferred.promise;
|
|
};
|
|
|
|
greetAsync()
|
|
.then(function(value) {return value + " world"})
|
|
.then(function(value) {console.log(value)}); //logs "hello world" after 1 second</code></pre>
|
|
<hr>
|
|
<h4 id="retrieving-a-value-via-the-getter-setter-api">Retrieving a value via the getter-setter API</h4>
|
|
<pre><code class="lang-javascript">//asynchronous service
|
|
var greetAsync = function() {
|
|
var deferred = m.deferred();
|
|
setTimeout(function() {
|
|
deferred.resolve("hello");
|
|
}, 1000);
|
|
return deferred.promise;
|
|
};
|
|
|
|
//asynchronous consumer
|
|
var greeting = greetAsync()
|
|
var processed = greeting.then(function(value) {return value + " world"})
|
|
|
|
console.log(greeting()) // undefined - because `deferred.resolve` has not been called yet
|
|
|
|
setTimeout(function() {
|
|
//now `deferred.resolve` has been called
|
|
console.log(greeting()) // "hello"
|
|
console.log(processed()) // "hello world"
|
|
}, 2000)</code></pre>
|
|
<hr>
|
|
<h4 id="integrating-to-the-mithril-redrawing-system">Integrating to the Mithril redrawing system</h4>
|
|
<pre><code class="lang-javascript">//asynchronous service
|
|
var greetAsync = function() {
|
|
m.startComputation();
|
|
|
|
var deferred = m.deferred();
|
|
setTimeout(function() {
|
|
deferred.resolve("hello");
|
|
|
|
m.endComputation();
|
|
}, 1000);
|
|
return deferred.promise;
|
|
};</code></pre>
|
|
<hr>
|
|
<h3 id="differences-from-promises-a-">Differences from Promises/A+</h3>
|
|
<p>For the most part, Mithril promises behave as you'd expect a <a href="http://promises-aplus.github.io/promises-spec/">Promise/A+</a> promise to behave, but has one difference:<br>Mithril promises atempt to execute synchronously if possible.</p>
|
|
<p>To illustrate the difference between Mithril and A+ promises, consider the code below:</p>
|
|
<pre><code class="lang-javascript">var deferred = m.deferred()
|
|
|
|
deferred.promise.then(function() {
|
|
console.log(1)
|
|
})
|
|
|
|
deferred.resolve("value")
|
|
|
|
console.log(2)</code></pre>
|
|
<p>In the example above, A+ promises are required to log <code>2</code> before logging <code>1</code>, whereas Mithril logs <code>1</code> before <code>2</code>. Typically <code>resolve</code>/<code>reject</code> are called asynchronously after the <code>then</code> method is called, so normally this difference does not matter.</p>
|
|
<hr>
|
|
<h3 id="signature">Signature</h3>
|
|
<p><a href="how-to-read-signatures.html">How to read signatures</a></p>
|
|
<pre><code class="lang-clike">Deferred deferred()
|
|
|
|
where:
|
|
Deferred :: Object { Promise promise, void resolve(any value), void reject(any value) }
|
|
Promise :: GetterSetter { Promise then(any successCallback(any value), any errorCallback(any value)) }
|
|
GetterSetter :: any getterSetter([any value])</code></pre>
|
|
<ul>
|
|
<li><p><strong>GetterSetter { Promise then([any successCallback(any value) [, any errorCallback(any value)]]) } promise</strong></p>
|
|
<p>A promise has a method called <code>then</code> which takes two computation callbacks as parameters.</p>
|
|
<p>The <code>then</code> method returns another promise whose computations (if any) receive their inputs from the parent promise's computation.</p>
|
|
<p>A promise is also a getter-setter (see <a href="mithril.prop.html"><code>m.prop</code></a>). After a call to either <code>resolve</code> or <code>reject</code>, it holds the result of the parent's computation (or the <code>resolve</code>/<code>reject</code> value, if the promise has no parent promises)</p>
|
|
<ul>
|
|
<li><p><strong>Promise then([any successCallback(any value) [, any errorCallback(any value)]])</strong></p>
|
|
<p>This method accepts two callbacks which process a value passed to the <code>resolve</code> and <code>reject</code> methods, respectively, and pass the processed value to the returned promise</p>
|
|
<ul>
|
|
<li><p><strong>any successCallback(any value)</strong> (optional)</p>
|
|
<p>The <code>successCallback</code> is called if <code>resolve</code> is called in the root <code>deferred</code>.</p>
|
|
<p>The default value (if this parameter is falsy) is the identity function <code>function(value) {return value}</code></p>
|
|
<p>If this function returns undefined, then it passes the <code>value</code> argument to the next step in the thennable queue, if any</p>
|
|
</li>
|
|
<li><p><strong>any errorCallback(any value)</strong> (optional)</p>
|
|
<p>The <code>errorCallback</code> is called if <code>reject</code> is called in the root <code>deferred</code>.</p>
|
|
<p>The default value (if this parameter is falsy) is the identity function <code>function(value) {return value}</code></p>
|
|
<p>If this function returns undefined, then it passes the <code>value</code> argument to the next step in the thennable queue, if any</p>
|
|
</li>
|
|
<li><p><strong>returns Promise promise</strong></p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><p><strong>void resolve(any value)</strong></p>
|
|
<p>This method passes a value to the <code>successCallback</code> of the deferred object's child promise</p>
|
|
</li>
|
|
<li><p><strong>void reject(any value)</strong></p>
|
|
<p>This method passes a value to the <code>errorCallback</code> of the deferred object's child promise</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> |