Module

Halogen.Component

Package
purescript-halogen
Repository
purescript-halogen/purescript-halogen

#Component Source

data Component :: (Type -> Type) -> Type -> Type -> (Type -> Type) -> Typedata Component (query :: Type -> Type) (input :: Type) (output :: Type) (m :: Type -> Type)

The "public" type for a component, with details of the component internals existentially hidden.

HTML

  • query is the query algebra; the requests that can be made of the component
  • input is the input value that will be received when the parent of this component renders
  • output is the type of messages the component can raise
  • m is the effect monad used during evaluation

#ComponentSpec Source

type ComponentSpec :: Type -> (Type -> Type) -> Type -> Row Type -> Type -> Type -> (Type -> Type) -> Typetype ComponentSpec state query action slots input output m = { eval :: (HalogenQ query action input) ~> (HalogenM state action slots output m), initialState :: input -> state, render :: state -> HTML (ComponentSlot slots m action) action }

The spec for a component.

The type variables involved:

  • state is the component's state
  • query is the query algebra; the requests that can be made of the component
  • action is the type of actions; messages internal to the component that can be evaluated
  • slots is the set of slots for addressing child components
  • input is the input value that will be received when the parent of this component renders
  • output is the type of messages the component can raise
  • m is the effect monad used during evaluation

The values in the record:

  • initialState is a function that accepts an input value and produces the state the component will start with. If the input value is unused (Unit), or irrelevant to the state construction, this will often be const ?someInitialStateValue.
  • render is a function that accepts the component's current state and produces a value to render (HTML usually). The rendered output can raise actions that will be handled in eval.
  • eval is a function that handles the HalogenQ algebra that deals with component lifecycle, handling actions, and responding to requests.

#mkComponent Source

mkComponent :: forall state query action slots input output m. ComponentSpec state query action slots input output m -> Component query input output m

Constructs a Component from a ComponentSpec.

#unComponent Source

unComponent :: forall query input output m a. (forall state action slots. ComponentSpec state query action slots input output m -> a) -> Component query input output m -> a

Exposes the inner details of a Component to a function to produce a new result.

The hidden details will not be allowed to be revealed in the result of the function - if any of the hidden types (state, action, set of slots) appear in the result, the compiler will complain about an escaped skolem.

#hoist Source

hoist :: forall query input output m m'. Functor m' => (m ~> m') -> Component query input output m -> Component query input output m'

Changes the Component's m type. A use case for this might be to interpret some Free monad as Aff so the component can be used with runUI.

#EvalSpec Source

type EvalSpec :: Type -> (Type -> Type) -> Type -> Row Type -> Type -> Type -> (Type -> Type) -> Typetype EvalSpec state query action slots input output m = { finalize :: Maybe action, handleAction :: action -> HalogenM state action slots output m Unit, handleQuery :: forall a. query a -> HalogenM state action slots output m (Maybe a), initialize :: Maybe action, receive :: input -> Maybe action }

The spec record that mkEval accepts to construct a component eval function.

It's not a requirement to use mkEval, and sometimes it's preferrable to write a component eval function from scratch, but often mkEval is more convenient for common cases.

See below for more details about mkEval and defaultEval.

#mkEval Source

mkEval :: forall state query action slots input output m a. EvalSpec state query action slots input output m -> HalogenQ query action input a -> HalogenM state action slots output m a

Accepts an EvalSpec to produce an eval function for a component. For example:

-- use `defaultEval` and override fields selectively
H.mkEval (H.defaultEval { handleAction = ?handleAction })

-- or specify all the fields in the `EvalSpec`
H.mkEval
  { handleAction: ?handleAction
  , handleQuery: ?handleQuery
  , receive: ?receive
  , initialize: ?initialize
  , finalize: ?finalize
  }

#defaultEval Source

defaultEval :: forall state query action slots input output m. EvalSpec state query action slots input output m

A default value for mkEval that will result in an eval that nothing at all - all incoming actions and queries will be ignored, and no receiver, initializer, or finalizer will be specified.

Usually this will be used with record update syntax to override fields to specify things as needed. If a component only needs to handle actions, for instance, a usage might be something like this:

H.mkComponent
  { initialState
  , render
  , eval: H.mkEval (H.defaultEval { handleAction = ?handleAction })
  }

#ComponentSlotBox Source

data ComponentSlotBox :: Row Type -> (Type -> Type) -> Type -> Typedata ComponentSlotBox (slots :: Row Type) (m :: Type -> Type) (action :: Type)

A slot for a child component in a component's rendered content.

Instances

#ComponentSlot Source

data ComponentSlot :: Row Type -> (Type -> Type) -> Type -> Typedata ComponentSlot slots m action

Constructors

Instances

#componentSlot Source

componentSlot :: forall query input output slots m action label slot _1. Cons label (Slot query output slot) _1 slots => IsSymbol label => Ord slot => Proxy label -> slot -> Component query input output m -> input -> (output -> Maybe action) -> ComponentSlotBox slots m action

Constructs a ComponentSlot.

Takes:

  • the slot address label
  • the slot address index
  • the component for the slot
  • the input value to pass to the component
  • a function mapping outputs from the component to a query in the parent

#ComponentSlotSpec Source

type ComponentSlotSpec :: (Type -> Type) -> Type -> Type -> Row Type -> (Type -> Type) -> Type -> Typetype ComponentSlotSpec query input output slots m action = { component :: Component query input output m, get :: forall slot. SlotStorage slots slot -> Maybe (slot query output), input :: input, output :: output -> Maybe action, pop :: forall slot. SlotStorage slots slot -> Maybe (Tuple (slot query output) (SlotStorage slots slot)), set :: forall slot. slot query output -> SlotStorage slots slot -> SlotStorage slots slot }

The internal representation used for a ComponentSlot.

#mkComponentSlot Source

mkComponentSlot :: forall query input output slots m action. ComponentSlotSpec query input output slots m action -> ComponentSlotBox slots m action

Constructs ComponentSlotBox from a ComponentSlotSpec.

#unComponentSlot Source

unComponentSlot :: forall slots m action a. (forall query input output. ComponentSlotSpec query input output slots m action -> a) -> ComponentSlotBox slots m action -> a

Exposes the inner details of a ComponentSlot to a function to produce a new result.

The hidden details will not be allowed to be revealed in the result of the function - if any of the hidden types (state, action, set of slots) appear in the result, the compiler will complain about an escaped skolem.

#hoistSlot Source

hoistSlot :: forall slots m m' action. Functor m' => (m ~> m') -> ComponentSlot slots m action -> ComponentSlot slots m' action

Changes the ComponentSlot's m type.