Text.StringTemplates.Templates

This is main templating module. It provides basic interface for generation templates (RenderTemplate) with renderTemplate function. We also provide types for templates and few functions for loading and testing

HOW TO USE TEMPLATING SYSTEM

1) There is a folder called templates, All templates files (*.st) are there. Each files contains many templates definitions, and there must be line starting with # between each two templates. Template definition has form 'nameOfTemplate=bodyOfTemplate'.

2) Template body is just String Template and you should be able to find more info at http://www.haskell.org/haskellwiki/HStringTemplate

3) All templates are in a global scope. Watch out for conflicting names. On dev computers they are loaded on every request, so one can change them without stoping server.

4) To generate a template in haskell call renderTemplate. First param is a set of all templates. Usually you can get it from Context. Next is a name of template that You wan't to render. Last one is some for of list of params. As a result you get IO String. If template will fail You will get error info inside. But this is only for syntax errors. If You will forget a param there will be info in log, and template set param value to something empty.

FIELDS

Current policy is to use fields. You can find usage of [(String,String)] as params and also composition of setAttribute functions in a code. This are old concepts and will be droped at some point.

How to user fields: - there is one function (field) that sets one field - fields form a monad so you can use do notation for setting many fields - value of a field can be almoust everything (String, Int, Maybe, List, Map, types that are instances of Data and Typeable etc) - IO wrapped values and fields can be also a values of a field.

Example

     userView tempates user =
       renderTemplate templates "userView" $ do
         userFields

     userFields user = do
       field "name" $ username user
       field "company" $ usercompany user
       field "documents" $ map (documentFields) getUserDocumentsFromDB

     documentFields document = do
       field "id" $ documentid document
       field "title" $ documenttitle document

Why we want to use fields - They force reuse. We write documentFields, and reuse it every time we want to pass document info to template. - Fields can be extended. If I want to have extended info about user I use userFields to set basic info and then add advanced fields - No need to first bind from IO, then pass to template - They support advanced structures like lists and maybe's

Some extra info: In templates use maybe. You can use 'if' in template body to check for Nothing Always change ByteString to String. We have a problems with encoding, so please watch for this.

Please also see example.hs for a running example

Documentation

data Fields m a

Simple monad transformer that collects info about template params

Instances

MonadTrans Fields

Defined in Text.StringTemplates.Fields

Methods

lift :: Monad m => m a -> Fields m a

MonadTransControl Fields

Defined in Text.StringTemplates.Fields

Associated Types

type StT Fields a :: Type

Methods

liftWith :: Monad m => (Run Fields -> m a) -> Fields m a

restoreT :: Monad m => m (StT Fields a) -> Fields m a

MonadBase b m => MonadBase b (Fields m)

Defined in Text.StringTemplates.Fields

Methods

liftBase :: b α -> Fields m α

MonadBaseControl b m => MonadBaseControl b (Fields m)

Defined in Text.StringTemplates.Fields

Associated Types

type StM (Fields m) a :: Type

Methods

liftBaseWith :: (RunInBase (Fields m) b -> b a) -> Fields m a

restoreM :: StM (Fields m) a -> Fields m a

Monad m => Monad (Fields m)

Defined in Text.StringTemplates.Fields

Methods

(>>=) :: Fields m a -> (a -> Fields m b) -> Fields m b

(>>) :: Fields m a -> Fields m b -> Fields m b

return :: a -> Fields m a

fail :: String -> Fields m a

Functor m => Functor (Fields m)

Defined in Text.StringTemplates.Fields

Methods

fmap :: (a -> b) -> Fields m a -> Fields m b

(<$) :: a -> Fields m b -> Fields m a

Monad m => Applicative (Fields m)

Defined in Text.StringTemplates.Fields

Methods

pure :: a -> Fields m a

(<*>) :: Fields m (a -> b) -> Fields m a -> Fields m b

liftA2 :: (a -> b -> c) -> Fields m a -> Fields m b -> Fields m c

(*>) :: Fields m a -> Fields m b -> Fields m b

(<*) :: Fields m a -> Fields m b -> Fields m a

MonadThrow m => MonadThrow (Fields m)

Defined in Text.StringTemplates.Fields

Methods

throwM :: Exception e => e -> Fields m a

MonadCatch m => MonadCatch (Fields m)

Defined in Text.StringTemplates.Fields

Methods

catch :: Exception e => Fields m a -> (e -> Fields m a) -> Fields m a

MonadMask m => MonadMask (Fields m)

Defined in Text.StringTemplates.Fields

Methods

mask :: ((forall a. Fields m a -> Fields m a) -> Fields m b) -> Fields m b

uninterruptibleMask :: ((forall a. Fields m a -> Fields m a) -> Fields m b) -> Fields m b

generalBracket :: Fields m a -> (a -> ExitCase b -> Fields m c) -> (a -> Fields m b) -> Fields m (b, c)

type StT Fields m

Defined in Text.StringTemplates.Fields

type StT Fields m

type StM (Fields m) a

Defined in Text.StringTemplates.Fields

type StM (Fields m) a = ComposeSt Fields m a

runFields :: Monad m => Fields m () -> m [(String, SElem String)]

get all collected template params

class (Applicative m, Monad m) => TemplatesMonad m where

Simple reader monad class that provides access to templates

Methods

getTemplates :: m Templates

Get templates (for text templates default language name is used).

getTextTemplatesByLanguage :: String -> m Templates

Get templates (for text templates specified language name is used).

