Get a unique identifier.

Converts a monadic form MForm into another monadic form WForm.

Since: 1.4.14

Converts a monadic form WForm into an applicative form AForm.

Since: 1.4.14

Converts a monadic form WForm into another monadic form MForm.

Since: 1.4.14

Converts a form field into monadic form WForm. This field requires a value and will return FormFailure if left empty.

Since: 1.4.14

Same as wreq but with your own message to be rendered in case the value is not provided.

This is useful when you have several required fields on the page and you want to differentiate between which fields were left blank. Otherwise the user sees "Value is required" multiple times, which is ambiguous.

Since: 1.6.7

Converts a form field into monadic form WForm. This field is optional, i.e. if filled in, it returns 'Just a', if left empty, it returns Nothing. Arguments are the same as for wreq (apart from type of default value).

Since: 1.4.14

Converts a form field into monadic form. This field requires a value and will return FormFailure if left empty.

Same as mreq but with your own message to be rendered in case the value is not provided.

This is useful when you have several required fields on the page and you want to differentiate between which fields were left blank. Otherwise the user sees "Value is required" multiple times, which is ambiguous.

Since: 1.6.6

Converts a form field into monadic form. This field is optional, i.e. if filled in, it returns 'Just a', if left empty, it returns Nothing. Arguments are the same as for mreq (apart from type of default value).

Applicative equivalent of mreq.

Same as areq but with your own message to be rendered in case the value is not provided.

This is useful when you have several required fields on the page and you want to differentiate between which fields were left blank. Otherwise the user sees "Value is required" multiple times, which is ambiguous.

Since: 1.6.7

Applicative equivalent of mopt.

This function is used to both initially render a form and to later extract results from it. Note that, due to CSRF protection and a few other issues, forms submitted via GET and POST are slightly different. As such, be sure to call the relevant function based on how the form will be submitted, not the current request method.

For example, a common case is displaying a form on a GET request and having the form submit to a POST page. In such a case, both the GET and POST handlers should use runFormPost.

Run a form for the Post/Redirect/Get pattern, so that invalid input and its validation errors survive a redirect.

Use this in both the GET and POST handlers of a route, exactly as you would runFormPost:

• On a POST request this behaves exactly like runFormPost (including CSRF protection). Additionally, on FormFailure the submitted parameters are stashed in the user session so that your handler can simply redirect back to the GET route instead of re-rendering. On FormSuccess any previously stashed parameters for this route are cleared. On FormMissing (another identifyForm-wrapped form on the page was the one submitted) the stash is left untouched.
• On a GET request, if stashed parameters exist for the current path, they are removed from the session and the form is run against them: the fields re-render with the user's input and validation errors, just as a non-redirecting handler would have rendered them. A fresh CSRF token is rendered into the form (the stashed token is discarded, and no token check is performed on a replay). If nothing is stashed, this behaves like generateFormPost (the result is FormMissing).

getRegisterR :: Handler Markup
getRegisterR = do
    ((_res, widget), enctype) <- runFormPRG personForm
    defaultLayout
        [whamlet|
            <form method=post action=@{RegisterR} enctype=#{enctype}>
                ^{widget}
        |]

postRegisterR :: Handler Markup
postRegisterR = do
    ((res, _widget), _enctype) <- runFormPRG personForm
    case res of
        FormSuccess person -> do
            -- insert into the database, etc.
            setMessage "Registered!"
            redirect RegisterR
        _ -> redirect RegisterR

Notes and caveats:

• The stash is keyed by request path, so the GET and POST handlers must share a route (the common Yesod pattern). Form pages on different routes do not interfere with each other; two tabs on the same path share one stash (the last failed submission wins).
• Multiple forms on one page work when wrapped with identifyForm: on replay, only the form that was actually submitted re-renders with values and errors; the others return FormMissing and render blank. (The stash is popped once per request and shared between calls via the per-request cache, so every form in the handler sees it.)
• Uploaded files are not stashed; file fields re-render empty after the redirect.
• The stashed parameters live in the user session. With the default client-session backend the whole session must fit in a cookie (roughly 4KB), so this is unsuitable for very large forms. If the stash fails to decode, it is discarded and a blank form is generated.
• If the application has no session backend, stashing is a no-op and this degrades to runFormPost/generateFormPost semantics (input will not survive the redirect).
• If your POST handler re-renders on failure instead of redirecting, do not use this function: the stash would be consumed by an unrelated later GET of the same path.
• On a replay the form may even produce FormSuccess (e.g. a checkM validation whose outcome depends on external state); the result is returned as-is. GET handlers normally use only the widget.
• A HEAD request reads the stash without consuming it, so that middleware such as autoHead does not eat the replay meant for the subsequent GET.

