Reflex HTML Basics
Last week we used Nix to create a very simple application using the Reflex FRP framework. This framework uses the paradigm of Functional Reactive Programming to create web pages. It allows us to use functional programming techniques in a problem space with a lot of input and output.
In this week's article, we're going to start explore this framework some more. We'll start getting a feel for the syntax Reflex uses for making different HTML elements. Once we're familiar with these basics, we can compare Reflex with other frontend Haskell tools.
There are several different options you can explore for making these kinds of pages. For some more ideas, download our Production Checklist. This will also suggest some different libraries you can use for your web app's backend!
A Main Function
Let's start out by looking at the code for the very basic page we made last week. It combines a few of the simplest functions we'll need to be familiar with in Reflex.
{-# LANGUAGE OverloadedStrings #-}
module Frontend.Index where
runIndex :: main ()
runIndex = mainWidget $ el "div" $ text "Welcome to Reflex!"There are three different functions here: mainWidget, el, and text. The mainWidget function is our interface between Reflex types and the IO monad. It functions a bit like a runStateT function, allowing us to turn our page into a normal program we can run. Here is its type signature:
mainWidget :: (forall t. Widget t ()) -> IO ()We provide an input in some kind of a Widget monad and it will convert it to an IO action. The t parameter is one we'll use throughout our type signatures. Reflex FRP will implicitly track a lot of different events on our page over time. This parameter signifies a particular "timeline" of events.
We won't need to get into too much detail about the parameter. There's only one case where different expressions can have different t parameters. This would be if we have multiple Reflex apps at the same time, and we won't get into this case.
There are other main functions we can use. Most likely, we would want to use mainWidgetWithCss for an full project. This takes a CSS string to apply over our page. We'll want to use the embedFile template function here. This converts a provided filepath into the actual CSS ByteString.
mainWidgetWithCss :: ByteString -> (forall t. Widget t()) -> IO ()
runIndex = do
let cssString = $(embedFile "static/styles.css")
mainWidgetWithCss cssString $ el "div" $ text "Hello, Reflex!"Static Elements
The rest of our combinators will have HTML oriented types. We'll start with our two simple combinators, text and el. These are both different kinds of "widgets" we can use.
The first of these is straightforward enough. It takes a string (Text) and produces an element in a DomBuilder monad. The result of this will be a simple text element appearing on our webpage with nothing wrapping it.
text :: (DomBuilder t m) => Text -> m ()So for example if we omitted the use of el above, the HTML for our web page body would look like:
<body>
Welcome to Reflex!
</body>The el combinator then provides us with the chance to wrap one HTML element within another. We provide a first argument with a string for the type of element we're wrapping with. Then we give the monadic action for the HTML element within. In the case of our page, we wrap our original text element with a div.
el :: (DomBuilder t m) => Text -> m () -> m ()
runIndex = mainWidget $ el "div" $ text "Welcome to Reflex!"This produces the following HTML in our body:
<body>
<div>Welcome to Reflex!</div>
</body>Now, because an element takes a monad, we can compose more elements within it as deeply as we want. Here's an example with a couple nested lists:
runIndex = mainWidget $ el "div" $ do
el "p" (text "Two Lists")
el "ol" $ do
el "li" (text "Number One")
el "li" (text "Number Two")
el "li" (text "Number Three")
el "ul" $ do
el "li" (text "First Item")
el "li" (text "Second Item")
el "li" (text "Third Item")Adding Attributes
Of course, there's more to HTML than creating elements. We'll also want to assign properties to our elements to customize their appearance.
One simple way to do this is to use the elAttr combinator instead of el. This allows us to provide a map of attributes and values. Here's an example where we provide the filename, width, and height of an image element. Note that blank is the same as text "", an empty HTML element:
imageElement = elAttr "image"
("src" =. "checkmark.jpg" <> "height" =. "300" <> "width" =. "300")
blank
-- Produced HTML
<img src="checkmark.jpg" height="300" width="300"></img>Reflex has some specific combinators we can use to build an attribute map. The =. operator combines two elements to create a singleton map. We can append different maps with the monoid operator <>.
In general, we should handle CSS with static files elsewhere. We would create CSS classes that contain many different properties. We can then apply these classes to our HTML elements. The elClass combinator is an easy way to do thing in Reflex.
styledText = elClass "p" "fancy" (text "Hello")
-- Produced HTML
<p class="fancy">Hello</p>Now we don't need to worry about styling every individual element.
Conclusion
We already have quite a few opportunities available to us to build our page. Still, it was a big hassle to use Nix and Reflex just to write some Html. Next week, we'll start exploring more lightweight options for doing this in Haskell.
For more resources on building Haskell web tools, download our Production Checklist!