Html.AttributeBuilder

Elm's Html module constructs HTML nodes by asking you to provide, among other things, a list of HTML attributes. So, you might typically see something like:

div [ class "ui button primary" , onClick DoLogin ] [ text "Login" ]

Sometimes it is convenient to build up the list of attributes through a series of computations. One can, of course, simply use functions that return lists of attributes and combine them together ... perhaps something like this:

div
    ( List.concat
        [ computation1 model
        , computation2 user
        , [ class "another-class"
          , style [("position", "absolute")]
          ]
        ]
    )
    [ text "Login" ]

And, in Elm 0.18, Elm does some things you might expect with this:

If you provide multiple "class" attributes, they get combined appropriately. (This wasn't the case in Elm 0.17, which was actually the original motivation for this package).
If you provide multiple "style" attributes, they are all used.

However, sometimes you might want to build attributes up using types that give you some more fine-tuned control. That is the purpose of this package. It allows you to something like this:

import Html.AttributeBuilder as AB


AB.attributeBuilder
    |> AB.union (computation1 model)
    |> AB.union (computation2 user)
    |> AB.addClass "another-class"
    |> AB.removeClass "unwanted-class"
    |> AB.addStyle "position" "absolute"
    |> AB.toAttributes

What you get at the end of such a pipeline is a List Html.Attribute, constructed in a way that you might enjoy.

type AttributeBuilder msg

An opaque type which you can use to gradually build up attributes for an Html element.

attributeBuilder : AttributeBuilder msg

An empty AttributeBuilder, with no attributes yet. You will often want to start with this.

attributeBuilder
    |> addClass "a-class"
    |> addStyle "background-color" "red"
    |> toAttributes

union :

AttributeBuilder msg

-> AttributeBuilder msg

Combine two AttributeBuilder values. If the names of styles collide, the values in the first AttributeBuilder will be preferred.

toAttributes : AttributeBuilder msg -> List (Attribute msg)

Convert an AttributeBuilder to a list of attributes. This will typically be your final step, when you have collected all the attributes you need and want to supply the attributes to the Html module.

addAttribute : Attribute msg -> AttributeBuilder msg -> AttributeBuilder msg

Add an attribute to an attribute builder.

This is particularly meant for event handlers (e.g. on "click" ...), for which we don't provide any special support.

Where possible, you should prefer the more specific functions for classes and styles, since they combine classes and styles in a more predictable manner.

attributeBuilder
    |> addClass "login"
    |> addAttribute (onClick Login)
    |> toAttributes

addAttributes :

List (Attribute msg)

-> AttributeBuilder msg

Add a list of attributes to an attribute builder.

This is particularly meant for event handlers (e.g. on "click" ...), for which we don't provide any special support.

Where possible, you should prefer the more specific functions for classes and styles, since they combine classes and styles in a more predictable manner.

addClass : String -> AttributeBuilder msg -> AttributeBuilder msg

Add a class to the AttributeBuilder.

removeClass : String -> AttributeBuilder msg -> AttributeBuilder msg

Remove a class from the AttributeBuilder.

applyClassList :

List ( String, Bool )

-> AttributeBuilder msg

Like Html.Attributes.classList, but also removes the classes in the List which are associated with a False, if already present.

addClassList :

List ( String, Bool )

-> AttributeBuilder msg

Like applyClassList, but only adds classes, never removes.

addStyle : String -> String -> AttributeBuilder msg -> AttributeBuilder msg

Add a value for a style, replacing any previous value for the style with that name. The first parameter is the name of the style, and the second is its value.

attributeBuilder
    |> addClass "some-class"
    |> addStyle "background-color" "red"
    |> toAttributes

addStyles :

List ( String, String )

-> AttributeBuilder msg

Add several styles at once, analogous to Html.Attribute.style.

removeStyle : String -> AttributeBuilder msg -> AttributeBuilder msg

Remove a style from an AttributeBuilder.

Modules