Text.Digestive.Heist

This module provides a 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 functions digestiveSplices and bindDigestiveSplices, 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" />

Core methods

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

bindDigestiveSplices :: MonadIO m => View Text -> HeistState m -> HeistState m

Main splices

dfInput :: Monad m => View v -> Splice m

Generate an input field with a supplied type. Example:

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

dfInputList :: MonadIO m => View Text -> Splice m

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".

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 => View v -> Splice m

Generate a text input field. Example:

 <dfInputText ref="user.name" />

dfInputTextArea :: Monad m => View v -> Splice m

Generate a text area. Example:

 <dfInputTextArea ref="user.about" />

dfInputPassword :: Monad m => View v -> Splice m

Generate a password field. Example:

 <dfInputPassword ref="user.password" />

dfInputHidden :: Monad m => View v -> Splice m

Generate a hidden input field. Example:

 <dfInputHidden ref="user.forgery" />

dfInputSelect :: Monad m => View Text -> Splice m

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

 <dfInputSelect ref="user.sex" />

dfInputSelectGroup :: Monad m => View Text -> Splice m

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

 <dfInputSelectGroup ref="user.sex" />

dfInputRadio :: Monad m => View Text -> Splice m

Generate a number of radio buttons. Example:

 <dfInputRadio ref="user.sex" />

dfInputCheckbox :: Monad m => View Text -> Splice m

Generate a checkbox. Example:

 <dfInputCheckbox ref="user.married" />

dfInputSubmit :: Monad m => View v -> Splice m

Generate a submit button. Example:

 <dfInputSubmit />

dfLabel :: Monad m => View v -> Splice m

Generate a label for a field. Example:

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

dfForm :: Monad m => View v -> Splice m

Generate a form tag with the method attribute set to POST and the enctype set to the right value (depending on the form). Custom method or enctype attributes would override this behavior. Example:

 <dfForm action="/users/new">
     <dfInputText ... />
     ...
     <dfInputSubmit />
 </dfForm>

dfErrorList :: Monad m => View Text -> Splice m

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

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

dfChildErrorList :: Monad m => View Text -> Splice m

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 => View Text -> Splice m

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" />
 <dfInputText ref="user.password" />

 <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 :: Monad m => View v -> Splice m

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.