Safe Haskell | None |
---|

Compiled splices are similar to the original Heist (interpreted) splices, but without the high performance costs of traversing a DOM at runtime. Compiled splices do all of their DOM processing at load time. They are compiled to produce a runtime computation that generates a ByteString Builder. This preserves the ability to write splices that access runtime information from the HTTP request, database, etc.

If you import both this module and Heist.Interpreted in the same file, then you will need to import them qualified.

- type Splice n = HeistT n IO (DList (Chunk n))
- renderTemplate :: Monad n => HeistState n -> ByteString -> Maybe (n Builder, MIMEType)
- mapPromises :: Monad n => (Promise a -> HeistT n IO (RuntimeSplice n Builder)) -> n [a] -> Splice n
- promiseChildren :: Monad m => HeistT m IO (RuntimeSplice m Builder)
- promiseChildrenWith :: Monad n => [(Text, a -> Builder)] -> Promise a -> HeistT n IO (RuntimeSplice n Builder)
- promiseChildrenWithTrans :: Monad n => (b -> Builder) -> [(Text, a -> b)] -> Promise a -> HeistT n IO (RuntimeSplice n Builder)
- promiseChildrenWithText :: Monad n => [(Text, a -> Text)] -> Promise a -> HeistT n IO (RuntimeSplice n Builder)
- promiseChildrenWithNodes :: Monad n => [(Text, a -> [Node])] -> Promise a -> HeistT n IO (RuntimeSplice n Builder)
- yieldPure :: Builder -> DList (Chunk m)
- yieldRuntime :: RuntimeSplice m Builder -> DList (Chunk m)
- yieldRuntimeEffect :: Monad m => RuntimeSplice m () -> DList (Chunk m)
- yieldPureText :: Text -> DList (Chunk m)
- yieldRuntimeText :: Monad m => RuntimeSplice m Text -> DList (Chunk m)
- yieldLater :: Monad m => m Builder -> DList (Chunk m)
- addSplices :: Monad m => [(Text, Splice n)] -> HeistT n m ()
- data Promise a
- newEmptyPromise :: HeistT n IO (Promise a)
- getPromise :: Monad m => Promise a -> RuntimeSplice m a
- putPromise :: Monad m => Promise a -> a -> RuntimeSplice m ()
- adjustPromise :: Monad m => Promise a -> (a -> a) -> RuntimeSplice m ()
- codeGen :: Monad m => [Chunk m] -> RuntimeSplice m Builder
- runNodeList :: Monad n => [Node] -> Splice n
- runNode :: Monad n => Node -> Splice n
- compileNode :: Monad n => Node -> Splice n
- runSplice :: Monad n => Node -> HeistState n -> Splice n -> IO [Chunk n]

# High level compiled splice API

type Splice n = HeistT n IO (DList (Chunk n))Source

A compiled Splice is a HeistT computation that returns a ```
DList
(Chunk m)
```

.

The more interesting part of the type signature is what comes before the
return value. The first type parameter in

is the runtime
monad. This reveals that the Chunks know about the runtime monad. The
second type parameter in `HeistT`

n IO`HeistT n IO`

is `IO`

. This tells is that the
compiled splices themselves are run in the IO monad, which will usually
mean at load time. Compiled splices run at load time, and they return
computations that run at runtime.

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

Looks up a compiled template and returns a runtime monad computation that constructs a builder.

:: Monad n | |

=> (Promise a -> HeistT n IO (RuntimeSplice n Builder)) | Use |

-> n [a] | Runtime computation returning a list of items |

-> Splice n |

Takes a promise function and a runtime action returning a list of items that fit in the promise and returns a Splice that executes the promise function for each item and concatenates the results.

This function works nicely with the `promiseChildrenWith`

family of
functions, much like the combination of `mapSplices`

and `runChildrenWith`

for interpreted splices.

promiseChildren :: Monad m => HeistT m IO (RuntimeSplice m Builder)Source

Returns a runtime computation that simply renders the node's children.

promiseChildrenWith :: Monad n => [(Text, a -> Builder)] -> Promise a -> HeistT n IO (RuntimeSplice n Builder)Source

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

promiseChildrenWithTrans :: Monad n => (b -> Builder) -> [(Text, a -> b)] -> Promise a -> HeistT n IO (RuntimeSplice n Builder)Source

Wrapper that composes a transformation function with the second item in each of the tuples before calling promiseChildren.

promiseChildrenWithText :: Monad n => [(Text, a -> Text)] -> Promise a -> HeistT n IO (RuntimeSplice n Builder)Source

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

promiseChildrenWithNodes :: Monad n => [(Text, a -> [Node])] -> Promise a -> HeistT n IO (RuntimeSplice n Builder)Source

Binds a list of Node splices before using the children of the spliced node as a view. Note that this will slow down page generation because the nodes generated by the splices must be traversed and rendered into a ByteString at runtime.

# Constructing Chunks

The internals of the Chunk data type are deliberately not exported because
we want to hide the underlying implementation as much as possible. The
`yield...`

functions give you lower lever construction of Chunks and DLists
of Chunks.

yieldPure :: Builder -> DList (Chunk m)Source

Yields a pure Builder known at load time. You should use this and
`yieldPureText`

as much as possible to maximize the parts of your page that
can be compiled to static ByteStrings.

yieldRuntime :: RuntimeSplice m Builder -> DList (Chunk m)Source

Yields a runtime action that returns a builder.

yieldRuntimeEffect :: Monad m => RuntimeSplice m () -> DList (Chunk m)Source

Yields a runtime action that returns no value and is only needed for its side effect.

yieldPureText :: Text -> DList (Chunk m)Source

A convenience wrapper around yieldPure for working with Text. Roughly
equivalent to `textSplice`

from Heist.Interpreted.

yieldRuntimeText :: Monad m => RuntimeSplice m Text -> DList (Chunk m)Source

Convenience wrapper around yieldRuntime allowing you to work with Text.

yieldLater :: Monad m => m Builder -> DList (Chunk m)Source

This lets you turn a plain runtime monad function returning a Builder into a compiled splice.

addSplices :: Monad m => [(Text, Splice n)] -> HeistT n m ()Source

Adds a list of compiled splices to the splice map. This function is useful because it allows compiled splices to bind other compiled splices during load-time splice processing.

# Lower level promise functions

Promises are used for referencing the results of future runtime computations during load time splice processing.

newEmptyPromise :: HeistT n IO (Promise a)Source

Creates an empty promise.

# RuntimeSplice functions

getPromise :: Monad m => Promise a -> RuntimeSplice m aSource

Gets the result of a promised runtime computation.

putPromise :: Monad m => Promise a -> a -> RuntimeSplice m ()Source

Adds a promise to the runtime splice context.

adjustPromise :: Monad m => Promise a -> (a -> a) -> RuntimeSplice m ()Source

Modifies a promise.

codeGen :: Monad m => [Chunk m] -> RuntimeSplice m BuilderSource

Given a list of output chunks, consolidate turns consecutive runs of
`Pure Html`

values into maximally-efficient pre-rendered strict
`ByteString`

chunks.

# Running nodes and splices

runNodeList :: Monad n => [Node] -> Splice nSource

Returns a computation that performs load-time splice processing on the supplied list of nodes.

runNode :: Monad n => Node -> Splice nSource

Runs a single node. If there is no splice referenced anywhere in the subtree, then it is rendered as a pure chunk, otherwise it is compiled to a runtime computation.