heist-0.8.0: An (x)html templating system

Safe HaskellNone

Text.Templating.Heist.Internal

Synopsis

Documentation

addDoctype :: Monad m => [DocType] -> HeistT m ()Source

Mappends a doctype to the state.

addOnLoadHook :: Monad m => (Template -> IO Template) -> HeistState m -> HeistState mSource

Adds an on-load hook to a HeistState.

addPreRunHook :: Monad m => (Template -> m Template) -> HeistState m -> HeistState mSource

Adds a pre-run hook to a HeistState.

addPostRunHook :: Monad m => (Template -> m Template) -> HeistState m -> HeistState mSource

Adds a post-run hook to a HeistState.

bindSpliceSource

Arguments

:: Monad m 
=> Text

tag name

-> Splice m

splice action

-> HeistState m

source state

-> HeistState m 

Binds a new splice declaration to a tag name within a HeistState.

bindSplicesSource

Arguments

:: Monad m 
=> [(Text, Splice m)]

splices to bind

-> HeistState m

start state

-> HeistState m 

Binds a set of new splice declarations within a HeistState.

setCurTemplateFile :: Monad m => Maybe FilePath -> HeistState m -> HeistState mSource

Sets the current template file.

textSplice :: Monad m => Text -> Splice mSource

Converts Text to a splice returning a single TextNode.

runChildren :: Monad m => Splice mSource

Runs the parameter node's children and returns the resulting node list. By itself this function is a simple passthrough splice that makes the spliced node disappear. In combination with locally bound splices, this function makes it easier to pass the desired view into your splices.

runChildrenWithSource

Arguments

:: Monad m 
=> [(Text, Splice m)]

List of splices to bind before running the param nodes.

-> Splice m

Returns the passed in view.

Binds a list of splices before using the children of the spliced node as a view.

runChildrenWithTransSource

Arguments

:: Monad m 
=> (b -> Splice m)

Splice generating function

-> [(Text, b)]

List of tuples to be bound

-> Splice m 

Wrapper around runChildrenWith that applies a transformation function to the second item in each of the tuples before calling runChildrenWith.

runChildrenWithTemplates :: Monad m => [(Text, Template)] -> Splice mSource

Like runChildrenWith but using constant templates rather than dynamic splices.

runChildrenWithText :: Monad m => [(Text, Text)] -> Splice mSource

Like runChildrenWith but using literal text rather than dynamic splices.

mapSplicesSource

Arguments

:: Monad m 
=> (a -> Splice m)

Splice generating function

-> [a]

List of items to generate splices for

-> Splice m

The result of all splices concatenated together.

Maps a splice generating function over a list and concatenates the results.

lookupSplice :: Monad m => Text -> HeistState m -> Maybe (Splice m)Source

Convenience function for looking up a splice.

splitPathWith :: Char -> ByteString -> TPathSource

Converts a path into an array of the elements in reverse order. If the path is absolute, we need to remove the leading slash so the split doesn't leave "" as the last element of the TPath.

FIXME ".." currently doesn't work in paths, the solution is non-trivial

splitLocalPath :: ByteString -> TPathSource

Converts a path into an array of the elements in reverse order using the path separator of the local operating system. See splitPathWith for more details.

splitTemplatePath :: ByteString -> TPathSource

Converts a path into an array of the elements in reverse order using a forward slash (/) as the path separator. See splitPathWith for more details.

singleLookup :: TemplateMap -> TPath -> ByteString -> Maybe (DocumentFile, TPath)Source

Does a single template lookup without cascading up.

traversePath :: TemplateMap -> TPath -> ByteString -> Maybe (DocumentFile, TPath)Source

Searches for a template by looking in the full path then backing up into each of the parent directories until the template is found.

hasTemplate :: Monad m => ByteString -> HeistState m -> BoolSource

Returns True if the given template can be found in the heist state.

lookupTemplate :: Monad m => ByteString -> HeistState m -> Maybe (DocumentFile, TPath)Source

Convenience function for looking up a template.

setTemplates :: Monad m => TemplateMap -> HeistState m -> HeistState mSource

Sets the templateMap in a HeistState.

insertTemplate :: Monad m => TPath -> DocumentFile -> HeistState m -> HeistState mSource

Adds a template to the heist state.

addTemplateSource

Arguments

:: Monad m 
=> ByteString

Path that the template will be referenced by

-> Template

The template's DOM nodes

-> Maybe FilePath

An optional path to the actual file on disk where the template is stored

-> HeistState m 
-> HeistState m 

Adds an HTML format template to the heist state.

addXMLTemplateSource

Arguments

:: Monad m 
=> ByteString

Path that the template will be referenced by

-> Template

The template's DOM nodes

-> Maybe FilePath

An optional path to the actual file on disk where the template is stored

-> HeistState m 
-> HeistState m 

Adds an XML format template to the heist state.

stopRecursion :: Monad m => HeistT m ()Source

Stops the recursive processing of splices. Consider the following example:

 <foo>
   <bar>
     ...
   </bar>
 </foo>

Assume that "foo" is bound to a splice procedure. Running the foo splice will result in a list of nodes L. Normally foo will recursively scan L for splices and run them. If foo calls stopRecursion, L will be included in the output verbatim without running any splices.

setContext :: Monad m => TPath -> HeistT m ()Source

Sets the current context

getContext :: Monad m => HeistT m TPathSource

Gets the current context

getTemplateFilePath :: Monad m => HeistT m (Maybe FilePath)Source

Gets the full path to the file holding the template currently being processed. Returns Nothing if the template is not associated with a file on disk or if there is no template being processed.

runNode :: Monad m => Node -> Splice mSource

Performs splice processing on a single node.

attSubst :: Monad m => (t, Text) -> HeistT m (t, Text)Source

