digestive-functors-heist-0.8.8.1: Heist frontend for the digestive-functors library

Text.Digestive.Heist.Compiled

Description

This module provides a compiled Heist frontend for the digestive-functors library.

Disclaimer: this documentation requires very basic familiarity with digestive-functors. You might want to take a quick look at this tutorial first:

https://github.com/jaspervdj/digestive-functors/blob/master/examples/tutorial.lhs

This module exports the formSplice function, and most users will not require anything else.

These splices are used to create HTML for different form elements. This way, the developer doesn't have to care about setting e.g. the previous values in a text field when something goes wrong.

For documentation on the different splices, see the different functions exported by this module. All splices have the same name as given in digestiveSplices.

You can give arbitrary attributes to most of the elements (i.e. where it makes sense). This means you can do e.g.:

<dfInputTextArea ref="description" cols="20" rows="3" />
Synopsis

# Core methods

Arguments

 :: MonadIO m => Splices (Splice m) Extra splices that you want to have available inside the form tag. -> Splices (AttrSplice m) Attribute splices available inside the form tag. -> RuntimeSplice m (View Text) -> Splice m

A compiled splice for a specific form. You pass in a runtime action that gets the form's view and this function returns a splice that creates a form tag. In your HeistConfig you might have a compiled splice like this:

("customerForm" ## formSplice mempty mempty
(liftM fst \$ runForm "customer" custForm))

Then you can use the customerForm tag just like you would use the dfForm tag in interpreted templates anywhere you want to have a customer form.

formSplice' :: MonadIO m => (RuntimeSplice m (View Text) -> Splices (Splice m)) -> (RuntimeSplice m (View Text) -> Splices (AttrSplice m)) -> RuntimeSplice m (View Text) -> Splice m Source #

Same as formSplice except the supplied splices and attribute splices are applied to the resulting form view.

# Main splices

dfInput :: Monad m => RuntimeSplice m (View v) -> Splice m Source #

Generate an input field with a supplied type. Example:

<dfInput type="date" ref="date" />

dfInputList :: MonadIO m => RuntimeSplice m (View Text) -> Splice m Source #

This splice allows variable length lists. It binds several attribute splices providing functionality for dynamically manipulating the list. The following descriptions will use the example of a form named "foo" with a list subform named "items".

Splices: dfListItem - This tag must surround the markup for a single list item. It surrounds all of its children with a div with id "foo.items" and class "inputList" and displays a copy for each of the list items including a "template" item used for generating new items. If the you supply the attribute "noTemplate", then the template item is not included and the generated list will not be dynamically updated by the add and remove actions.

Attribute Splices: itemAttrs - Attribute you should use on div, span, etc that surrounds all the markup for a single list item. This splice expands to an id of "foo.items.ix" (where ix is the index of the current item) and a class of "inputListItem". addControl - Use this attribute on the tag you use to define a control for adding elements to the list (usually a button or anchor). It adds an onclick attribute that calls a javascript function addInputListItem. removeControl - Use this attribute on the control for removing individual items. It adds an onclick attribute that calls removeInputListItem.

dfInputText :: Monad m => RuntimeSplice m (View v) -> Splice m Source #

Generate a text input field. Example:

<dfInputText ref="user.name" />

dfInputTextArea :: Monad m => RuntimeSplice m (View v) -> Splice m Source #

Generate a text area. Example:

<dfInputTextArea ref="user.about" />

dfInputPassword :: Monad m => RuntimeSplice m (View v) -> Splice m Source #

<dfInputPassword ref="user.password" />

dfInputHidden :: Monad m => RuntimeSplice m (View v) -> Splice m Source #

Generate a hidden input field. Example:

<dfInputHidden ref="user.forgery" />

dfInputSelect :: Monad m => RuntimeSplice m (View Text) -> Splice m Source #

Generate a select button (also known as a combo box). Example:

<dfInputSelect ref="user.sex" />

Generate a select button (also known as a combo box). Example:

<dfInputSelectGroup ref="user.sex" />

dfInputRadio :: Monad m => RuntimeSplice m (View Text) -> Splice m Source #

Generate a number of radio buttons. Example:

<dfInputRadio ref="user.sex" />

dfInputCheckbox :: Monad m => RuntimeSplice m (View v) -> Splice m Source #

Generate a checkbox. Example:

<dfInputCheckbox ref="user.married" />

dfInputFile :: Monad m => RuntimeSplice m (View v) -> Splice m Source #

Generate a file upload element. Example:

<dfInputFile ref="user.avatar" />

Generate a submit button. Example:

<dfInputSubmit />

dfLabel :: Monad m => RuntimeSplice m (View v) -> Splice m Source #

Generate a label for a field. Example:

<dfLabel ref="user.married">Married: </dfLabel>
<dfInputCheckbox ref="user.married" />

dfErrorList :: MonadIO m => RuntimeSplice m (View Text) -> Splice m Source #

Display the list of errors for a certain field. Example:

<dfErrorList ref="user.name" />
<dfInputText ref="user.name" />

Display the list of errors for a certain form and all forms below it. E.g., if there is a subform called "user":

<dfChildErrorList ref="user" />

Or display all errors for the form:

<dfChildErrorList ref="" />

Which is more conveniently written as:

<dfChildErrorList />

dfSubView :: MonadIO m => RuntimeSplice m (View Text) -> Splice m Source #

This splice allows reuse of templates by selecting some child of a form tree. While this may sound complicated, it's pretty straightforward and practical. Suppose we have:

<dfInputText ref="user.name" />

<dfInputTextArea ref="comment.body" />

You may want to abstract the "user" parts in some other template so you Don't Repeat Yourself (TM). If you create a template called "user-form" with the following contents:

<dfInputText ref="name" />
<dfInputText ref="password" />

You will be able to use:

<dfSubView ref="user">
<apply template="user-form" />
</dfSubView>

<dfInputTextArea ref="comment.body" />

# Utility splices

dfIfChildErrors :: MonadIO m => RuntimeSplice m (View v) -> Splice m Source #

Render some content only if there are any errors. This is useful for markup purposes.

<dfIfChildErrors ref="user">
Content to be rendered if there are any errors...
</dfIfChildErrors>

The ref attribute can be omitted if you want to check the entire form.

digestiveSplices :: MonadIO m => RuntimeSplice m (View Text) -> Splices (Splice m) Source #

List of splices defined for forms. For most uses the formSplice function will be fine and you won't need to use this directly. But this is available if you need more customization.