Events.md

Module Html.Events

It is often helpful to create an Union Type so you can have many different kinds of events as seen in the TodoMVC example.

For Purescript, an Eq constraint has been added to a variety of function signatures here. In most cases, you should be able to ask the compiler to derive an Eq instance. If you really can't have an Eq instance, then we could supply variants which don't require an Eq instance. (In fact, if you look at the source, you ought to be able to construct them yourself).

onClick

onClick :: forall msg. Eq msg => msg -> Attribute msg

onDoubleClick

onDoubleClick :: forall msg. Eq msg => msg -> Attribute msg

onMouseDown

onMouseDown :: forall msg. Eq msg => msg -> Attribute msg

onMouseUp

onMouseUp :: forall msg. Eq msg => msg -> Attribute msg

onMouseEnter

onMouseEnter :: forall msg. Eq msg => msg -> Attribute msg

onMouseLeave

onMouseLeave :: forall msg. Eq msg => msg -> Attribute msg

onMouseOver

onMouseOver :: forall msg. Eq msg => msg -> Attribute msg

onMouseOut

onMouseOut :: forall msg. Eq msg => msg -> Attribute msg

onInput

onInput :: forall msg. (String -> msg) -> Attribute msg

Capture input events for things like text fields or text areas.

It grabs the string value at event.target.value, so it will not work if you need some other type of information. For example, if you want to track inputs on a range slider, make a custom handler with on.

For more details on how onInput works, check out targetValue.

onCheck

onCheck :: forall msg. (Bool -> msg) -> Attribute msg

Capture change events on checkboxes. It will grab the boolean value from event.target.checked on any input event.

Check out targetChecked for more details on how this works.

onSubmit

onSubmit :: forall msg. Eq msg => msg -> Attribute msg

Capture a submit event with preventDefault in order to prevent the form from changing the page’s location. If you need different behavior, use onWithOptions to create a customized version of onSubmit.

onBlur

onBlur :: forall msg. Eq msg => msg -> Attribute msg

onFocus

onFocus :: forall msg. Eq msg => msg -> Attribute msg

on

on :: forall msg. String -> Decoder msg -> Attribute msg

Create a custom event listener. Normally this will not be necessary, but you have the power! Here is how onClick is defined for example:

import Json.Decode as Json

onClick : msg -> Attribute msg
onClick message =
  on "click" (Json.succeed message)

The first argument is the event name in the same format as with JavaScript's addEventListener function.

The second argument is a JSON decoder. Read more about these here. When an event occurs, the decoder tries to turn the event object into an Elm value. If successful, the value is routed to your update function. In the case of onClick we always just succeed with the given message.

If this is confusing, work through the Elm Architecture Tutorial. It really does help!

onWithOptions

onWithOptions :: forall msg. String -> Options -> Decoder msg -> Attribute msg

Same as on but you can set a few options.

Options

type Options = { stopPropagation :: Bool, preventDefault :: Bool }

Options for an event listener. If stopPropagation is true, it means the event stops traveling through the DOM so it will not trigger any other event listeners. If preventDefault is true, any built-in browser behavior related to the event is prevented. For example, this is used with touch events when you want to treat them as gestures of your own, not as scrolls.

defaultOptions

defaultOptions :: Options

Everything is False by default.

defaultOptions =
    { stopPropagation = False
    , preventDefault = False
    }

targetValue

targetValue :: Decoder String

A Json.Decoder for grabbing event.target.value. We use this to define onInput as follows:

import Json.Decode as Json

onInput : (String -> msg) -> Attribute msg
onInput tagger =
  on "input" (Json.map tagger targetValue)

You probably will never need this, but hopefully it gives some insights into how to make custom event handlers.

targetChecked

targetChecked :: Decoder Bool

A Json.Decoder for grabbing event.target.checked. We use this to define onCheck as follows:

import Json.Decode as Json

onCheck : (Bool -> msg) -> Attribute msg
onCheck tagger =
  on "input" (Json.map tagger targetChecked)

keyCode

keyCode :: Decoder Int

A Json.Decoder for grabbing event.keyCode. This helps you define keyboard listeners like this:

import Json.Decode as Json

onKeyUp : (Int -> msg) -> Attribute msg
onKeyUp tagger =
  on "keyup" (Json.map tagger keyCode)

Note: It looks like the spec is moving away from event.keyCode and towards event.key. Once this is supported in more browsers, we may add helpers here for onKeyUp, onKeyDown, onKeyPress, etc.