fn-extra-0.1.1.0: Extras for Fn, a functional web framework.

Safe HaskellNone
LanguageHaskell2010

Web.Fn.Extra.Heist

Contents

Description

This module contains helpers to make Heist fit in more closely within Fn's stance against monad transformers and for regular functions.

In particular, it instantiates the Monad for HeistState to be a ReaderT that contains our context, so that in the splices we can get the context out.

Further, we add splice builders that work similar to our url routing - splices are declared to have certain attributes of specific types, and the splice that correspond is a function that takes those as arguments (and takes the context and the node as well).

Synopsis

Types

class HeistContext ctxt where Source

In order to have render be able to get the FnHeistState out of our context, we need this helper class. The easiest way to instantiate it is with the heistLens, but if you prefer you can use getHeist and setHeist instead (one of these must be provided).

Minimal complete definition

Nothing

Methods

heistLens :: Functor f => (FnHeistState ctxt -> f (FnHeistState ctxt)) -> ctxt -> f ctxt Source

getHeist :: ctxt -> FnHeistState ctxt Source

setHeist :: ctxt -> FnHeistState ctxt -> ctxt Source

type FnHeistState ctxt = HeistState (ReaderT ctxt IO) Source

The type of our state. We need a ReaderT to be able to pass the runtime context (which includes the current request) into the splices.

type FnSplice ctxt = Splice (ReaderT ctxt IO) Source

The type of our splice. We need a ReaderT to be able to pass the runtime context (which includes the current request) into the splice.

Initializer

heistInit :: HeistContext ctxt => [Text] -> Splices (Splice (ReaderT ctxt IO)) -> IO (Either [String] (FnHeistState ctxt)) Source

Initialize heist. This takes a list of paths to template directories and a set of interpreted splices. Currently, we don't have support for compiled splices yet (so you can drop down to just plain Heist if you want them).

Rendering templates

render :: HeistContext ctxt => ctxt -> Text -> IO (Maybe Response) Source

Render a single template by name.

renderWithSplices :: HeistContext ctxt => ctxt -> Text -> Splices (FnSplice ctxt) -> IO (Maybe Response) Source

Render a template, and add additional interpreted splices before doing so.

Building splices

tag :: Text -> (Node -> k -> Maybe (Node, FnSplice ctxt)) -> (ctxt -> Node -> k) -> Splices (FnSplice ctxt) Source

This declares a new splice. Given a name, an attribute matcher, and a handler function (which takes the context, the node, and the specified attributes), it will pass the handler function the provided attributes or return nothing, if the attributes are missing / not deserializable.

Note that due to the dynamism (the handler function can have any number of arguments, and the number / type of them is based on the matcher), the types of this may be a little confusing (in particular, the k contains a lot). This continuation-based style lets us achieve this style, but the types suffer. It may be easier to see via an example:

 tag "posts" (attr "num" & attr "sort") $ \ctxt node num sort -> ...

tag' :: Text -> (ctxt -> Node -> FnSplice ctxt) -> Splices (FnSplice ctxt) Source

A tag with no attributes.

class FromAttribute a where Source

In order to make splice definitions more functional, we declare them and the attributes they need, along with deserialization (if needed). The deserialization is facilitated be this class.

Methods

fromAttribute :: Text -> Maybe a Source

Instances

attr :: FromAttribute a => Text -> Node -> (a -> t) -> Maybe (Node, t) Source

This specifies that an attribute should be present and convertable to the type indicated by it's type.

attrOpt :: FromAttribute a => Text -> Node -> (Maybe a -> t) -> Maybe (Node, t) Source

This specifies that an attribute is optional - if absent or not convertable, Nothing will be passed.

(&=) :: (Node -> k -> Maybe (Node, k')) -> (Node -> k' -> Maybe (Node, a)) -> Node -> k -> Maybe (Node, a) Source

This combines two matchers together.