Larceny is Haskell HTML templating based on Heist.
With Larceny, you write templates that look like this:
<bind tag=\"sport\">
Roller Derby
</bind>
<h1>
<name/> <sport/>
</h1>
<ul>
<skaters>
<li>
<h2><name/></h2>
<p><position/></p>
<p><bio length="30" text="${longBio}"/></p>
<p><a href="skater/${id}/">Read more!</a></p>
</li>
</skaters>
</ul>
And "substitutions" that look like this:
teamPageSubs :: Substitutions ()
teamPageSubs =
subs [ ("name", textFill "Gotham Girls")
, ("skaters", mapSubs
(\(i,n,p,b) ->
subs [ ("id", textFill i)
, ("name", textFill n)
, ("position", textFill p)
, ("longBio", textFill b)])
[ ("1", "Bonnie Thunders", "jammer", longBio)
, ("2", "Donna Matrix", "blocker", longBio)
, ("3", "V-Diva", "jammer", longBio) ] )
, ("bio", useAttrs (a"length" %
a"text")
bioFill))
where longBio = "Some example bio that is really long!"
bioFill maybeNumber fullBio = textFill $
case maybeNumber of
Just numChars -> T.take numChars fullBio <> "..."
Nothing -> fullBio
You end up with HTML like this:
<h1>
Gotham Girls Roller Derby
</h1>
<ul>
<li>
<h2>Bonnie Thunders</h2>
<p>jammer</p>
<p>Some example bio that is rea...</p>
<p><a href="skaters/1/">Read more!</a></p>
</li>
<li>
<h2>Donna Matrix</h2>
<p>blocker</p>
<p>Some example bio that is rea...</p>
<p><a href="skaters/2/">Read more!</a></p>
</li>
<li>
<h2>V-Diva</h2>
<p>jammer</p>
<p>Some example bio that is rea...</p>
<p><a href="skaters/3/">Read more!</a></p>
</li>
Position Dev loves Heist templates!
But then we needed unescaped HTML in our templates... so we had to use Compiled Heist. Compiled Heist is really hard to undestand.
We wrote Larceny as an alternative to compiled Heist that is easier to understand and use (if slower).
The Haskell code you write to fill in your templates is very different from Heist, but we tried to make the templates themselves as similar as possible, with a couple notable exceptions:
Larceny is different from Interpreted Heist (but similar to Compiled
Heist) in that, by default, it doesn't escape any text. The textFill
helper function which you'll most commonly use does escape t, but
if you write your own more complicated Fills, you'll need to remember
to escape the text yourself.
In Heist, <bind>s inside of nested template application can be used
in the outer templates. We found that confusing, so Larceny doesn't
allow that.
If your app lives in an environment like Alpine Linux or other
locale-less environment, you may run into this error when templates
are loaded:
your_app: some_template.tpl: hGetContents: invalid argument (invalid byte sequence)
This probably means that your template has UTF-8 characters in it, but there's no locale set.
You can remedy this by using
setLocaleEncoding
from GHC.IO.Encoding, along with an encoding like
utf8.
An example would be:
initializeApp :: IO AppCtxt
initializeApp = do
setLocaleEncoding utf8
templates <- loadTemplates "templates" defaultOverrides
...
Use stack ghci --ghci-options -isrc --ghci-options -itest larceny:test to
start ghci with the ability to reload tests when you change the library code.
CI runs stack test --pedantic on branches, which will fail if there are any
errors. Run stack test --pedantic before pushing.