# Composing

Composing HTML elements is straightforward in Shpadoinkle when the elements all have the same model type; nesting them in each other works automatically.

For an element to be a child of another element, they must have the same model type. This means that all elements in the tree under an `Html m Model`

(children, children of children, etc.) must have the type `Html m Model`

. Therefore, before an element can become the child of a parent, it must be transformed to have a matching model type, if the model types do not already match.

Changing the model type of an HTML element can be accomplished using the `xC`

functions which make use of the `Continuous`

typeclass. This typeclass is instantiated by types where the values can be changed by functions which change continuations.

Continuations are a concept in Shpadoinkle’s event handling system. Each event handler causes a continuation to be run. That continuation may perform I/O actions and/or update the model. If a continuation updates the model, then it does so atomically, which means that it is safe to have multiple continuations running concurrently. To learn more about continuations, see the Shpadoinkle-continuations package. |

The model type of an `Html`

element determines what type the event handlers expect the model to have. An event handler yields a continuation which may update the model. In order to change the model type of an `Html`

element, it is sufficient to change the type which the continuations operate on. As such, `Html`

instantiates `Continuous`

; any function which changes the type which continuations operate on can be used to change the model type of an `Html`

element.

First consider the case where you have an element `x :: Html m a`

and you need to change its type to `Html m (a,b)`

so that the event handlers act on the left side of the tuple. In this case you should use the `leftC`

function: `leftC x :: Html m (a,b)`

.

Similarly, if you have an element `x :: Html m b`

and you need to change its type `Html m (a,b)`

, then you should use the `rightC`

function: `rightC x :: Html (a,b)`

.

If you have an element `x :: Html m ()`

then you can freely vary its model type using `voidC`

: `voidC x :: Html m a`

. The event handlers will have the same side effects and they will not touch the model.

You can change the model type from anything to anything using the `forgetC`

function, which will strip out all event handlers, replacing them with no-ops. For any types `a`

, `b`

and monads `m`

, `n`

, if `x :: Html m a`

then `forgetC x :: Html n b`

.

Given a lens from a type `b`

to a type `a`

, consisting of a function `set :: (a -> b -> b)`

and a function `get :: b -> a`

, you can change an element `x :: Html m a`

to an element `liftC set get x :: Html m b`

using the `liftC`

function.

You can change an element `x :: Html m a`

to an element `maybeC x :: Html m (Maybe a)`

, where the event handlers are lifted into the `Maybe`

monad using `fmap`

(so they will have the same effect when the model is `Just`

and they will not affect the model when the model is `Nothing`

).

Given an isomorphism, you can change the type of an element from one side of the isomorphism to the other side. An isomorphism from a type `a`

to a type `b`

consists of a function `f :: a -> b`

and a function `g :: b -> a`

such that `f . g = id`

and `g . f = id`

. You can change an element `x :: Html m a`

in the following way: `pimap (piiso f g) x :: Html m b`

.

There is one more way of changing the model type of an element which you are likely to need, which is lifting into coproducts. Let’s say that you have two views in your app, represented by models of types `a`

and `b`

respectively. Then you can have an overall model of type `Either a b`

. How can you combine elements `x :: Html m a`

and `y :: Html m b`

into the same structure?

In this scenario it will make more sense to think of view functions as opposed to elements. By a view function, I mean a function which goes from the value of the model to an element. So let’s suppose we have view functions `v :: a -> Html m a`

and `u :: b -> Html m b`

. Then we can combine them as `eitherH v u :: Either a b -> Html m (Either a b)`

. This combined element will show the view `v`

when the model is a `Left`

and the view `u`

when the model is a `Right`

.

If you wish to have multiple views combined in this way but you do not want your model type to be an `Either`

type, then you can combine this coproduct pattern with an isomorphism. Suppose that `f :: Either a b -> Model`

and `g :: Model -> Either a b`

constitute an isomorphism, and `v`

and `u`

are as above. Then: `pimap (piiso f g) . eitherH v u . g :: Model -> Html m Model`

.

For examples of many of these patterns, see the Servant CRUD example.