Bonsai.VirtualDom
- Package
- purescript-bonsai
- Repository
- grmble/purescript-bonsai
Purescript interface to Elm Virtual DOM
#node Source
node :: forall msg. String -> Array (Property msg) -> Array (VNode msg) -> VNode msg
Create a DOM node with a tag name, a list of HTML properties that can
include styles and event listeners, a list of CSS properties like color
, and
a list of child nodes.
import Json.Encode as Json
hello : Node msg hello = node "div" [] [ text "Hello!" ]
greeting : Node msg greeting = node "div" [ property "id" (Json.string "greeting") ] [ text "Hello!" ]
#Property Source
newtype Property msg
When using HTML and JS, there are two ways to specify parts of a DOM node.
Attributes — You can set things in HTML itself. So the
class
in<div class="greeting"></div>
is called an attribute.Properties — You can also set things in JS. So the
className
indiv.className = 'greeting'
is called a property.
So the class
attribute corresponds to the className
property. At first
glance, perhaps this distinction is defensible, but it gets much crazier.
There is not always a one-to-one mapping between attributes and properties!
Yes, that is a true fact. Sometimes an attribute exists, but there is no
corresponding property. Sometimes changing an attribute does not change the
underlying property. For example, as of this writing, the webkit-playsinline
attribute can be used in HTML, but there is no corresponding property!
Instances
#property Source
property :: forall msg a. String -> a -> Property msg
Create arbitrary properties.
import JavaScript.Encode as Json
greeting : Html greeting = node "div" [ property "className" (Json.string "greeting") ] [ text "Hello!" ]
Notice that you must give the property name, so we use className
as it
would be in JavaScript, not class
as it would appear in HTML.
#attribute Source
attribute :: forall msg. String -> String -> Property msg
Create arbitrary HTML attributes. Maps onto JavaScript’s setAttribute
function under the hood.
greeting : Html
greeting =
node "div" [ attribute "class" "greeting" ] [
text "Hello!"
]
Notice that you must give the attribute name, so we use class
as it would
be in HTML, not className
as it would appear in JS.
#attributeNS Source
attributeNS :: forall msg. String -> String -> String -> Property msg
Would you believe that there is another way to do this?! This corresponds
to JavaScript's setAttributeNS
function under the hood. It is doing pretty
much the same thing as attribute
but you are able to have "namespaced"
attributes. This is used in some SVG stuff at least.
#EventDecoder Source
type EventDecoder msg = Foreign -> F (Cmd msg)
A EventDecoder turns DOM events into messages.
#on Source
on :: forall msg. String -> (EventDecoder msg) -> Property msg
Create a custom event listener.
import Json.Decode as Json
onClick : msg -> Property msg
onClick msg =
on "click" (Json.succeed msg)
You first specify the name of the event in the same format as with JavaScript’s
addEventListener
. Next you give a JSON decoder, which lets you pull
information out of the event object. If the decoder succeeds, it will produce
a message and route it to your update
function.
#onWithOptions Source
onWithOptions :: forall msg. String -> Options -> EventDecoder msg -> Property msg
Same as on
but you can set a few options.
#Options Source
type Options = { preventDefault :: Boolean, stopPropagation :: Boolean }
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.
#lazy Source
lazy :: forall msg a. (a -> VNode msg) -> a -> VNode msg
A performance optimization that delays the building of virtual DOM nodes.
Calling (view model)
will definitely build some virtual DOM, perhaps a lot of
it. Calling (lazy view model)
delays the call until later. During diffing, we
can check to see if model
is referentially equal to the previous value used,
and if so, we just stop. No need to build up the tree structure and diff it,
we know if the input to view
is the same, the output must be the same!
#keyedNode Source
keyedNode :: forall msg. String -> Array (Property msg) -> Array (Tuple String (VNode msg)) -> VNode msg
Works just like node
, but you add a unique identifier to each child
node. You want this when you have a list of nodes that is changing: adding
nodes, removing nodes, etc. In these cases, the unique identifiers help make
the DOM modifications more efficient.