hakyll-4.13.0.1: A static website compiler library

Safe Haskell | None
Language | Haskell2010

Hakyll.Web.Template

Description

This module provides means for reading and applying `Template`s.

Templates are tools to convert items into a string. They are perfectly suited for laying out your site.

Let's look at an example template:

    <html>
        <head>
            <title>My crazy homepage - $title$</title>
        </head>
        <body>
            <div id="header">
                <h1>My crazy homepage - $title$</h1>
            </div>
            <div id="content">
                $body$
            </div>
            <div id="footer">
                By reading this you agree that I now own your soul
            </div>
        </body>
    </html>

As you can see, the format is very simple -- `$key$` is used to render the `$key$` field from the page, everything else is literally copied. If you want to literally insert `"$key$"` into your page (for example, when you're writing a Hakyll tutorial) you can use

    <p>
        A literal $$key$$.
    </p>

Because of it's simplicity, these templates can be used for more than HTML: you could make, for example, CSS or JS templates as well.

Apart from interpolating `$key$`s from the `Context` you can also use the following macros:

-     $if(key)$

    $if(key)$
     <b> Defined </b>
    $else$
     <b> Non-defined </b>
    $endif$

This example will print `Defined` if `key` is defined in the context and `Non-defined` otherwise. The `$else$` clause is optional.

-     $for(key)$

The `for` macro is used for enumerating `Context` elements that are lists, i.e. constructed using the `listField` function. Assume that in a context we have an element `listField "key" c itms`. Then the snippet

    $for(key)$
      $x$
    $sep$,
    $endfor$

would, for each item `i` in `itms`, lookup `$x$` in the context `c` with item `i`, interpolate it, and join the resulting list with `,`.

Another concrete example one may consider is the following. Given the context

    listField "things" (field "thing" (return . itemBody))
       (sequence [makeItem "fruits", makeItem "vegetables"])

and a template

     I like
     $for(things)$
       fresh $thing$$sep$, and
     $endfor$

the resulting page would look like

    <p>
     I like

      fresh fruits, and

      fresh vegetables
    </p>

The `$sep$` part can be omitted. Usually, you can get by using the `applyListTemplate` and `applyJoinListTemplate` functions.

-     $partial(path)$

Loads a template located in a separate file and interpolates it under the current context.

Assuming that the file `test.html` contains

    <b>$key$</b>

The result of rendering

    <p>
      $partial("test.html")$
    </p>

is the same as the result of rendering

    <p>
      <b>$key$</b>
    </p>

That is, calling `$partial$` is equivalent to just copying and pasting template code.

In the examples above you can see that the outputs contain a lot of leftover whitespace that you may wish to remove. Using ``$-`` or ``-$`` instead of ``$`` in a macro strips all whitespace to the left or right of that clause respectively. Given the context

    listField "counts" (field "count" (return . itemBody))
       (sequence [makeItem "3", makeItem "2", makeItem "1"])

and a template

    <p>
        $for(counts)-$
          $count$
          $-sep$...
        $-endfor$
    </p>

the resulting page would look like

    <p>
        3...2...1
    </p>

Synopsis

- data Template
- templateBodyCompiler :: Compiler (Item Template)
- templateCompiler :: Compiler (Item Template)
- applyTemplate :: Template -> Context a -> Item a -> Compiler (Item String)
- loadAndApplyTemplate :: Identifier -> Context a -> Item a -> Compiler (Item String)
- applyAsTemplate :: Context String -> Item String -> Compiler (Item String)
- readTemplate :: String -> Template
- compileTemplateItem :: Item String -> Compiler Template
- unsafeReadTemplateFile :: FilePath -> Compiler Template
- embedTemplate :: FilePath -> Q Exp

# Documentation

data Template Source #

Datatype used for template substitutions.

Instances

Eq Template Source # |
Instance details Defined in Hakyll.Web.Template.Internal Methods (==) :: Template -> Template -> Bool Source # (/=) :: Template -> Template -> Bool Source #
Show Template Source # |
Instance details Defined in Hakyll.Web.Template.Internal Methods showsPrec :: Int -> Template -> ShowS Source # show :: Template -> String Source # showList :: [Template] -> ShowS Source #
IsString Template Source # |
Instance details Defined in Hakyll.Web.Template.Internal Methods fromString :: String -> Template Source #
Generic Template Source # |
Instance details Defined in Hakyll.Web.Template.Internal Associated Types type Rep Template :: Type -> Type Source # Methods from :: Template -> Rep Template x Source # to :: Rep Template x -> Template Source #
Binary Template Source # |
Instance details Defined in Hakyll.Web.Template.Internal Methods put :: Template -> Put Source # get :: Get Template Source # putList :: [Template] -> Put Source #
Writable Template Source # |
Instance details Defined in Hakyll.Web.Template.Internal Methods write :: FilePath -> Item Template -> IO () Source #
type Rep Template Source # |

Instance details

Defined in Hakyll.Web.Template.Internal

type Rep Template = D1 (MetaData "Template" "Hakyll.Web.Template.Internal" "hakyll-4.13.0.1-DVicqx3BsrW85jFIzMUpem" False) (C1 (MetaCons "Template" PrefixI True) (S1 (MetaSel (Just "tplElements") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 [TemplateElement]) :*: S1 (MetaSel (Just "tplOrigin") NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 FilePath)))

templateBodyCompiler :: Compiler (Item Template) Source #

Read a template, without metadata header

templateCompiler :: Compiler (Item Template) Source #

Read complete file contents as a template

applyTemplate Source #

Arguments

:: Template | Template
-> Context a | Context
-> Item a | Page
-> Compiler (Item String) | Resulting item

Interpolate template expressions from context values in a page

loadAndApplyTemplate Source #

Arguments

:: Identifier | Template identifier
-> Context a | Context
-> Item a | Page
-> Compiler (Item String) | Resulting item

The following pattern is so common:

    tpl <- loadBody "templates/foo.html"
    someCompiler
        >>= applyTemplate tpl context

That we have a single function which does this:

    someCompiler
        >>= loadAndApplyTemplate "templates/foo.html" context

applyAsTemplate Source #

Arguments

:: Context String | Context
-> Item String | Item and template
-> Compiler (Item String) | Resulting item

It is also possible that you want to substitute `$key$`s within the body of an item. This function does that by interpreting the item body as a template, and then applying it to itself.

readTemplate :: String -> Template Source #

Deprecated: Use templateCompiler instead

Parse a string into a template. You should prefer `compileTemplateItem` over this.

compileTemplateItem :: Item String -> Compiler Template Source #

Parse an item body into a template. Provides useful error messages in the `Compiler` monad.

unsafeReadTemplateFile :: FilePath -> Compiler Template Source #

Deprecated: Use templateCompiler

embedTemplate :: FilePath -> Q Exp Source #

Embed template allows you embed a template within the Haskell binary. Example:

    myTemplate :: Template
    myTemplate = $(embedTemplate "test.html")