Concepts#

Dispatch loop#

Once started, Program runs a dispatch loop, producing a new Model given the current state and an input Message.

See thebasics example for details.

Parent-child composition and user interaction#

Parent-child hierarchy is made explicit by wrapping model and message types of the child with those of the parent.

Following diagrams show interactions between components in case of a user interacting with an example web app. Note that Elmish doesn't depend on any specific UI such as HTML rendering (it actually does not require any UI at all), and HTML is used just for explanation purposes.

First the UI is initialised:

1. program requests the initial model from the parent, top-level component (Main)
2. Parent component requests the initial model from its child subcomponent (Widget)
3. Widget.initialModel returns its initial model to the parent
4. Main.initialModel wraps child's model and returns the top-level initial model to the program
5. Program sends the model to the parent'sMain.view
6. Parent unwraps the child's component model from its model and sends it to child'sWidget.view
7. Widget.view returns a renderedHTML page
8. Main.view embeds child'sHTML page in itsHTML page
9. The resultingHTML page is send to the user

Then the user interacts with the browser:

1. User clicks on the increase button
2. Widget.view dispatches anIncrease message
3. Main.view has augemented thedispatch so the message becomesWidgetMsg Increase as it is sent along toprogram
4. program callsMain.update with this message andmainModel
5. As the message was tagged withWidgetMsg,Main.update delegates the update toWidget.update, sending along the way thewidgetModel part ofmainModel
6. Widget.update modifies the model according to the given message, in this caseIncrease, and returns the modifiedwidgetModel plus a command
7. Main.update returns the updatedmainModel toprogram
8. program then renders the view again passing the updatedmainModel

See theexample for details.

Tasks and side-effects#

Tasks such as reading a database or making a Web API call are performed usingasync andpromise blocks or just plain functions. These operations may return immediately but complete (or fail) at some later time. To feed the results back into the dispatch loop, instead of executing the operations directly, we instruct Elmish to do it for us by wrapping the instruction in a command.

Commands#

Commands are carriers of instructions, which you issue from theinit andupdate functions. Once evaluated, a command may produce one or more new messages, mapping success or failure as instructed ahead of time. As with any message dispatch, in the case of Parent-Child composition, child commands need to be mapped to the parent's type:

1. Program calls theMain.update with a message
2. Main.update does its own update and/or delegates toChild.update
3. Child.update does its own update and/or delegates toGrandChild.update
4. GrandChild.update returns with its model andCmd (of GrandChild message type)
5. Child.update processes GrandChild's model and maps itsCmd intoCmd of Child's message type and batches it with its ownCmd, if any
6. Main.update processes Child's model and maps itsCmd intoCmd of Main's message type and batches it with its ownCmd, if any

Here we collect commands from three different levels. At the end we send all these commands to ourProgram instance to run.

See theCmd module for ways to construct, map and batch commands.

Subscriptions#

Most of the messages (changes in the state) will originate within your code, but some will come from the outside, for example from a timer or a websocket. These sources can be tapped into with subscriptions, defined as F# functions that can dispatch new messages as they happen.

See thesubscriptions example for details.

View#

The core is independent of any particular technolgy, instead relying on a renderer library to implementsetState in any way seen fit. In fact, an Elmish app can run entirely without a UI!

At the moment, there are two UI technologies for which rendering has been implemented: React and React Native.

For details please seeelmish-react.

Interacting with a browser#

Larger Elmish applications for the browser may benefit from advanced features like routing and explicit navigation control.

For information about these features please seeelmish-browser.

Controlling termination#

Hot reloading requires the new version of the application loop to be started. To faciliate the interaction with libraries that implement this functionality the v4 elmish extends the abstractions with "termination". UsewithTermination function to specify the predicate that can evaluate incoming messages and decide if the dispatch loop should stop processing the messages, as well as specify how to release the resources.

Observing the state changes#

Every message going through the dispatch loop can be traced, along with the current state of the app. Just augument the program instance with a trace function:openElmishProgram.mkProgram init update view|> Program.withConsoleTrace|> Program.run

And start seeing the state and messages as updates happen in the browser developer console.

For more advanced debugging capabilities please seeelmish-debugger.