visotype / elm-dom / Dom

Element


type alias Element msg =
Internal.Element msg

Dom.Element is an opaque type that stores an internal record, defined here. The internal record contains all of the data needed to construct an Elm Html node. By using a record to temporarily store data about a node, we can partially construct that node with some data, but delay building it until all of the data has been assembled.

A new Element record is created when you call the element function. The record is then rendered to Html when it is added as a child element to another Element record, or when it is passed as an argument to the render function.

Because rendering is built into the functional development pattern of this package, it is often only necessary to call the render function once, on the root node of your DOM tree. (One notable exception is when you want to use the Html.Lazy optimization; see here for a very simple example of how you would implement that with this package).

Create and Render

element : String -> Element msg

Constructor for Element records. The string argument provides the HTML tag.

render : Element msg -> VirtualNode msg

Convert an Element record to Elm Html. This function only needs to be called once, on the root node of your DOM tree.

Build

Using a single argument...

to set the id attribute

setId : String -> Element msg -> Element msg

Sets or resets the id attribute

to add a class, style, or other attribute

addClass : String -> Element msg -> Element msg

Adds a class name to the current list

addStyle : ( String, String ) -> Element msg -> Element msg

Adds a style key/value pair to the current list

addAttribute : VirtualAttribute msg -> Element msg -> Element msg

Adds an attribute to the current list

Note: For complicated reasons, there is more than one VirtualDom primitive for assigning attributes to DOM elements. Unless you are really confident in what you are doing, I recommend using the constructors in Html.Attributes and Html.Events (or Svg.Attributes and Svg.Events) to ensure that the implementation used internally best matches the current spec.

to add an event listener

addAction : ( String, msg ) -> Element msg -> Element msg

Adds an action to the current list of event listeners

As defined here, an action is a simple event listener that does nothing except send a message to your Elm program's update function when the specified event is triggered. This is useful for responding to events like "click", "mouseover", "mouseout", and so on.

Event names in the DOM API are documented here.

addInputHandler : (String -> msg) -> Element msg -> Element msg

Adds an input handler for form elements to the current list of event listeners

Internally, this function is equivalent to Html.Events.onInput.

addChangeHandler : (String -> msg) -> Element msg -> Element msg

Adds value change handler for form elements to the current list of event listeners

This handler captures event.target.value on a "change" event, which can sometimes be useful when designing form interaction. Unlike the default input handler, it does not invoke the "stopPropagation" option.

addToggleHandler : (Basics.Bool -> msg) -> Element msg -> Element msg

Adds a toggle handler for checkboxes and radio buttons to the current list of event listeners

Internally, this function is equivalent to Html.Events.onCheck.

to append or prepend internal text

appendText : String -> Element msg -> Element msg

Adds a string to the end of the current text

prependText : String -> Element msg -> Element msg

Adds a string to the beginning of the current text

to append or prepend a child element

appendChild : Element msg -> Element msg -> Element msg

Renders an element (the first argument) and adds it to the end of the current child list (in the second argument)

prependChild : Element msg -> Element msg -> Element msg

Renders an element and adds it to the beginning of the current child list

appendNode : VirtualNode msg -> Element msg -> Element msg

Adds an Html node to the end of the the current child list

prependNode : VirtualNode msg -> Element msg -> Element msg

Adds an Html node to the beginning of the the current child list

Using a list argument...

to add a list of classes, styles, or other attributes

addClassList : List String -> Element msg -> Element msg

Adds a list of class names to the current list

addStyleList : List ( String, String ) -> Element msg -> Element msg

Adds a list of style key/value pairs to the current list

addAttributeList : List (VirtualAttribute msg) -> Element msg -> Element msg

Adds a list of attributes to the current list

to append or prepend a list of child elements

appendChildList : List (Element msg) -> Element msg -> Element msg

Renders a list of elements and adds them to the end of the current child list

prependChildList : List (Element msg) -> Element msg -> Element msg

Renders a list of elements and adds them to the beginning of the current child list

appendNodeList : List (VirtualNode msg) -> Element msg -> Element msg

Adds a list of Html nodes to the end of the the current child list

prependNodeList : List (VirtualNode msg) -> Element msg -> Element msg

Adds a list of Html nodes to the beginning of the the current child list

Using a conditional parameter...

when adding a class, style, or other attribute

addClassConditional : String -> Basics.Bool -> Element msg -> Element msg

Adds a class name to the current list when the condition is True

addStyleConditional : ( String, String ) -> Basics.Bool -> Element msg -> Element msg

Adds a style key/value pair to the current list when the condition is True

addAttributeConditional : VirtualAttribute msg -> Basics.Bool -> Element msg -> Element msg

Adds an attribute to the current list when the condition is True

when adding a list of classes, styles, or other attributes

addClassListConditional : List String -> Basics.Bool -> Element msg -> Element msg

Adds a list of class names to the current list when the condition is True

addStyleListConditional : List ( String, String ) -> Basics.Bool -> Element msg -> Element msg

Adds a list of style key/value pairs to the current list when the condition is True

addAttributeListConditional : List (VirtualAttribute msg) -> Basics.Bool -> Element msg -> Element msg

Adds a list of attributes to the current list when the condition is True

when adding an event listener for an action

addActionConditional : ( String, msg ) -> Basics.Bool -> Element msg -> Element msg

Adds an action to the current list of event listeners when the condition is True

when appending or prepending internal text

appendTextConditional : String -> Basics.Bool -> Element msg -> Element msg

Adds a string to the end of the current text when the condition is True

prependTextConditional : String -> Basics.Bool -> Element msg -> Element msg

Adds a string to the beginning of the current text when the condition is True

when appending or prepending child elements