Since: 1.7.10

Similar to runFormPost, except it always ignores the currently available environment. This is necessary in cases like a wizard UI, where a single page will both receive and incoming form and produce a new, blank form. For general usage, you can stick with runFormPost.

Since 1.3.11

Creates a hidden field on the form that identifies it. This identification is then used to distinguish between missing and wrong form data when a single handler contains more than one form.

For instance, if you have the following code on your handler:

((fooRes, fooWidget), fooEnctype) <- runFormPost fooForm
((barRes, barWidget), barEnctype) <- runFormPost barForm

Then replace it with

((fooRes, fooWidget), fooEnctype) <- runFormPost $ identifyForm "foo" fooForm
((barRes, barWidget), barEnctype) <- runFormPost $ identifyForm "bar" barForm

Note that it's your responsibility to ensure that the identification strings are unique (using the same one twice on a single handler will not generate any errors). This allows you to create a variable number of forms and still have them work even if their number or order change between the HTML generation and the form submission.

Render a form into a series of tr tags. Note that, in order to allow you to add extra rows to the table, this function does not wrap up the resulting HTML in a table tag; you must do that yourself.

render a field inside a div

render a field inside a div, not displaying any label

Deprecated synonym for renderBootstrap2.

Render a form using Bootstrap v2-friendly shamlet syntax. If you're using Bootstrap v3, then you should use the functions from module Yesod.Form.Bootstrap3.

Sample Hamlet:

 <form .form-horizontal method=post action=@{ActionR} enctype=#{formEnctype}>
   <fieldset>
     <legend>_{MsgLegend}
     $case result
       $of FormFailure reasons
         $forall reason <- reasons
           <div .alert .alert-error>#{reason}
       $of _
     ^{formWidget}
     <div .form-actions>
       <input .btn .primary type=submit value=_{MsgSubmit}>

Since 1.3.14

Return the given error message if the predicate is false.

Same as checkM, but modifies the datatype.

In order to make this work, you must provide a function to convert back from the new datatype to the old one (the second argument to this function).

Since 1.1.2

Allows you to overwrite the error message on parse error.

Generate a FieldSettings from the given label.

A helper function for creating custom fields.

This is intended to help with the common case where a single input value is required, such as when parsing a text field.

Since 1.1

A generalized version of parseHelper, allowing any type for the message indicating a bad parse.

Since 1.3.6

Since a Field cannot be a Functor, it is not obvious how to "reuse" a Field on a newtype or otherwise equivalent type. This function allows you to convert a Field m a to a Field m b assuming you provide a bidirectional conversion between the two, through the first two functions.

A simple example:

import Data.Monoid
sumField :: (Functor m, Monad m, RenderMessage (HandlerSite m) FormMessage) => Field m (Sum Int)
sumField = convertField Sum getSum intField

Another example, not using a newtype, but instead creating a Lazy Text field:

import qualified Data.Text.Lazy as TL
TextField :: (Functor m, Monad m, RenderMessage (HandlerSite m) FormMessage) => Field m TL.Text
lazyTextField = convertField TL.fromStrict TL.toStrict textField

Since 1.3.16

Adds a CSS class to the fsAttrs in a FieldSettings.

Examples

>>> addClass "login-form" [("class", "form-control"), ("id", "home-login")]
[("class","form-control login-form"),("id","home-login")]

Since: 1.6.2

Removes a CSS class from the fsAttrs in a FieldSettings.

Examples

>>> removeClass "form-control" [("class","form-control login-form"),("id","home-login")]
[("class","  login-form"),("id","home-login")]

Since: 1.6.2

The raw parameter values the named field was run against in this request, whether from a direct submission or a Post/Redirect/Get replay (runFormPRG). Empty if no form containing the field has run with a submission in this request (e.g. generateFormPost, or an identifyForm-wrapped form that was not the one submitted).

This lets the view of a field rendering several inputs under one name restore all of the user's raw input after a failed submission: the Either Text a argument a view receives can only carry the first submitted value. Only fields run through mreq/mopt (and the applicative/widget helpers built on them) record their values here.

Since: 1.7.11