This module introduces a simple callback utility that allows information to be passed upwards in the model-update hierarchy. The pattern is similar to event handling in object-oriented languages, in the sense that we can think of a nested model as an event source, and of the parent as a listener. The event listener is then able to respond to state changes by hooking into the event source via one or more callbacks (event handlers).

Usage example:

The following example shows how to implement an update function with support for callbacks. Scroll down for explanations of the indicated points in the code.

module Main exposing (..)


import Browser exposing (Document, document)
import Html exposing (Html, button, span, text)
import Html.Attributes as Attributes
import Html.Events exposing (onClick)
import Update.Pipeline exposing (..)
import Update.Pipeline.Extended exposing (..)


type FeatureMsg
    = OnClick Bool


type alias Feature =
    {}


initFeature : ( Feature, Cmd FeatureMsg )
initFeature =
    save {}


{- #1 -}
updateFeature :
    FeatureMsg
    -> { onClick : Bool -> a }
    -> Extended Feature a
    -> ( Extended Feature a, Cmd FeatureMsg )
updateFeature msg { onClick } model =
    case msg of
        OnClick choice ->
            {- #2 -}
            model
                |> call (onClick choice)


viewFeature : Feature -> Html FeatureMsg
viewFeature _ =
    span []
        [ button
            [ onClick (OnClick True) ]
            [ text "Yay" ]
        , button
            [ onClick (OnClick False) ]
            [ text "Nay" ]
        ]


type Msg
    = FeatureMsg FeatureMsg


type alias Model =
    { feature : Feature
    , clicked : Bool
    , choice : Maybe Bool
    }


insertAsFeatureIn : Model -> Feature -> ( Model, Cmd Msg )
insertAsFeatureIn model feature =
    save { model | feature = feature }


{- #3 -}
inFeature : Run Model Feature Msg FeatureMsg a
inFeature =
    runStack .feature insertAsFeatureIn FeatureMsg


init : () -> ( Model, Cmd Msg )
init () =
    map3 Model
        (mapCmd FeatureMsg initFeature)
        (save False)
        (save Nothing)


{- #4 -}
handleClick :
    Bool
    -> Model
    -> ( Model, Cmd Msg )
handleClick choice model =
    save
        { model
            | clicked = True
            , choice = Just choice
        }


update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        FeatureMsg featureMsg ->
            {- #5 -}
            model
                |> inFeature
                    (updateFeature featureMsg
                        { onClick = handleClick }
                    )


subscriptions : Model -> Sub Msg
subscriptions _ =
    Sub.none


view : Model -> Document Msg
view { feature, clicked, choice } =
    { title = ""
    , body =
        [ if clicked then
            let
                choiceStr =
                    case choice of
                        Just True ->
                            "yay"


                        _ ->
                            "nay"
            in
            text ("You chose " ++ choiceStr ++ "!")


          else
            Html.map FeatureMsg (viewFeature feature)
        ]
    }


main : Program () Model Msg
main =
    document
        { init = init
        , update = update
        , subscriptions = subscriptions
        , view = view
        }

Explanation:

1. The update function is atypical in the following ways:

   • Instead of the usual

     msg -> m -> ( m, Cmd msg )

     … we change the type so that it ends with

     Extended m a -> ( Extended m a, Cmd msg )

   • The second argument is a record containing a callback

     onClick : Bool -> a

     In general, we can have any number of these functions. The type of a callback is always of the form

     arg1 -> arg2 -> ... -> a

2. Using call, we add a function to the list of callbacks, which is eventually returned together with the model. Think of this simply as invoking the callback.

3. Partially applied, runStack gives us a function that takes care of updating the nested Feature model in a way that also accommodates for the extra callback structure. The actual type of the resulting function is slightly complicated, so we’ll typically use the Run alias to make things more readable.

4. The handler’s type has to match that of the callback. The type parameter a is expanded to m -> ( m, Cmd msg ), where m is the type of the parent model. So, in this example

   Bool -> a

   … becomes

   Bool -> Model -> ( Model, Cmd Msg )

5. Finally, in the parent model’s update function, we use the inFeature helper (see #3) to update the nested model and apply the callbacks.

Types

Callback Interface

Shortcuts

Pointful Helpers