appendChildConditional : Element msg -> Basics.Bool -> Element msg -> Element msg

Renders an element and adds it to the end of the current child list when the condition is true

appendChildListConditional : List (Element msg) -> Basics.Bool -> Element msg -> Element msg

Renders a list of elements and adds them to the end of the current child list when the condition is True

prependChildConditional : Element msg -> Basics.Bool -> Element msg -> Element msg

Renders an element and adds it to the beginning of the current child list when the condition is True

prependChildListConditional : List (Element msg) -> Basics.Bool -> Element msg -> Element msg

Renders a list of elements and adds them to the beginning of the current child list when the condition is True

Modify

Removing all instances of a single name or key

removeClass : String -> Element msg -> Element msg

Removes all instances of a class name from the current list

removeStyle : String -> Element msg -> Element msg

Removes all instances of a style key from the current list

removeListener : String -> Element msg -> Element msg

Removes all instances of a key (event name) from the current list of event listeners

Replacing the existing list of classes, styles, or other attributes

replaceClassList : List String -> Element msg -> Element msg

Replaces the current list of class names with a new list

replaceStyleList : List ( String, String ) -> Element msg -> Element msg

Replace the current list of style key/value pairs with a new list

replaceAttributeList : List (VirtualAttribute msg) -> Element msg -> Element msg

Replaces the current list of attributes with a new list

Replacing the existing text

replaceText : String -> Element msg -> Element msg

Replaces the current text with new text

replaceTextConditional : String -> Basics.Bool -> Element msg -> Element msg

Replaces the current text with new text when the condition is True

Replacing the existing descendant tree

replaceChildList : List (Element msg) -> Element msg -> Element msg

Renders a list of elements replaces the current child list with the rendered list

replaceChildListConditional : List (Element msg) -> Basics.Bool -> Element msg -> Element msg

Replaces the current child list with the rendered list when the condition is True

replaceNodeList : List (VirtualNode msg) -> Element msg -> Element msg

Replaces the current child list with a list of Html nodes

Advanced Usage

Setting an element's HTML/XML tag and namespace

setTag : String -> Element msg -> Element msg

Sets or resets the HTML tag

This is generally unnecessary because the tag is set by the element constructor; it may be useful to have when working with component libraries based on this package.

setNamespace : String -> Element msg -> Element msg

Sets the XML namespace as described here

This is required when using Element records to construct SVG nodes.

Using the Html.Keyed optimization

setChildListWithKeys : List ( String, Element msg ) -> Element msg -> Element msg

Sets or resets the current child list from a keyed list of element records

This is a performance optimization that will flag the rendering function to use keyedNode or keyedNodeNS. See here for details.

setNodeListWithKeys : List ( String, VirtualNode msg ) -> Element msg -> Element msg

Sets or resets the current child list from a keyed list of Html nodes

This is a performance optimization that will flag the rendering function to use keyedNode or keyedNodeNS. See here for details.

Customizing event handling...

by transforming input values

addInputHandlerWithParser : ( a -> msg, String -> a ) -> Element msg -> Element msg

Adds an input handler for form elements to the current list of event listeners

The parser works as follows: when the "input" event is triggered, a String is captured from event.target.value; then the parsing function is applied before the resulting value is passed to your Elm program's update function. For simple error handling, it is recommended to have your parsing function return a Maybe value.

addChangeHandlerWithParser : ( a -> msg, String -> a ) -> Element msg -> Element msg

Adds a value change handler for form elements to the current list of event listeners

This handler captures event.target.value on a "change" event, which can sometimes be useful when designing form interaction. Unlike the default input handler, it does not invoke the "stopPropagation" option.

The parser works as follows: when the "change" event is triggered, a String is captured from event.target.value; then the parsing function is applied before the resulting value is passed to your Elm program's update function. For simple error handling, it is recommended to have your parsing function return a Maybe value.

by using a custom decoder

addListener : ( String, Json.Decode.Decoder msg ) -> Element msg -> Element msg

Adds a listener to the current list that will invoke a custom Json decoder when the specified event is triggered.

The VirtualDom implementation for this function uses the Handler type Normal.

addListenerConditional : ( String, Json.Decode.Decoder msg ) -> Basics.Bool -> Element msg -> Element msg

Adds a listener to the current list (via addListener) when the condition is True

by using custom handler options

stop propagation

addActionStopPropagation : ( String, msg ) -> Element msg -> Element msg

Adds an action to the current list of event listeners using the Handler type MayStopPropagation with the option set to True

addListenerStopPropagation : ( String, Json.Decode.Decoder msg ) -> Element msg -> Element msg

Adds a listener to the current list that will invoke a custom Json decoder when the specified event is triggered

The VirtualDom implementation for this function uses the Handler type MayStopPropagation with the option set to True.

addActionPreventDefault : ( String, msg ) -> Element msg -> Element msg

Adds an action to the current list of event listeners using the Handler option MayPreventDefault with the option set to True

addListenerPreventDefault : ( String, Json.Decode.Decoder msg ) -> Element msg -> Element msg

Adds a listener to the current list that will invoke a custom Json decoder when the specified event is triggered

The VirtualDom implementation for this function uses the Handler type MayPreventDefault with the option set to True.

addActionStopAndPrevent : ( String, msg ) -> Element msg -> Element msg

Adds an action to the current list of event listeners using the Handler type Custom with both options set to True

addListenerStopAndPrevent : ( String, Json.Decode.Decoder msg ) -> Element msg -> Element msg

Adds a listener to the current list that will invoke a custom Json decoder when the specified event is triggered

The VirtualDom implementation for this function uses the Handler type Custom with both options set to True.

Debug

getData : Element msg -> Internal.Data msg

Returns a record containing the Element's internal data