Module

Halogen

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

The base Halogen module re-exports most of the library's useful types and combinators, aside from the HTML-building functionality - the HTML modules export a large number of commonly named values that are likely to conflict.

#HalogenIO Source

type HalogenIO query output m = { dispose :: m Unit, query :: forall a. query a -> m (Maybe a), subscribe :: Consumer output m Unit -> m Unit }

A record produced when the root component in a Halogen UI has been run.

  • query allows external sources to query the root component
  • subscribe allows external consumers to receive messages raised by the root component
  • dispose stops running the UI and finalizes the root component

Re-exports from Data.Lazy

#defer Source

defer :: forall a. (Unit -> a) -> Lazy a

Defer a computation, creating a Lazy value.

Re-exports from Halogen.Component

#ComponentSpec Source

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

The spec for a component.

The type variables involved:

  • surface is the type that will be rendered by the component, usually HTML
  • 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.

#ComponentSlotSpec Source

type ComponentSlotSpec surface query input output slots m action = { component :: Component surface 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.

#ComponentSlot Source

data ComponentSlot surface slots m action

Instances

#Component Source

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

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

  • surface is the type that will be rendered by the component, usually 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

#unComponentSlot Source

unComponentSlot :: forall a action m slots surface. (forall output input query. ComponentSlotSpec surface query input output slots m action -> a) -> ComponentSlotBox surface 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.

#unComponent Source

unComponent :: forall a m output input query surface. (forall slots action state. ComponentSpec surface state query action slots input output m -> a) -> Component surface 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.

#mkEval Source

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

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

``purescript -- 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 }


#mkComponent Source

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

Constructs a Component from a ComponentSpec.

#hoist Source

hoist :: forall m' m output input query surface. Bifunctor surface => Functor m' => (m ~> m') -> Component surface query input output m -> Component surface 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.

#defaultEval Source

defaultEval :: forall m output input slots action query state. 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 })
  }

#componentSlot Source

componentSlot :: forall _1 slot label action m slots output input query surface. Cons label (Slot query output slot) _1 slots => IsSymbol label => Ord slot => SProxy label -> slot -> Component surface query input output m -> input -> (output -> Maybe action) -> ComponentSlotBox surface 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

Re-exports from Halogen.Data.Slot

#Slot Source

data Slot (query :: Type -> Type) output slot

A type which records the queries, output messages, and slot identifier for a particular slot (ie. a location in HTML where a component is rendered). For example:

type ButtonSlot slot = Slot Button.Query Button.Output slot

-- A component using this slot type can have one type of child component,
-- which supports `Button.Query` queries, `Button.Output` outputs, and
-- which can be uniquely identified by an integer.
type Slots = ( button :: ButtonSlot Int )
  • query represents the requests that can be made of this component
  • output represents the output messages that can be raised by this component
  • slot represents the unique identifier for this component

Re-exports from Halogen.HTML

#ComponentHTML Source

type ComponentHTML action slots m = HTML (ComponentSlot HTML slots m action) action

A convenience synonym for the output type of a render function for a component that renders HTML.

  • action is the type of actions, events internal to the component that can be evaluated with the handleAction function
  • slots is the set of child component types that can be used in the HTML
  • m is the monad used by the child component during evaluation

Re-exports from Halogen.HTML.Core

#PropName Source

newtype PropName value

A type-safe wrapper for property names.

The phantom type value describes the type of value which this property requires.

Constructors

Instances

#ElemName Source

#ClassName Source

newtype ClassName

A wrapper for strings which are used as CSS classes.

Constructors

Instances

#AttrName Source

newtype AttrName

A type-safe wrapper for attribute names.

Constructors

Instances

Re-exports from Halogen.Query

#Tell Source

type Tell f = Unit -> f Unit

Type synonym for a "tell-style" query - queries that only cause effects, but that cannot receive a return value.

In a query algebra, a tell constructor carries the algebra's type variable as its last argument. For example:

data Query a
  = SomeTell a
  | SomeOtherTell String a
  | NotATell (Boolean -> a)

Both SomeTell and SomeOtherTell carry a plain a as a value, whereas NotATell has a as the result of a function so is considered to be a "request" (see below).

#SubscriptionId Source

newtype SubscriptionId

The ID value associated with a subscription. Allows the subscription to be stopped at a later time.

Instances

#Request Source

type Request f a = (a -> a) -> f a

Type synonym for an "request-style" query - queries that can cause effects as well as fetching some information from a component.

In a query algebra, a request constructor carries the algebra's type variable as the return value of a function as its last argument. For example:

data Query a = SomeRequest (Boolean -> a)

#RefLabel Source

#HalogenQ Source

data HalogenQ query action input a

Constructors

Instances

#HalogenM Source

newtype HalogenM state action slots output m a

The Halogen component eval effect monad.

  • state is the component's state
  • action is the type of actions; veents internal to the component that can be evaluated
  • slots is the set of slots for addressing child components
  • output is the type of output messages the component can raise
  • m is the monad used during evaluation
  • a is the result of the HalogenM expression. Use the following pattern: handleAction :: Action -> H.HalogenM State Action Slots Output m UnithandleQuery :: forall a. Query a -> H.HalogenM State Action Slots Output m (Maybe a)

