From 90843f6bdbaaadaec3192c07243aa85defe2a71a Mon Sep 17 00:00:00 2001 From: Leo Horie Date: Thu, 26 Feb 2015 22:51:07 -0500 Subject: [PATCH] add docs about async components --- docs/components.md | 13 ++++++++++++- docs/mithril.module.md | 15 +++++++++++++-- 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/docs/components.md b/docs/components.md index 5427f3ce..350d62d2 100644 --- a/docs/components.md +++ b/docs/components.md @@ -39,6 +39,7 @@ m.module(document.body, MyApp) Modules can have arguments "preloaded" into them. Calling `m.module` without a DOM element as an argument will create copy of the module with parameters already bound as arguments to the controller and view functions ```javascript +//declare a component var MyModule = {} MyModule.controller = function(options, extras) { this.greeting = "Hello" @@ -125,7 +126,17 @@ m.module(document.body, MyApp) --- -### Component limitations +### Asynchronous components + +Since components are Mithril modules, it's possible to encapsulate asynchronous behavior. Under regular circumstances, Mithril waits for all asynchronous tasks to complete, but when using components, a component's parent view renders before the component completes its asynchronous tasks (because the existence of the component only becomes known to the diff engine at the time when the template is rendered). + +When a component has asynchronous payloads and they are queued by the [auto-redrawing system](auto-redrawing.md), its view is NOT rendered until all asynchronous operations complete. When the component's asynchronous operations complete, another redraw is triggered and the entire template tree is evaluated again. This means that the virtual dom tree may take two or more redraws (depending on how many nested asynchronous components there are) to be fully rendered. + +For this reason, it's recommended to refactor code in such a way that asynchronous operations happen in the root module and avoid making AJAX calls within components. + +--- + +### Component limitations and caveats There are a few caveats to using modules as components: diff --git a/docs/mithril.module.md b/docs/mithril.module.md index f11e1728..5c9e4c14 100644 --- a/docs/mithril.module.md +++ b/docs/mithril.module.md @@ -8,7 +8,8 @@ - [Unloading modules](#unloading-modules) - [Using modules as components](#using-modules-as-components) - [Unloading components](#unloading-components) -- [Component limitations](#component limitations) +- [Asynchronous components](#asynchronous-components) +- [Component limitations and caveats](#component-limitations-and-caveats) --- @@ -280,7 +281,17 @@ m.module(document.body, MyApp) --- -### Component limitations +### Asynchronous components + +Since components are Mithril modules, it's possible to encapsulate asynchronous behavior. Under regular circumstances, Mithril waits for all asynchronous tasks to complete, but when using components, a component's parent view renders before the component completes its asynchronous tasks (because the existence of the component only becomes known to the diff engine at the time when the template is rendered). + +When a component has asynchronous payloads and they are queued by the [auto-redrawing system](auto-redrawing.md), its view is NOT rendered until all asynchronous operations complete. When the component's asynchronous operations complete, another redraw is triggered and the entire template tree is evaluated again. This means that the virtual dom tree may take two or more redraws (depending on how many nested asynchronous components there are) to be fully rendered. + +For this reason, it's recommended to refactor code in such a way that asynchronous operations happen in the root module and avoid making AJAX calls within components. + +--- + +### Component limitations and caveats There are a few caveats to using modules as components: