This module provides support for:

1. embedding Javascript generated by JMacro into HSX.
2. turning XML generated by HSX into a DOM node in Javascript

It provides the following instances:

instance (XMLGenerator m, IntegerSupply m) => EmbedAsChild m JStat
instance (IntegerSupply m, IsName n, EmbedAsAttr m (Attr Name String)) => EmbedAsAttr m (Attr n JStat)
instance ToJExpr XML
instance ToJExpr DOMNode
instance ToJExpr XMLToInnerHTML
instance ToJExpr XMLToDOM

In order to ensure that each embedded JStat block has unique variable names, the monad must supply a source of unique names. This is done by adding an instance of IntegerSupply for the monad being used with XMLGenerator.

For example, we can use StateT to provide an IntegerSupply instance for ServerPartT:

instance IntegerSupply (ServerPartT (StateT Integer IO)) where
    nextInteger = nextInteger'

Alternatively, we can exploit the IO monad to provide an IntegerSupply instance for ServerPartT:

instance IntegerSupply (ServerPartT IO) where
    nextInteger = fmap (fromIntegral . (`mod` 1024) . hashUnique) (liftIO newUnique)

The ToJExpr XML instance allows you to splice in XML lifted out of an arbitrary monad to generate DOM nodes with JMacro antiquotation:

js = do html <- unXMLGenT <p>I'm in a Monad!</p>
        return [jmacro| document.getElementById("messages").appendChild(`(html)`); |]

The ToJExpr DOMNode instance allows you to run HSP in the Identity monad to render JMacro in pure code:

html :: DOMNode
html = <p>I'm using <em>JavaScript</em>!</p>
js = [jmacro| var language = `(html)`.getElementsByTagName("em")[0].textContent; |]

You can see here that you get an actual DOM tree in JavaScript. This is also compatible with libraries such as jQuery and YUI which are able to wrap DOM nodes in their own type, for example with jQuery:

js = [jmacro| var languages = $(`(html)`).find("em").text(); |]

Or with YUI:

js = [jmacro| var languages = Y.one(`(html)`).one("em").get("text"); |]

There are two ways to turn HTML into a a DOM node in the browser. One way is to render the HTML to a string, and pass the string to element.innerHTML. The other way is to us the use the DOM functions like createElement, setAttribute, to programatically create the DOM on the client.

In webkit-based browsers like Chrome and Safari, the DOM method appears to be slightly faster. In other browsers, the innerHTML method appears to be faster. The innerHTML method will almost always required fewer bytes to be transmitted. Additionally, if your XML/HTML contains pre-escaped content, you are required to use innerHTML anyway.

So, by default the ToJExpr XML instance uses the innerHTML method. Though, that could change in the future. If you care about using one method over the other you can use the newtype wrappers XMLToInnerHTML or XMLToDOM to select which method to use.