Constructors

Instances

#HalogenF Source

data HalogenF state action slots output m a

The Halogen component eval algebra.

  • state is the component's state
  • action is the type of actions; events internal to the component that can be evaluated
  • slots is the set of slots for addressing child components
  • output is the type of output messages the component can raise
  • m is the monad used during evaluation
  • a is the result of the HalogenF expression (see HalogenM for an example).

Constructors

Instances

#ForkId Source

newtype ForkId

The ID value associated with a forked process. Allows the fork to be killed at a later time.

Instances

#unsubscribe Source

unsubscribe :: forall m output slots action state. SubscriptionId -> HalogenM state action slots output m Unit

Unsubscribes a component from an EventSource. If the subscription associated with the ID has already ended this will have no effect.

#tell Source

tell :: forall f. Tell f -> f Unit

Takes a data constructor of query algebra f and creates a tell query.

For example:

data Query a = Tick a

sendTick :: forall o. H.HalogenIO Query o Aff -> Aff (Maybe Unit)
sendTick app = app.query (H.tell Tick)

#subscribe' Source

subscribe' :: forall m output slots action state. (SubscriptionId -> EventSource m action) -> HalogenM state action slots output m Unit

An alternative to subscribe, intended for subscriptions that unsubscribe themselves. Instead of returning the SubscriptionId from subscribe', it is passed into an EventSource constructor. This allows emitted queries to include the SubscriptionId, rather than storing it in the state of the component.

When a component is disposed of any active subscriptions will automatically be stopped and no further subscriptions will be possible during finalization.

#subscribe Source

subscribe :: forall m output slots action state. EventSource m action -> HalogenM state action slots output m SubscriptionId

Subscribes a component to an EventSource.

When a component is disposed of any active subscriptions will automatically be stopped and no further subscriptions will be possible during finalization.

#request Source

request :: forall a f. Request f a -> f a

Takes a data constructor of query algebra f and creates a request query.

For example:

data Query a = GetTickCount (Int -> a)

getTickCount :: forall o. H.HalogenIO Query o Aff -> Aff (Maybe Int)
getTickCount app = app.query (H.request GetTickCount)

#raise Source

raise :: forall m output slots action state. output -> HalogenM state action slots output m Unit

Raises an output message for the component.

#queryAll Source

queryAll :: forall _1 a slot output' query slots label m output action state. Cons label (Slot query output' slot) _1 slots => IsSymbol label => Ord slot => SProxy label -> query a -> HalogenM state action slots output m (Map slot a)

Sends a query to all children of a component at a given slot label.

#query Source

query :: forall _1 a slot output' query slots label m output action state. Cons label (Slot query output' slot) _1 slots => IsSymbol label => Ord slot => SProxy label -> slot -> query a -> HalogenM state action slots output m (Maybe a)

Sends a query to a child of a component at the specified slot.

#put Source

put :: forall s m. MonadState s m => s -> m Unit

Set the state.

#modify_ Source

modify_ :: forall m s. MonadState s m => (s -> s) -> m Unit

#modify Source

modify :: forall m s. MonadState s m => (s -> s) -> m s

Modify the state by applying a function to the current state. The returned value is the new state value.

#liftEffect Source

liftEffect :: forall m a. MonadEffect m => Effect a -> m a

#liftAff Source

liftAff :: forall m. MonadAff m => Aff ~> m

#lift Source

lift :: forall t a m. MonadTrans t => Monad m => m a -> t m a

#kill Source

kill :: forall m output slots action state. ForkId -> HalogenM state action slots output m Unit

Kills a forked process if it is still running. Attempting to kill a forked process that has already ended will have no effect.

#gets Source

gets :: forall a m s. MonadState s m => (s -> a) -> m a

Get a value which depends on the current state.

#getRef Source

getRef :: forall m output slots action state. RefLabel -> HalogenM state action slots output m (Maybe Element)

Retrieves an Element value that is associated with a Ref in the rendered output of a component. If there is no currently rendered value for the requested ref this will return Nothing.

#getHTMLElementRef Source

getHTMLElementRef :: forall m output slots action surface. RefLabel -> HalogenM surface action slots output m (Maybe HTMLElement)

Retrieves a HTMLElement value that is associated with a Ref in the rendered output of a component. If there is no currently rendered value (or it is not an HTMLElement) for the request will return Nothing.

#get Source

get :: forall s m. MonadState s m => m s

Get the current state.

#fork Source

fork :: forall m output slots action state. HalogenM state action slots output m Unit -> HalogenM state action slots output m ForkId

Starts a HalogenM process running independent from the current eval "thread".

A commonly use case for fork is in component initializers where some async action is started. Normally all interaction with the component will be blocked until the initializer completes, but if the async action is forked instead, the initializer can complete synchronously while the async action continues.

Some care needs to be taken when using a fork that can modify the component state, as it's easy for the forked process to "clobber" the state (overwrite some or all of it with an old value) by mistake.

When a component is disposed of any active forks will automatically be killed. New forks can be started during finalization but there will be no means of killing them.