Instances

(Applicative (t m), Monad (t m), MonadTrans t, TemplatesMonad m) => TemplatesMonad (t m)

Generic, overlappable instance.

Defined in Text.StringTemplates.Templates.Class

Methods

getTemplates :: t m Templates

getTextTemplatesByLanguage :: String -> t m Templates

(Applicative m, Monad m) => TemplatesMonad (TemplatesT m)

Defined in Text.StringTemplates.Templates

Methods

getTemplates :: TemplatesT m Templates

getTextTemplatesByLanguage :: String -> TemplatesT m Templates

renderTemplate

Arguments

:: TemplatesMonad m

=> String

template name

-> Fields m ()

template params

-> m String

renders a template by name

renderTemplate_

Arguments

:: TemplatesMonad m

=> String

template name

-> m String

renders a template by name without any params

renderTemplateI

Arguments

:: TemplatesMonad m

=> String

template name

-> Fields Identity ()

template params

-> m String

renders a template by name (params function cannot use side effects)

newtype TemplatesT m a

Simple implementation of TemplatesMonad

Constructors

TemplatesT

Fields

• unTT :: InnerTemplatesT m a

Instances

MonadTrans TemplatesT

Defined in Text.StringTemplates.Templates

Methods

lift :: Monad m => m a -> TemplatesT m a

MonadTransControl TemplatesT

Defined in Text.StringTemplates.Templates

Associated Types

type StT TemplatesT a :: Type

Methods

liftWith :: Monad m => (Run TemplatesT -> m a) -> TemplatesT m a

restoreT :: Monad m => m (StT TemplatesT a) -> TemplatesT m a

MonadBase b m => MonadBase b (TemplatesT m)

Defined in Text.StringTemplates.Templates

Methods

liftBase :: b α -> TemplatesT m α

MonadBaseControl b m => MonadBaseControl b (TemplatesT m)

Defined in Text.StringTemplates.Templates

Associated Types

type StM (TemplatesT m) a :: Type

Methods

liftBaseWith :: (RunInBase (TemplatesT m) b -> b a) -> TemplatesT m a

restoreM :: StM (TemplatesT m) a -> TemplatesT m a

MonadError e m => MonadError e (TemplatesT m)

Defined in Text.StringTemplates.Templates

Methods

throwError :: e -> TemplatesT m a

catchError :: TemplatesT m a -> (e -> TemplatesT m a) -> TemplatesT m a

Monad m => Monad (TemplatesT m)

Defined in Text.StringTemplates.Templates

Methods

(>>=) :: TemplatesT m a -> (a -> TemplatesT m b) -> TemplatesT m b

(>>) :: TemplatesT m a -> TemplatesT m b -> TemplatesT m b

return :: a -> TemplatesT m a

fail :: String -> TemplatesT m a

Functor m => Functor (TemplatesT m)

Defined in Text.StringTemplates.Templates

Methods

fmap :: (a -> b) -> TemplatesT m a -> TemplatesT m b

(<$) :: a -> TemplatesT m b -> TemplatesT m a

Applicative m => Applicative (TemplatesT m)

Defined in Text.StringTemplates.Templates

Methods

pure :: a -> TemplatesT m a

(<*>) :: TemplatesT m (a -> b) -> TemplatesT m a -> TemplatesT m b

liftA2 :: (a -> b -> c) -> TemplatesT m a -> TemplatesT m b -> TemplatesT m c

(*>) :: TemplatesT m a -> TemplatesT m b -> TemplatesT m b

(<*) :: TemplatesT m a -> TemplatesT m b -> TemplatesT m a

MonadIO m => MonadIO (TemplatesT m)

Defined in Text.StringTemplates.Templates

Methods

liftIO :: IO a -> TemplatesT m a

MonadThrow m => MonadThrow (TemplatesT m)

Defined in Text.StringTemplates.Templates

Methods

throwM :: Exception e => e -> TemplatesT m a

MonadCatch m => MonadCatch (TemplatesT m)

Defined in Text.StringTemplates.Templates

Methods

catch :: Exception e => TemplatesT m a -> (e -> TemplatesT m a) -> TemplatesT m a

MonadMask m => MonadMask (TemplatesT m)

Defined in Text.StringTemplates.Templates

Methods

mask :: ((forall a. TemplatesT m a -> TemplatesT m a) -> TemplatesT m b) -> TemplatesT m b

uninterruptibleMask :: ((forall a. TemplatesT m a -> TemplatesT m a) -> TemplatesT m b) -> TemplatesT m b

generalBracket :: TemplatesT m a -> (a -> ExitCase b -> TemplatesT m c) -> (a -> TemplatesT m b) -> TemplatesT m (b, c)

(Applicative m, Monad m) => TemplatesMonad (TemplatesT m)

Defined in Text.StringTemplates.Templates

Methods

getTemplates :: TemplatesT m Templates

getTextTemplatesByLanguage :: String -> TemplatesT m Templates

type StT TemplatesT m

Defined in Text.StringTemplates.Templates

type StT TemplatesT m

type StM (TemplatesT m) a

Defined in Text.StringTemplates.Templates

type StM (TemplatesT m) a = ComposeSt TemplatesT m a

runTemplatesT

Arguments

:: (Functor m, Monad m)

=> (String, GlobalTemplates)

(default language name, global templates)

-> TemplatesT m a

-> m a

renderHelper :: Monad m => Templates -> String -> Fields m () -> m String