Web-page
========

This package combines blaze-html, clay and jmacro into a
framework-agnostic library to generate web pages dynamically from
individual components.  It is inspired by Yesod's widgets, but is more
general, more powerful and can be used with other web frameworks.


Features
--------

The `Widget` type is very expressive.  The following features are built
in:

  * works with your web framework of choice,
  * fully embedded stylesheet and script languages (jmacro and clay),
  * page-specific or external stylesheets and script,
  * type-safe routing,
  * flexible polymorphic body type,
  * monoidal piece-by-piece construction of pages,
  * hierarchial titles,
  * additional head markup,
  * optional lens interface,
  * rendering to multiple documents (e.g. separate stylesheet and
    script).

Other features are add-ons:

  * non-HTML bodies (e.g. Pandoc integration),
  * multipart bodies aka *sections*,
  * page-unique identifier generation.


Usage
-----

This is a brief overview of the process to construct and render a web
page using this library.  First of all you will need a few extensions:

    {-# LANGUAGE FlexibleContexts #-}
    {-# LANGUAGE OverloadedStrings #-}
    {-# LANGUAGE QuasiQuotes #-}

The `OverloadedStrings` extension is optional, but makes writing
blaze-html markup and clay stylesheets a lot more convenient.  The
`QuasiQuotes` extension is only required for jmacro, if you need scripts
in your widgets.  With that aside the first step is to understand the
`Widget` type:

    Widget url h

The type argument `url` is your URL type.  If you don't use type-safe
routing, then simply use `url = Text`.  This is only significant for
external stylesheets and scripts.  If you don't use any of them, just
leave it polymorphic.

The second type argument `h` is the page body type.  For now just use
`Html` (from blaze-html), which means that the body of your page will be
simple unstructured HTML markup.


### Construction

`Widget` is a family of monoids.  While you could use the `Monoid`
interface directly it's usually much more convenient to use a writer
monad to construct your widgets.  In most cases the correct type will be
inferred, but we will specify it regardless:

    myWidget :: (MonadWriter (Widget url Html) m) => m ()

If you are like me, you prefer to write type signatures for your
top-level definitions.  A constraint alias is provided for your
convenience.  The following type signature is equivalent to the above:

    myWidget :: (MonadWidget url Html m) => m ()

If writer is the only effect you need, there is an even simpler alias
that you can use, which is equivalent to the above as well:

    myWidget :: WidgetWriter url Html ()

Now we can construct the widget piece by piece:

    myWidget = do
        setTitle "Hello"
        addBody (H.h1 "Hello")
        addBody (H.p "Hello world!")
        addStyle $ html ? do
            background white
            color black

You can build the widget by reducing the writer:

    w :: Widget url Html
    w = execWriter myWidget

This widget can now be rendered to a page.


### Rendering

To render the widget you can use the `renderWidget` function:

    renderWidget :: ([Text] -> Tl.Text) -> Widget Text Html -> Page

The `Text` type is the strict version, while the `Tl.Text` type is the
lazy version.

The first argument to this function is the title renderer.  Widgets
define an optional title, which is not just a text string, but a list of
text strings.  That's because this library supports hierarchial titles
by using the `withTitle` function.  We will not cover this here.  Just
use `titleMinor`:

    page :: Page
    page = renderWidget (titleMinor " - ") w

Pages are an intermediate step between rendering and delivery.  They are
necessary, because this library allows you to render to multiple
documents, for example to a markup document, a stylesheet and a script.
You can then use a clever hash-based routing mechanism to tell clients
to cache stylesheets and scripts forever and reduce the required
bandwidth to a minimum.


### Realisation

To process of finalising a page to an actual set of documents that you
can deliver is referred to as *realisation*.  We will simply render to a
single document with an inline stylesheet and no script (because our
widget above doesn't define one).  The `realiseInline` function does
exactly that:

    realiseInline :: Page -> Builder

All we need to do is to apply it to our page:

    document :: Builder
    document = realiseInline page

The `Builder` type is the usual one from blaze-builder.  Most web
frameworks use it for efficient bytestring concatenation and provide a
simple interface to deliver those strings to clients.  For example WAI
provides the `responseBuilder` function.  If you want to save the result
to a file, just use `toLazyByteString` or `toByteStringIO`.