docs.json

[{"name":"ColorPicker","comment":" The interface to a color picking service.  This service provides other\nsub-compnents the ability to request that the user pick a color.\n\nColors are represented as CSS color value strings. I.E.: `#f7d87e`.\n\nSee the very similar `SizePicker` service for a more detailed discussion of\n  how this is structured.\n\n# Requests\n@docs Request, askForColor\n\n# Fancy Stuff\n@docs mapRequest\n\n","unions":[{"name":"Request","comment":"","args":["msg"],"cases":[["RequestColor",["String.String","String.String -> msg"]]]}],"aliases":[],"values":[{"name":"askForColor","comment":" Create a reqeust for the color picker service to ask the user for a color.\nWhen the user has chosen a color, it will be used with the supplied function\nto create a message object, which will be routed to your `update` function.\n\nThe supplied string is used to identify the request to the user.\n","type":"String.String -> (String.String -> msg) -> ColorPicker.Request msg"},{"name":"mapRequest","comment":"","type":"(msg1 -> msg2) -> ColorPicker.Request msg1 -> ColorPicker.Request msg2"}],"binops":[]},{"name":"ColorPicker.Service","comment":" The implementation of the color picker service.\n\nSee `SizePicker.Service` for commentary and details, since this service is\nimplemented in exactly the same way.\n\n# Types\n@docs Id, Model, init, Msg\n\n# Functions\n@docs update, request, view, subscriptions\n","unions":[{"name":"Model","comment":"","args":["top"],"cases":[]},{"name":"Msg","comment":"","args":[],"cases":[]}],"aliases":[{"name":"Id","comment":"","args":[],"type":"Basics.Int"}],"values":[{"name":"init","comment":"","type":"ColorPicker.Service.Model top"},{"name":"request","comment":"","type":"ColorPicker.Request top -> ColorPicker.Service.Model top -> ( ColorPicker.Service.Model top, Command.Command ColorPicker.Service.Msg, List.List top )"},{"name":"subscriptions","comment":"","type":"ColorPicker.Service.Model top -> Platform.Sub.Sub ColorPicker.Service.Msg"},{"name":"update","comment":"","type":"ColorPicker.Service.Msg -> ColorPicker.Service.Model top -> ( ColorPicker.Service.Model top, Command.Command ColorPicker.Service.Msg, List.List top )"},{"name":"view","comment":"","type":"ColorPicker.Service.Model top -> Html.Html ColorPicker.Service.Msg"}],"binops":[]},{"name":"Command","comment":" A meta-command type that encapsulates all the command-like things a\ncomponent might make.\n\n`Command` is completely analagous to `Cmd`, only in addition to including\n`Cmd` values, it can include requests to service components that are in the\napplication.\n\nLike `Cmd`, `Command` is parametric in the type of messages that it's requests\nmight generate as responses. See `map`.\n\n# Commands\n@docs Command, none, batch\n\n# Fancy Stuff\n@docs map\n\n---\n# Narrative Path\nContinue on with [`SizePicker.Service`](SizePicker-Service)...\n","unions":[{"name":"Command","comment":" The command type. There are constructors for all the types of commands in\nthe whole application.\n","args":["msg"],"cases":[["NoCommand",[]],["Cmd",["Platform.Cmd.Cmd msg"]],["ColorPicker",["ColorPicker.Request msg"]],["SizePicker",["SizePicker.Request msg"]],["Batch",["List.List (Command.Command msg)"]]]}],"aliases":[],"values":[{"name":"batch","comment":" Convert a list of commands into a single command\n","type":"List.List (Command.Command msg) -> Command.Command msg"},{"name":"map","comment":" Maps `Commands` from one message type to another. Usually used so that\n`Commands` generated in sub-components (which use the sub-component's\n`msg` type) can be handled in the parent component.\n\n    type alias ParentModel = { ... childModel : Child.Model, ... }\n    type ParentMsg = ... | ChildMsg Child.Msg | ...\n    \n    update : ParentMsg -> ParentModel -> (ParentModel, Command ParentMsg)\n    update msg model =\n      case msg of\n        ...\n        ChildMsg childMsg ->\n          let\n            (childModel, childCommand) = Child.update childMsg model.childModel\n          in\n            ( { model | childModel = childModel }\n            , Command.map ChildMsg childCommand\n            )\n","type":"(msg1 -> msg2) -> Command.Command msg1 -> Command.Command msg2"},{"name":"none","comment":" No command to be done.\n","type":"Command.Command msg"}],"binops":[]},{"name":"SizePicker","comment":" The interface to a size picking service. This service provides other\nsub-components the ability to request that the user pick a size. The UI for\nthe size picking is handled by the service, and is not within the calling\nsub-components view.\n\nClients of this code can think of it in the same way as a `port`: You make\na request by calling a function that returns a value which is returned\nfrom its `update` function to the containing component. That request value\nmay contain a message function, so that a `Msg` is delivered to the client at\na later time.\n\nExample:\n\n    import Command\n    import SizePicker\n    \n    type alias Model = Maybe Int\n\n    type Msg =\n      = Start\n      | SetSize Int\n\n    update : Msg -> Model -> (Model, Command Msg)\n    update msg model =\n      case msg of\n        Start\n          -> (Nothing, Command.SizePicker <| SizePicker.askForSize SetSize)\n\n        SetSize size\n          -> (Just Size, Command.none)\n\n# Requests\n@docs Request, askForSize\n\n# Fancy Stuff\n@docs mapRequest\n\n---\n# Narrative Path\nContinue on with [`Sub1`](Sub1)...\n","unions":[{"name":"Request","comment":" Requests that the size picking service can accept.\n\nNormally, a client uses a convience function, like `askForSize`, to build a\nrequest, and the wraps the request to make it a `Command`:\n\n    update : Msg -> Model -> (Model, Command Msg)\n    update msg model =\n      ...\n      let\n        model_ = ...\n        command_ = Command.SizePicker <| askForSize \"Pikachu\" SetSize\n      in\n        (model_, command_)\n\nGenerally, clients are expected to use the request building functions (like\n`askForSize`) rather than these constructors directly.\n\nThe constructors are exposed so that the implementation, `SizePicker.Service`\ncan pattern match on them. There is no real issue with lack of encapsulation\nhere because any information in these constructors has to have come from the\nclient anyway.\n","args":["msg"],"cases":[["RequestSize",["String.String","Basics.Int -> msg"]]]}],"aliases":[],"values":[{"name":"askForSize","comment":" Create a request for the size picker service to ask the user for a size.\nWhen the user has chosen a size, it will be passed to the supplied function\nto create a message object, which will be routed to your `update` function.\n\nThe supplied string is used to identify the request to the user.\n","type":"String.String -> (Basics.Int -> msg) -> SizePicker.Request msg"},{"name":"mapRequest","comment":" Convert a `Request` based one message type to another. This is analogous\nto `Cmd.map`. It lets parent components handle requests made by children\ncomponents.  However, parent components don't usualy call this directly, but\nuse `Command.map` (which calls this internally).\n","type":"(msg1 -> msg2) -> SizePicker.Request msg1 -> SizePicker.Request msg2"}],"binops":[]},{"name":"SizePicker.Service","comment":" The implementation of the size picker service.\n\nFor the most part, this is structured like any other sub-component, with \n`Model` and `Msg` types, and `update`, `view`, and `subscriptions` functions.\n\nThe only differences are:\n  1. The `Model` type is parametric on the _top component's `Msg` type_\n  2. The addition of a `request` function.\n  3. The return tuple of `request` and `update` has an additional value\n\n# Types\n@docs Id, Model, init, Msg\n\n# Functions\n@docs update, request, view, subscriptions\n\n---\n# Narrative Path\nContinue on with [`Top`](Top)...\n","unions":[{"name":"Model","comment":" The model of the service must be parametric on the message type of the\ncomponent that contains it. This is usually the top component in the\napplication.\n\nThe reason for this can be seen in the dictionary of pending requests: The\nrequest includes a function that maps the response (the picked size) to a\nmessage to be re-injected into the program, via the top component's `update`\nfunction.\n","args":["top"],"cases":[["Model",["{ nextId : SizePicker.Service.Id, pending : Dict.Dict SizePicker.Service.Id ( String.String, Basics.Int -> top ) }"]]]},{"name":"Msg","comment":" The message type of this service, as a sub-component.\n","args":[],"cases":[]}],"aliases":[{"name":"Id","comment":" Internal ids are used to tag the requests in progress.\n","args":[],"type":"Basics.Int"}],"values":[{"name":"init","comment":"","type":"SizePicker.Service.Model top"},{"name":"request","comment":" This is almost identical in every way to `update`, only it handles a\n`Request`, not a `Msg`. Upon progressing the request, the model may have\nchanged, new `Command`s issues, and even other response messages returned.\n\nNotice that `Request` here is parameterized by `top`. This is because by the\ntime a `Request` from a child component had bubbled up to the top component\nfor dispatch to this function, it has been mapped (`Command.map`) to the\ntop component's message type.\n","type":"SizePicker.Request top -> SizePicker.Service.Model top -> ( SizePicker.Service.Model top, Command.Command SizePicker.Service.Msg, List.List top )"},{"name":"subscriptions","comment":"","type":"SizePicker.Service.Model top -> Platform.Sub.Sub SizePicker.Service.Msg"},{"name":"update","comment":" This like a standard sub-component update function with an addition:\nThe returned tuple has a third value, `List top`, that is a list of top-level\nmessages that should be operated on after this update. These are the messages\nback to requesting sub-components.\n","type":"SizePicker.Service.Msg -> SizePicker.Service.Model top -> ( SizePicker.Service.Model top, Command.Command SizePicker.Service.Msg, List.List top )"},{"name":"view","comment":"","type":"SizePicker.Service.Model top -> Html.Html SizePicker.Service.Msg"}],"binops":[]},{"name":"Sub1","comment":" A simple sub-component that draws a box. It uses the `SizePicker` and\n`ColorPicker` services to let the user pick the size and color of the box.\n\nFor simplicity of the example, colors here are just strings with CSS color\nvalues.\n\n# Component Types\n@docs Model, init, Msg\n\n# Component Functions\n@docs update, view, subscriptions\n\n---\n# Narrative Path\nContinue on with [`Command`](Command)...\n","unions":[{"name":"Model","comment":"","args":[],"cases":[]},{"name":"Msg","comment":" The `Pick` constructors are messages from the `onClick` handlers in the\nview to indicate the user has clicked the button to pick a value.\n\nThe `Set` constructors are messages from the picker services saying that the\nvalue has been picked.\n","args":[],"cases":[["PickSize",[]],["PickColor",[]],["SetSize",["Basics.Int"]],["SetColor",["String.String"]]]}],"aliases":[],"values":[{"name":"init","comment":"","type":"Sub1.Model"},{"name":"subscriptions","comment":"","type":"Sub1.Model -> Platform.Sub.Sub Sub1.Msg"},{"name":"update","comment":" A standard sub-component `update` function, but notice that in the return\nvalue it has `Command Msg` rather than `Cmd Msg`. `Command` is a super set of\nboth the standard `Cmd` values, as well as the requests that other services in\nthe app offer. As a consequence, requests must be wrapped in the correct \n`Command` constructor:\n\n    Command.SizePicker <| SizePicker.askForSize \"Pikachu\" SetSize\n\nor\n\n    Command.Cmd <| somePortThing \n\n(You might think that `askForSize` could have done this wrapping, but it can't\nbecause it would lead to a circular import between `Command` and `SizePicker`!)\n","type":"Sub1.Msg -> Sub1.Model -> ( Sub1.Model, Command.Command Sub1.Msg )"},{"name":"view","comment":"","type":"Sub1.Model -> Html.Html Sub1.Msg"}],"binops":[]},{"name":"Sub2","comment":" A simple sub-component that draws a box. It uses the `SizePicker` \nservice twice to let the user pick the width and height of thebox.\n\nSee `Sub1` for details and commentary. This is implemented in exactly the \nsame way. \n\n# Component Types\n@docs Model, init, Msg\n\n# Component Functions\n@docs update, view, subscriptions\n","unions":[{"name":"Model","comment":"","args":[],"cases":[]},{"name":"Msg","comment":"","args":[],"cases":[]}],"aliases":[],"values":[{"name":"init","comment":"","type":"Sub2.Model"},{"name":"subscriptions","comment":"","type":"Sub2.Model -> Platform.Sub.Sub Sub2.Msg"},{"name":"update","comment":"","type":"Sub2.Msg -> Sub2.Model -> ( Sub2.Model, Command.Command Sub2.Msg )"},{"name":"view","comment":"","type":"Sub2.Model -> Html.Html Sub2.Msg"}],"binops":[]},{"name":"Top","comment":" This is the top component in the application. It contains four sub-\ncomponents: two are services and and two are normal sub-components.\n\nWeaving together subcomponents is a well established pattern in Elm. The\ncore of this whole project is the logic here that weaves together services\nas well. They are more complicating because updates to sub-components may\nresult in service requests, which must then be threaded through. And service\noperations may result in messages that need to get processed back to the\nsub-components.\n\nWhile this doc will walk though some of this, you are highly encouraged\nto read the source code.\n\n# Types\n@docs Model, init, Msg\n\n# Functions\n@docs update, view, subscriptions\n\n# Component Descriptors\n\nThese types and values make working with multiple components easy. While the\ntypes here are highly parameterized and a littly dizzing to read, they will\nmake the `update` function be almost trivial. Using these techniques, you\ncan easily incorporate dozens of sub-components and services in a top level\ncomponent.\n\nAn example descriptor is:\n\n    sub1 : Component Sub1.Model Sub1.Msg \n    sub1 =\n      { msgFn = Sub1Msg\n      , getModel = .sub1\n      , setModel = \\s m -> { m | sub1 = s }\n      , update = Sub1.update\n      }\n\nSee the source code for others.\n@docs ComponentBase, Component, Service\n\n# Processing Functions\n\nThese internal functions do the bulk of the work in calling a sub-component\nand processing te returned values. This mostly a nest of unwrapping and re-\nwrapping.\n\nSee the source code to see how they work.\n\n@docs processCommand, processCommandAndMessages, updateComponent, updateService, requestService\n\n---\n# Narrative Path\nNow go [browse the source](https://github.com/mzero/elm-service-pattern)...\n","unions":[{"name":"Msg","comment":" Standard message type for something with sub-components. There is a\nconstructor for each sub-component's msg type.\n\n(Those are different `Msg` types - click on them and see. This might be easier\nto read in the source code.)\n","args":[],"cases":[["NoOp",[]],["ColorPickerMsg",["ColorPicker.Service.Msg"]],["SizePickerMsg",["SizePicker.Service.Msg"]],["Sub1Msg",["Sub1.Msg"]],["Sub2Msg",["Sub2.Msg"]]]}],"aliases":[{"name":"Component","comment":" A regular component has a simple `update` function.\n","args":["model","msg"],"type":"Top.ComponentBase model msg { update : msg -> model -> ( model, Command.Command msg ) }"},{"name":"ComponentBase","comment":" A `ComponentBase` value describes a sub-component. It has the function for\nmapping the sub-component's message type into `Msg`, and functions for getting\nand setting the sub-component's model in `Model`.\n","args":["model","msg","a"],"type":"{ a | msgFn : msg -> Top.Msg, getModel : Top.Model -> model, setModel : model -> Top.Model -> Top.Model }"},{"name":"Model","comment":" Standard model type with fields for the sub-component models. Notice that\nfor services, their model type is parameterized by this top level's `Msg` type.\n","args":[],"type":"{ colorPicker : ColorPicker.Service.Model Top.Msg, sizePicker : SizePicker.Service.Model Top.Msg, sub1 : Sub1.Model, sub2 : Sub2.Model }"},{"name":"Service","comment":" A service has an update and a request function, and both may return\nadditional `Msg` values to be processed.\n","args":["model","msg","req"],"type":"Top.ComponentBase model msg { update : msg -> model -> ( model, Command.Command msg, List.List Top.Msg ), request : req -> model -> ( model, Command.Command msg, List.List Top.Msg ) }"}],"values":[{"name":"init","comment":"","type":"Top.Model"},{"name":"processCommand","comment":" `Command` values must be ultimately resolved into `Cmd` values so they can\nbe returned to the Elm framework. Where `Command` wraps a service request,\nthe service's `request` function will be called, and those results processed\nrecursively.\n","type":"Top.Model -> Command.Command Top.Msg -> ( Top.Model, Platform.Cmd.Cmd Top.Msg )"},{"name":"processCommandAndMessages","comment":" This is very simiilar to `processCommand`, but is used for services which\nreturn an additional `List Msg` to be processed. These are messages to be sent\nback to sub-components. This function handles them by calling this module's\nown `update` on them.\n","type":"Top.Model -> Command.Command Top.Msg -> List.List Top.Msg -> ( Top.Model, Platform.Cmd.Cmd Top.Msg )"},{"name":"requestService","comment":" Helper function for handling a request on a service. The logic is\nidentical to `updateService`, but usese the services `request` function\ninstead.\n","type":"Top.Service model msg req -> req -> Top.Model -> ( Top.Model, Platform.Cmd.Cmd Top.Msg )"},{"name":"subscriptions","comment":"","type":"Top.Model -> Platform.Sub.Sub Top.Msg"},{"name":"update","comment":" Given the complexity of services, you'd think this would have a hairy\nimplementation. But you'd be wrong! Given the component descriptors and\nprocessing helper functions, handling a component or service is a one liner:\n\n    case msg of\n      ...\n      SizePickerMsg spMsg -> updateService sizePicker spMsg model\n      ...\n\n","type":"Top.Msg -> Top.Model -> ( Top.Model, Platform.Cmd.Cmd Top.Msg )"},{"name":"updateComponent","comment":" Helper function for performing a component update. This involves getting\nthe components model from `Model`, calling its `update` function, and\nhandling the results.\n","type":"Top.Component model msg -> msg -> Top.Model -> ( Top.Model, Platform.Cmd.Cmd Top.Msg )"},{"name":"updateService","comment":" Like `updateComponent` but for services.\n","type":"Top.Service model msg req -> msg -> Top.Model -> ( Top.Model, Platform.Cmd.Cmd Top.Msg )"},{"name":"view","comment":"","type":"Top.Model -> Html.Html Top.Msg"}],"binops":[]}]