Helper function for substituting a parsed attribute into an attribute tuple.

parseAtt :: Monad m => Text -> HeistT m TextSource

Parses an attribute for any identifier expressions and performs appropriate substitution.

data AttAST Source

AST to hold attribute parsing structure. This is necessary because attoparsec doesn't support parsers running in another monad.

Constructors

Literal Text 
Ident Text 

Instances

attParser :: Parser [AttAST]Source

Parser for attribute variable substitution.

getAttributeSplice :: Monad m => Text -> HeistT m TextSource

Gets the attribute value. If the splice's result list contains non-text nodes, this will translate them into text nodes with nodeText and concatenate them together.

Originally, this only took the first node from the splices's result list, and only if it was a text node. This caused problems when the splice's result contained HTML entities, as they would split a text node. This was then fixed to take the first consecutive bunch of text nodes, and return their concatenation. This was seen as more useful than throwing an error, and more intuitive than trying to render all the nodes as text.

However, it was decided in the end to render all the nodes as text, and then concatenate them. If a splice returned "some <b>text</b> foobar", the user would almost certainly want "some text foobar" to be rendered, and Heist would probably seem annoyingly limited for not being able to do this. If the user really did want it to render "some ", it would probably be easier for them to accept that they were silly to pass more than that to be substituted than it would be for the former user to accept that "some <b>text</b> foobar" is being rendered as "some " because it's "more intuitive".

runNodeList :: Monad m => [Node] -> Splice mSource

Performs splice processing on a list of nodes.

mAX_RECURSION_DEPTH :: IntSource

The maximum recursion depth. (Used to prevent infinite loops.)

recurseSplice :: Monad m => Node -> Splice m -> Splice mSource

Checks the recursion flag and recurses accordingly. Does not recurse deeper than mAX_RECURSION_DEPTH to avoid infinite loops.

lookupAndRun :: Monad m => ByteString -> ((DocumentFile, TPath) -> HeistT m (Maybe a)) -> HeistT m (Maybe a)Source

Looks up a template name runs a HeistT computation on it.

evalTemplate :: Monad m => ByteString -> HeistT m (Maybe Template)Source

Looks up a template name evaluates it by calling runNodeList.

fixDocType :: Monad m => Document -> HeistT m DocumentSource

Sets the document type of a Document based on the HeistT value.

evalWithHooksInternal :: Monad m => ByteString -> HeistT m (Maybe Document)Source

Same as evalWithHooks, but returns the entire Document rather than just the nodes. This is the right thing to do if we are starting at the top level.

evalWithHooks :: Monad m => ByteString -> HeistT m (Maybe Template)Source

Looks up a template name evaluates it by calling runNodeList. This also executes pre- and post-run hooks and adds the doctype.

bindStrings :: Monad m => [(Text, Text)] -> HeistState m -> HeistState mSource

Binds a list of constant string splices.

bindString :: Monad m => Text -> Text -> HeistState m -> HeistState mSource

Binds a single constant string splice.

callTemplateSource

Arguments

:: Monad m 
=> ByteString

The name of the template

-> [(Text, Splice m)]

Association list of (name,value) parameter pairs

-> HeistT m Template 

Renders a template with the specified parameters. This is the function to use when you want to call a template and pass in parameters from inside a splice. If the template does not exist, this version simply returns an empty list.

callTemplateWithTextSource

Arguments

:: Monad m 
=> ByteString

The name of the template

-> [(Text, Text)]

Association list of (name,value) parameter pairs

-> HeistT m Template 

Like callTemplate except the splices being bound are constant text splices.

renderTemplate :: Monad m => HeistState m -> ByteString -> m (Maybe (Builder, MIMEType))Source

Renders a template from the specified HeistState to a Builder. The MIME type returned is based on the detected character encoding, and whether the root template was an HTML or XML format template. It will always be texthtml@ or @textxml. If a more specific MIME type is needed for a particular XML application, it must be provided by the application.

renderWithArgs :: Monad m => [(Text, Text)] -> HeistState m -> ByteString -> m (Maybe (Builder, MIMEType))Source

Renders a template with the specified arguments passed to it. This is a convenience function for the common pattern of calling renderTemplate after using bindString, bindStrings, or bindSplice to set up the arguments to the template.

type ParserFun = String -> ByteString -> Either String DocumentSource

Type synonym for parsers.

getDocWith :: ParserFun -> String -> IO (Either String DocumentFile)Source

Reads an HTML or XML template from disk.

getDoc :: String -> IO (Either String DocumentFile)Source

Reads an HTML template from disk.

getXMLDoc :: String -> IO (Either String DocumentFile)Source

Reads an XML template from disk.

loadTemplateSource

Arguments

:: String

path of the template root

-> String

full file path (includes the template root)

-> IO [Either String (TPath, DocumentFile)] 

Loads a template with the specified path and filename. The template is only loaded if it has a .tpl or .xtpl extension.

loadTemplates :: Monad m => FilePath -> HeistState m -> IO (Either String (HeistState m))Source

Traverses the specified directory structure and builds a HeistState by loading all the files with a .tpl or .xtpl extension.

runHook :: Monad m => (Template -> m Template) -> DocumentFile -> m DocumentFileSource

Runs a template modifying function on a DocumentFile.

loadHook :: Monad m => HeistState m -> (TPath, DocumentFile) -> IO (HeistState m)Source

Runs the onLoad hook on the template and returns the HeistState with the result inserted.

addTemplatePathPrefix :: ByteString -> HeistState m -> HeistState mSource

Adds a path prefix to all the templates in the HeistState. If you want to add multiple levels of directories, separate them with slashes as in foo/bar. Using an empty string as a path prefix will leave the HeistState unchanged.