lucid

Clear to write, read and edit DSL for HTML

https://github.com/chrisdone/lucid

LTS Haskell 22.41:2.11.20230408@rev:2
Stackage Nightly 2024-11-12:2.11.20230408@rev:2
Latest on Hackage:2.11.20230408@rev:2

See all snapshots lucid appears in

BSD-3-Clause licensed by Chris Done
Maintained by [email protected]
This version can be pinned in stack with:lucid-2.11.20230408@sha256:d2757a8c190a942d4931350692643a5f94ecfeded467969a03d105d9c36c0e8e,3180

Module documentation for 2.11.20230408

lucid Hackage Build Status

Clear to write, read and edit DSL for writing HTML

Table of Contents

Introduction

HTML terms in Lucid are written with a postfix ‘_’ to indicate data rather than code. Some examples:

p_, class_, table_, style_

See Lucid.Html5 for a complete list of Html5 combinators.

Plain text is written using the OverloadedStrings and ExtendedDefaultRules extensions, and is automatically escaped:

λ> "123 < 456" :: Html ()

123 &lt; 456

Elements nest by function application:

λ> table_ (tr_ (td_ (p_ "Hello, World!"))) :: Html ()

<table><tr><td><p>Hello, World!</p></td></tr></table>

Elements are juxtaposed via monoidal append:

λ> p_ "hello" <> p_ "sup" :: Html ()

<p>hello</p><p>sup</p>

Or monadic sequencing:

λ> div_ (do p_ "hello"; p_ "sup") :: Html ()

<div><p>hello</p><p>sup</p></div>

Attributes are set by providing an argument list:

λ> p_ [class_ "brand"] "Lucid Inc" :: Html ()

<p class="brand">Lucid Inc</p>

Here is a fuller example of Lucid:

table_ [rows_ "2"]
       (tr_ (do td_ [class_ "top",colspan_ "2",style_ "color:red"]
                    (p_ "Hello, attributes!")
                td_ "yay!"))

<table rows="2">
  <tr>
    <td style="color:red" colspan="2" class="top">
      <p>Hello, attributes!</p>
    </td>
    <td>yay!</td>
  </tr>
</table>

Rendering

For proper rendering you can easily run some HTML immediately with:

λ> renderText (p_ "Hello!")

"<p>Hello!</p>"

Or to bytes:

λ> renderBS (p_ [style_ "color:red"] "Hello!")

"<p style=\"color:red\">Hello!</p>"

For ease of use in GHCi, there is a Show instance, as demonstrated above.

If the above rendering functions aren’t suited for your purpose, you can run the monad directly via execHtml and use the more low-level blaze Builder, which has a plethora of output modes in Blaze.ByteString.Builder.

See the documentation for the Lucid module for information about using it as a monad transformer.

Good to know

  • Attributes are escaped, so you cannot write arbitrary JavaScript in attributes. Instead, do something like onclick_ "foo()".
  • Attributes are rendered in the order that they are written in your Haskell code.

Transforming

You can use lift to call parent monads.

λ> runReader (renderTextT (html_ (body_ (do name <- lift ask
                                            p_ [class_ "name"] (toHtml name)))))
             ("Chris" :: String)

"<html><body><p class=\"name\">Chris</p></body></html>"

Changes

Upcoming

2.11.20230408

  • Don’t expect Control.Monad to be re-exported from mtl anymore

2.11.1

  • Use explicit imports for mtl, avoids the mtl-2.3 issue
  • Added minlength attribute.
  • Added loading attribute.

2.11.0

  • Change internal attributes to Seq Attribute. This preserves ordering. Attributes are merged in a left-biased way, preserving the key order as first encountered.

2.10.0

  • Change internal attributes representation from HashMap to Map. This introduces stable ordering, at a negligible performance cost for realistic element sizes. This may affect some test suites.
  • doctype no longer accepts attributes. You can use with with doctypeHtml now, if needed.

2.9.12.1

  • Allow different orderings of attributes in test-suite

2.9.12

  • Add MonadFix instance

2.9.11

  • Add GHC-8.6 support
  • row-fluid and container-fluid instead of camelCase

2.9.10

  • Drop GHC-7.8 and older (pre-AMP) support
  • Generalise type-signatures to require only Applicative or Functor, when that’s enough

2.9.9

  • Add commuteHtmlT to commute HtmlT m a into m (HtmlT n a).
  • Add MonadError e m => MonadError e (HtmlT m) and MonadWriter w m => MonadWriter w (HtmlT m) instances

2.9.8.1

  • Improve performance by adding INLINE pragmas to Monad etc. combinators.

2.9.8

  • Add integrity_, crossorigin_ attributes
  • Add classes_ smart attribute constructor
  • Add ToHtml (HtmlT m a) instance

2.9.7

  • Add Semigroup (HtmlT m a) instance
  • Add MonadState and MonadReader instances

2.9.6

  • Fix compilation of benchmarks
  • Add @athanclark’s version of relaxHtmlT
  • Add a utility to generalize the underlying monad from Identity: relaxHtmlT

2.9.5

  • Add ToHtml instance for ByteString (both)
  • Add MFunctor HtmlT instance, i.e. hoist from @mmorph@.

2.9.1

  • Small performance tweaks.
  • Make svg_ an element.

2.6

  • Restrict monoid instance’s a to ~ () (means you can use mempty without inference errors)

2.2

  • Export renderToFile from top-level Lucid module.

2.1

  • Add some extra HTML tags.

2.0

  • Use variadic HTML terms.
  • Add lazy Text instance for ToHtml.

1.0

  • Initial version.