Forms

I’ve mentioned the boundary issue already: whenever data enters or leaves an application, we need to validate it. Probably the most difficult place this occurs is forms. Coding forms is complex; in an ideal world, we’d like a solution that addresses the following problems:

  • Ensure data is valid.

  • Marshal string data in the form submission to Haskell datatypes.

  • Generate HTML code for displaying the form.

  • Generate Javascript to do clientside validation and provide more user-friendly widgets, such as date pickers.

  • Build up more complex forms by combining together simpler forms.

  • Automatically assign names to our fields that are guaranteed to be unique.

The yesod-form package provides all these features in a simple, declarative API. It builds on top of Yesod’s widgets to simplify styling of forms and applying Javascript appropriately. And like the rest of Yesod, it uses Haskell’s type system to make sure everything is working correctly.

Synopsis

  1. {-# LANGUAGE QuasiQuotes, TemplateHaskell, MultiParamTypeClasses,
  2.     OverloadedStrings, TypeFamilies #-}
  3. import Yesod
  4. import Yesod.Form.Jquery
  5. import Data.Time (Day)
  6. import Data.Text (Text)
  7. import Control.Applicative ((<$>), (<*>))
  9. data Synopsis = Synopsis
  11. mkYesod "Synopsis" [parseRoutes|
  12. / RootR GET
  13. /person PersonR POST
  14. |]
  16. instance Yesod Synopsis
  18. -- Tells our application to use the standard English messages.
  19. -- If you want i18n, then you can supply a translating function instead.
  20. instance RenderMessage Synopsis FormMessage where
  21.     renderMessage _ _ = defaultFormMessage
  23. -- And tell us where to find the jQuery libraries. We'll just use the defaults,
  24. -- which point to the Google CDN.
  25. instance YesodJquery Synopsis
  27. -- The datatype we wish to receive from the form
  28. data Person = Person
  29.     { personName :: Text
  30.     , personBirthday :: Day
  31.     , personFavoriteColor :: Maybe Text
  32.     , personEmail :: Text
  33.     , personWebsite :: Maybe Text
  34.     }
  35.   deriving Show
  37. -- Declare the form. The type signature is a bit intimidating, but here's the
  38. -- overview:
  39. --
  40. -- * The Html parameter is used for encoding some extra information. See the
  41. -- discussion regarding runFormGet and runFormPost below for further
  42. -- explanation.
  43. --
  44. -- * We have the sub and master site types, as usual.
  45. --
  46. -- * FormResult can be in three states: FormMissing (no data available),
  47. -- FormFailure (invalid data) and FormSuccess
  48. --
  49. -- * The Widget is the viewable form to place into the web page.
  50. --
  51. -- Note that the scaffolded site provides a convenient Form type synonym,
  52. -- so that our signature could be written as:
  53. --
  54. -- > personForm :: Form Person
  55. --
  56. -- For our purposes, it's good to see the long version.
  57. personForm :: Html -> MForm Synopsis Synopsis (FormResult Person, Widget)
  58. personForm = renderDivs $ Person
  59.     <$> areq textField "Name" Nothing
  60.     <*> areq (jqueryDayField def
  61.         { jdsChangeYear = True -- give a year dropdown
  62.         , jdsYearRange = "1900:-5" -- 1900 till five years ago
  63.         }) "Birthday" Nothing
  64.     <*> aopt textField "Favorite color" Nothing
  65.     <*> areq emailField "Email address" Nothing
  66.     <*> aopt urlField "Website" Nothing
  68. -- The GET handler displays the form
  69. getRootR :: Handler RepHtml
  70. getRootR = do
  71.     -- Generate the form to be displayed
  72.     (widget, enctype) <- generateFormPost personForm
  73.     defaultLayout [whamlet|
  74. <p>The widget generated contains only the contents of the form, not the form tag itself. So...
  75. <form method=post action=@{PersonR} enctype=#{enctype}>
  76.     ^{widget}
  77.     <p>It also doesn't include the submit button.
  78.     <input type=submit>
  79. |]
  81. -- The POST handler processes the form. If it is successful, it displays the
  82. -- parsed person. Otherwise, it displays the form again with error messages.
  83. postPersonR :: Handler RepHtml
  84. postPersonR = do
  85.     ((result, widget), enctype) <- runFormPost personForm
  86.     case result of
  87.         FormSuccess person -> defaultLayout [whamlet|<p>#{show person}|]
  88.         _ -> defaultLayout [whamlet|
  89. <p>Invalid input, let's try again.
  90. <form method=post action=@{PersonR} enctype=#{enctype}>
  91.     ^{widget}
  92.     <input type=submit>
  93. |]
  95. main :: IO ()
  96. main = warpDebug 3000 Synopsis

Kinds of Forms

Before jumping into the types themselves, we should begin with an overview of the different kinds of forms. There are three categories:

Applicative

These are the most commonly used (it’s what appeared in the synopsis). Applicative gives us some nice properties of letting error messages coallesce together and keep a very high-level, declarative approach. (For more information on applicative code, see the Haskell wiki.)

Monadic

A more powerful alternative to applicative. While this allows you more flexibility, it does so at the cost of being more verbose. Useful if you want to create forms that don’t fit into the standard two-column look.

Input

Used only for receiving input. Does not generate any HTML for receiving the user input. Useful for interacting with existing forms.

In addition, there are a number of different variables that come into play for each form and field you will want to set up:

  • Is the field required or optional?

  • Should it be submitted with GET or POST?

  • Does it have a default value, or not?

An overriding goal is to minimize the number of field definitions and let them work in as many contexts as possible. One result of this is that we end up with a few extra words for each field. In the synopsis, you may have noticed things like areq and that extra Nothing parameter. We’ll cover why all of those exist in the course of this chapter, but for now realize that by making these parameters explicit, we are able to reuse the individuals fields (like intField) in many different ways.

A quick note on naming conventions. Each form type has a one-letter prefix (A, M and I) which is used in a few places, such as saying MForm. We also use req and opt to mean required and optional. Combining these, we create a required applicative field with areq, or an optional input field with iopt.

Types

The Yesod.Form.Types module declares a few types. Let’s start off with some simple helpers:

Enctype

The encoding type, either UrlEncoded or Multipart. This datatype declares an instance of ToHtml, so you can use the enctype directly in Hamlet.

Env

Maps a parameter name to a list of values.

FileEnv

Maps a parameter name to the associated uploaded file.

Ints

As mentioned in the introduction, yesod-form automatically assigns a unique name to each field. Ints is used to keep track of the next number to assign.

FormResult

Has one of three possible states: FormMissing if no data was submitted, FormFailure if there was an error parsing the form (e.g., missing a required field, invalid content), or FormSuccess if everything went smoothly.

Next we have three datatypes used for defining individual fields.

A field is a single piece of information, such as a number, a string or an email address. Fields are combined together to build forms.

Field

Defines two pieces of functionality: how to parse the text input from a user into a Haskell value, and how to create the widget to be displayed to the user. yesod-form defines a number of individual Fields in Yesod.Form.Fields.

FieldSettings

Basic information on how a field should be displayed, such as the display name, an optional tooltip, and possibly hardcoded id and name attributes. (If none are provided, they are automatically generated.)

FieldSettings provides an IsString instance, so when you need to provide a FieldSettings value, you can actually type in a literal string. That’s how we interacted with it in the synopsis.

FieldView

An intermediate format containing a bunch of view information on a field. This is hardly ever used directly by the user, we’ll see more details later.

And finally, we get to the important stuff: the forms themselves. There are three types for this: MForm is for monadic forms, AForm for applicative and IForm (declared in IForm) for input. MForm is actually a type synonym for a monad stack that provides the following features:

  • A Reader monad giving us the parameters (Env and FileEnv), the master site argument and the list of languages the user supports. The last two are used for i18n (more on this later).

  • A Writer monad keeping track of the Enctype. A form will always be UrlEncoded, unless there is a file input field, which will force us to use multipart instead.

  • A State monad holding an Ints to keep track of the next unique name to produce.

An AForm is pretty similar. However, there are a few major differences:

  • It produces a list of FieldViews. This allows us to keep an abstract idea of the form display, and then at the end of the day choose an appropriate function for laying it out on the page. In the synopsis, we used renderDivs, which creates a bunch of div tags. Another option would be renderTable.

  • It does not provide a Monad instance. The goal of Applicative is to allow the entire form to run, grab as much information on each field as possible, and then create the final result. This cannot work in the context of Monad.

An IForm is even simpler: it returns either a list of error messages or a result.

Converting

“But wait a minute,” you say. “You said the synopsis uses applicative forms, but I’m sure the type signature said MForm. Shouldn’t it be Monadic?” That’s true, the final form we produced was monadic. But what really happened is that we converted an applicative form to a monadic one.

Again, our goal is to reuse code as much as possible, and minimize the number of functions in the API. And Monadic forms are more powerful than Applicative, if more clumsy, so anything that can be expressed in an Applicative form could also be expressed in a Monadic form. There are two core functions that help out with this: aformToForm converts any applicative form to a monadic one, and formToAForm converts certain kinds of monadic forms to applicative forms.

“But wait another minute,” you insist. “I didn’t see any aformToForm!” Also true. The renderDivs function takes care of that for us.

Create AForms

Now that I’ve (hopefully) convinced you that in our synopsis we were really dealing with applicative forms, let’s have a look and try to understand how these things get created. Let’s take a simple example:

  1. data Car = Car
  2.     { carModel :: Text
  3.     , carYear :: Int
  4.     }
  5.   deriving Show
  7. carAForm :: AForm Synopsis Synopsis Car
  8. carAForm = Car
  9.     <$> areq textField "Model" Nothing
  10.     <*> areq intField "Year" Nothing
  12. carForm :: Html -> MForm Synopsis Synopsis (FormResult Car, Widget)
  13. carForm = renderTable carAForm

Here, we’ve explicitly split up applicative and monadic forms. In carAForm, we use the <$> and <*> operators. This should not be surprising; these are almost always used in applicative-style code. And we have one line for each record in our Car datatype. Perhaps unsurprisingly, we have a textField for the Text record, and an intField for the Int record.

Let’s look a bit more closely at the areq function. Its (simplified) type signature is Field a -> FieldSettings -> Maybe a -> AForm a. So that first argument is going to determine the datatype of this field, how to parse it, and how to render it. The next argument, FieldSettings, tells us the label, tooltip, name and ID of the field. In this case, we’re using the previously-mentioned IsString instance of FieldSettings.

And what’s up with that Maybe a? It provides the optional default value. For example, if we want our form to fill in “2007” as the default car year, we would use areq intField "Year" (Just 2007). We can even take this to the next level, and have a form that takes an optional parameter giving the default values.

Form with default values

  1. carAForm :: Maybe Car -> AForm Synopsis Synopsis Car
  2. carAForm mcar = Car
  3.     <$> areq textField "Model" (carModel <$> mcar)
  4.     <*> areq intField "Year" (carYear <$> mcar)

Optional fields

Suppose we wanted to have an optional field (like the car color). All we do instead is use the aopt function.

Optional fields

  1. data Car = Car
  2.     { carModel :: Text
  3.     , carYear :: Int
  4.     , carColor :: Maybe Text
  5.     }
  6.   deriving Show
  8. carAForm :: AForm Synopsis Synopsis Car
  9. carAForm = Car
  10.     <$> areq textField "Model" Nothing
  11.     <*> areq intField "Year" Nothing
  12.     <*> aopt textField "Color" Nothing

And like required fields, the last argument is the optional default value. However, this has two layers of Maybe wrapping. This may seem redundant (and it is), but it makes it much easier to write code that takes an optional default form parameter, such as in the next example.

Default optional fields

  1. data Car = Car
  2.     { carModel :: Text
  3.     , carYear :: Int
  4.     , carColor :: Maybe Text
  5.     }
  6.   deriving Show
  8. carAForm :: Maybe Car -> AForm Synopsis Synopsis Car
  9. carAForm mcar = Car
  10.     <$> areq textField "Model" (carModel <$> mcar)
  11.     <*> areq intField  "Year"  (carYear  <$> mcar)
  12.     <*> aopt textField "Color" (carColor <$> mcar)
  14. carForm :: Html -> MForm Synopsis Synopsis (FormResult Car, Widget)
  15. carForm = renderTable $ carAForm $ Just $ Car "Forte" 2010 $ Just "gray"

Validation

How would we make our form only accept cars created after 1990? If you remember, we said above that the Field itself contained the information on what is a valid entry. So all we need to do is write a new Field, right? Well, that would be a bit tedious. Instead, let’s just modify an existing one:

  1. carAForm :: Maybe Car -> AForm Synopsis Synopsis Car
  2. carAForm mcar = Car
  3.     <$> areq textField    "Model" (carModel <$> mcar)
  4.     <*> areq carYearField "Year"  (carYear  <$> mcar)
  5.     <*> aopt textField    "Color" (carColor <$> mcar)
  6.   where
  7.     errorMessage :: Text
  8.     errorMessage = "Your car is too old, get a new one!"
  10.     carYearField = check validateYear intField
  12.     validateYear y
  13.         | y < 1990 = Left errorMessage
  14.         | otherwise = Right y

The trick here is the check function. It takes a function (validateYear) that returns either an error message or a modified field value. In this example, we haven’t modified the value at all. That is usually going to be the case. This kind of checking is very common, so we have a shortcut:

  1.     carYearField = checkBool (>= 1990) errorMessage intField

checkBool takes two parameters: a condition that must be fulfilled, and an error message to be displayed if it was not.

You may have noticed the explicit Text type signature on errorMessage. In the presence of OverloadedStrings, this is necessary. In order to support i18n, messages can have many different datatypes, and GHC has no way of determining which instance of IsString you intended to use.

It’s great to make sure the car isn’t too old. But what if we want to make sure that the year specified is not from the future? In order to look up the current year, we’ll need to run some IO. For such circumstances, we’ll need checkM:

  1.     carYearField = checkM inPast $ checkBool (>= 1990) errorMessage intField
  3.     inPast y = do
  4.         thisYear <- liftIO getCurrentYear
  5.         return $ if y <= thisYear
  6.             then Right y
  7.             else Left ("You have a time machine!" :: Text)
  9. getCurrentYear :: IO Int
  10. getCurrentYear = do
  11.     now <- getCurrentTime
  12.     let today = utctDay now
  13.     let (year, _, _) = toGregorian today
  14.     return $ fromInteger year

inPast is a function that will return an Either result. However, it uses a Handler monad. We use liftIO getCurrentYear to get the current year and then compare it against the user-supplied year. Also, notice how we can chain together multiple validators.

Since the checkM validator runs in the Handler monad, it has access to a lot of the stuff you can normally do in Yesod. This is especially useful for running database actions, which we’ll cover in the Persistent chapter.

More sophisticated fields

Our color entry field is nice, but it’s not exactly user-friendly. What we really want is a drop-down list.

Drop-down lists

  1. data Car = Car
  2.     { carModel :: Text
  3.     , carYear :: Int
  4.     , carColor :: Maybe Color
  5.     }
  6.   deriving Show
  8. data Color = Red | Blue | Gray | Black
  9.     deriving (Show, Eq, Enum, Bounded)
  11. carAForm :: Maybe Car -> AForm Synopsis Synopsis Car
  12. carAForm mcar = Car
  13.     <$> areq textField "Model" (carModel <$> mcar)
  14.     <*> areq carYearField "Year" (carYear <$> mcar)
  15.     <*> aopt (selectFieldList colors) "Color" (carColor <$> mcar)
  16.   where
  17.     colors :: [(Text, Color)]
  18.     colors = [("Red", Red), ("Blue", Blue), ("Gray", Gray), ("Black", Black)]

selectFieldList takes a list of pairs. The first item in the pair is the text displayed to the user in the drop-down list, and the second item is the actual Haskell value. Of course, the code above looks really repetitive; we can get the same result using the Enum and Bounded instance GHC automatically derives for us.

Uses Enum and Bounded

  1. data Car = Car
  2.     { carModel :: Text
  3.     , carYear :: Int
  4.     , carColor :: Maybe Color
  5.     }
  6.   deriving Show
  8. data Color = Red | Blue | Gray | Black
  9.     deriving (Show, Eq, Enum, Bounded)
  11. carAForm :: Maybe Car -> AForm Synopsis Synopsis Car
  12. carAForm mcar = Car
  13.     <$> areq textField "Model" (carModel <$> mcar)
  14.     <*> areq carYearField "Year" (carYear <$> mcar)
  15.     <*> aopt (selectFieldList colors) "Color" (carColor <$> mcar)
  16.   where
  17.     colors = map (pack . show &&& id) $ [minBound..maxBound]

[minBound..maxBound] gives us a list of all the different Color values. We then apply a map and &&& (a.k.a, the fan-out operator) to turn that into a list of pairs.

Some people prefer radio buttons to drop-down lists. Fortunately, this is just a one-word change. For example, see Radio buttons

Radio buttons

  1. data Car = Car
  2.     { carModel :: Text
  3.     , carYear :: Int
  4.     , carColor :: Maybe Color
  5.     }
  6.   deriving Show
  8. data Color = Red | Blue | Gray | Black
  9.     deriving (Show, Eq, Enum, Bounded)
  11. carAForm :: Maybe Car -> AForm Synopsis Synopsis Car
  12. carAForm mcar = Car
  13.     <$> areq textField "Model" (carModel <$> mcar)
  14.     <*> areq carYearField "Year" (carYear <$> mcar)
  15.     <*> aopt (radioFieldList colors) "Color" (carColor <$> mcar)
  16.   where
  17.     colors = map (pack . show &&& id) $ [minBound..maxBound]

Running forms

At some point, we’re going to need to take our beautiful forms and produce some results. There are a number of different functions available for this, each with its own purpose. I’ll go through them, starting with the most common.

runFormPost

This will run your form against any submitted POST parameters. If this is not a POST submission, it will return a FormMissing. This automatically inserts a security token as a hidden form field to avoid CSRF attacks.

runFormGet

The equivalent of runFormPost for GET parameters. In order to distinguish a normal GET page load from a GET submission, it includes an extra _hasdata hidden field in the form. Also, unlike runFormPost, it does not include CSRF protection.

runFormPostNoNonce

Same as runFormPost, but does not include (or require) the CSRF security token.

generateFormPost

Instead of binding to existing POST parameters, acts as if there are none. This can be useful when you want to generate a new form after a previous form was submitted, such as in a wizard.

generateFormGet

Same as generateFormPost, but for GET.

The return type from the first three is ((FormResult a, Widget), Enctype). The Widget will already have any validation errors and previously submitted values.

i18n

There have been a few references to i18n in this chapter. The topic will get more thorough coverage in its own chapter, but since it has such a profound effect on yesod-form, I wanted to give a brief overview. The idea behind i18n in Yesod is to have data types represent messages. Each site can have an instance of RenderMessage for a given datatype which will translate that message based on a list of languages the user accepts. As a result of all this, there are a few things you should be aware of:

  • There is an automatic instance of RenderMessage for Text in every site, so you can just use plain strings if you don’t care about i18n support. However, you may need to use explicit type signatures occassionally.

  • yesod-form expresses all of its messages in terms of the FormMessage datatype. Therefore, to use yesod-form, you’ll need to have an appropriate RenderMessage instance. A simple one that uses the default English translations would be:

    1. instance RenderMessage MyApp FormMessage where
    2.     renderMessage _ _ = defaultFormMessage

    This is provided automatically by the scaffolded site.

Monadic Forms

Often times, a simple form layout is adequate, and applicative forms excel at this approach. Sometimes, however, you’ll want to have a more customized look to your form.

A non-standard form layout

Forms - 图1

For these use cases, monadic forms fit the bill. They are a bit more verbose than their applicative cousins, but this verbosity allows you to have complete control over what the form will look like. In order to generate the form above, we could code something like this.

  1. {-# LANGUAGE OverloadedStrings, TypeFamilies, QuasiQuotes,
  2.              TemplateHaskell, MultiParamTypeClasses #-}
  3. import Yesod
  4. import Control.Applicative
  5. import Data.Text (Text)
  7. data MFormExample = MFormExample
  9. mkYesod "MFormExample" [parseRoutes|
  10. / RootR GET
  11. |]
  13. instance Yesod MFormExample
  15. instance RenderMessage MFormExample FormMessage where
  16.     renderMessage _ _ = defaultFormMessage
  18. data Person = Person { personName :: Text, personAge :: Int }
  19.     deriving Show
  21. personForm :: Html -> MForm MFormExample MFormExample (FormResult Person, Widget)
  22. personForm extra = do
  23.     (nameRes, nameView) <- mreq textField "this is not used" Nothing
  24.     (ageRes, ageView) <- mreq intField "neither is this" Nothing
  25.     let personRes = Person <$> nameRes <*> ageRes
  26.     let widget = do
  27.             toWidget [lucius|
  28. ##{fvId ageView} {
  29.     width: 3em;
  30. }
  31. |]
  32.             [whamlet|
  33. #{extra}
  34. <p>
  35.     Hello, my name is #
  36.     ^{fvInput nameView}
  37.     \ and I am #
  38.     ^{fvInput ageView}
  39.     \ years old. #
  40.     <input type=submit value="Introduce myself">
  41. |]
  42.     return (personRes, widget)
  44. getRootR :: Handler RepHtml
  45. getRootR = do
  46.     ((res, widget), enctype) <- runFormGet personForm
  47.     defaultLayout [whamlet|
  48. <p>Result: #{show res}
  49. <form enctype=#{enctype}>
  50.     ^{widget}
  51. |]
  53. main :: IO ()
  54. main = warpDebug 3000 MFormExample

Similar to the applicative areq, we use mreq for monadic forms. (And yes, there’s also mopt for optional fields.) But there’s a big difference: mreq gives us back a pair of values. Instead of hiding away the FieldView value and automatically inserting it into a widget, we get the control to insert it as we see fit.

FieldView has a number of pieces of information. The most important is fvInput, which is the actual form field. In this example, we also use fvId, which gives us back the HTML id attribute of the input tag. In our example, we use that to specify the width of the field.

You might be wondering what the story is with the “this is not used” and “neither is this” values. mreq takes a FieldSettings as its second argument. Since FieldSettings provides an IsString instance, the strings are essentially expanded by the compiler to:

  1. fromString "this is not used" == FieldSettings
  2.     { fsLabel = "this is not used"
  3.     , fsTooltip = Nothing
  4.     , fsId = Nothing
  5.     , fsName = Nothing
  6.     , fsClass = []
  7.     }

In the case of applicative forms, the fsLabel and fsTooltip values are used when constructing your HTML. In the case of monadic forms, Yesod does not generate any of the “wrapper” HTML for you, and therefore these values are ignored. However, we still keep the FieldSettings parameter to allow you to override the id and name attributes of your fields if desired.

The other interesting bit is the extra value. GET forms include an extra field to indicate that they have been submitted, and POST forms include a security tokens to prevent CSRF attacks. If you don’t include this extra hidden field in your form, Yesod will not accept it.

Other than that, things are pretty straight-forward. We create our personRes value by combining together the nameRes and ageRes values, and then return a tuple of the person and the widget. And in the getRootR function, everything looks just like an applicative form. In fact, you could swap out our monadic form with an applicative one and the code would still work.

Input forms

Applicative and monadic forms handle both the generation of your HTML code and the parsing of user input. Sometimes, you only want to do the latter, such as when there’s an already-existing form in HTML somewhere, or if you want to generate a form dynamically using Javascript. In such a case, you’ll want input forms.

These work mostly the same as applicative and monadic forms, with some differences:

  • You use runInputPost and runInputGet.

  • You use ireq and iopt. These functions now only take two arguments: the field type and the name (i.e., HTML name attribute) of the field in question.

  • After running a form, it returns the value. It doesn’t return a widget or an encoding type.

  • If there are any validation errors, the page returns an “invalid arguments” error page.

You can use input forms to recreate the previous example. Note, however, that the input version is less user friendly. If you make a mistake in an applicative or monadic form, you will be brought back to the same page, with your previously entered values in the form, and an error message explaning what you need to correct. With input forms, the user simply gets an error message.

  1. {-# LANGUAGE OverloadedStrings, TypeFamilies, QuasiQuotes,
  2.              TemplateHaskell, MultiParamTypeClasses #-}
  3. import Yesod
  4. import Control.Applicative
  5. import Data.Text (Text)
  7. data Input = Input
  9. mkYesod "Input" [parseRoutes|
  10. / RootR GET
  11. /input InputR GET
  12. |]
  14. instance Yesod Input
  16. instance RenderMessage Input FormMessage where
  17.     renderMessage _ _ = defaultFormMessage
  19. data Person = Person { personName :: Text, personAge :: Int }
  20.     deriving Show
  22. getRootR :: Handler RepHtml
  23. getRootR = defaultLayout [whamlet|
  24. <form action=@{InputR}>
  25.     <p>
  26.         My name is #
  27.         <input type=text name=name>
  28.         \ and I am #
  29.         <input type=text name=age>
  30.         \ years old. #
  31.         <input type=submit value="Introduce myself">
  32. |]
  34. getInputR :: Handler RepHtml
  35. getInputR = do
  36.     person <- runInputGet $ Person
  37.                 <$> ireq textField "name"
  38.                 <*> ireq intField "age"
  39.     defaultLayout [whamlet|<p>#{show person}|]
  41. main :: IO ()
  42. main = warpDebug 3000 Input

Custom fields

The fields that come built-in with Yesod will likely cover the vast majority of your form needs. But occassionally, you’ll need something more specialized. Fortunately, you can create new forms in Yesod yourself. The Field datatype has two records: fieldParse takes a list of values submitted by the user and returns one of three results:

  • An error message saying validation failed.

  • The parsed value.

  • Nothing, indicating that no data was supplied.

That last case might sound surprising: shouldn’t Yesod automatically know that no information is supplied when the input list is empty? Well, no actually. Checkboxes, for instance, indicate an unchecked state by sending in an empty list.

Also, what’s up with the list? Shouldn’t it be a Maybe? Well, that’s also not the case. With grouped checkboxes and multi-select lists, you’ll have multiple widgets with the same name. We also use this trick in our example below.

The second record is fieldView, and it renders a widget to display to the user. This function has four arguments: the id attribute, the name attribute, the result and a Bool indicating if the field is required.

What did I mean by result? It’s actually an Either, giving either the unparsed input (when parsing failed) or the successfully parsed value. intField is a great example of how this works. If you type in 42, the value of result will be Right 42. But if you type in turtle, the result will be Left "turtle". This lets you put in a value attribute on your input tag that will give the user a consistent experience.

As a small example, we’ll create a new field type that is a password confirm field. This field has two text inputs- both with the same name attribute- and returns an error message if the values don’t match. Note that, unlike most fields, it does not provide a value attribute on the input tags, as you don’t want to send back a user-entered password in your HTML ever.

  1. passwordConfirmField :: Field sub master Text
  2. passwordConfirmField = Field
  3.     { fieldParse = \rawVals ->
  4.         case rawVals of
  5.             [a, b]
  6.                 | a == b -> return $ Right $ Just a
  7.                 | otherwise -> return $ Left "Passwords don't match"
  8.             [] -> return $ Right Nothing
  9.             _ -> return $ Left "You must enter two values"
  10.     , fieldView = \idAttr nameAttr _ eResult isReq -> [whamlet|
  11. <input id=#{idAttr} name=#{nameAttr} type=password>
  12. <div>Confirm:
  13. <input id=#{idAttr}-confirm name=#{nameAttr} type=password>
  14. |]
  15.     }
  17. getRootR :: Handler RepHtml
  18. getRootR = do
  19.     ((res, widget), enctype) <- runFormGet $ renderDivs
  20.         $ areq passwordConfirmField "Password" Nothing
  21.     defaultLayout [whamlet|
  22. <p>Result: #{show res}
  23. <form enctype=#{enctype}>
  24.     ^{widget}
  25.     <input type=submit value="Change password">
  26. |]

Summary

Forms in Yesod are broken up into three groups. Applicative is the most common, as it provides a nice user interface with an easy-to-use API. Monadic forms give you more power, but are harder to use. Input forms are intended when you just want to read data from the user, not generate the input widgets.

There are a number of different Fields provided by Yesod out-of-the-box. In order to use these in your forms, you need to indicate the kind of form and whether the field is required or optional. The result is six helper functions: areq, aopt, mreq, mopt, ireq, and iopt.

Forms have significant power available. They can automatically insert Javascript to help you leverage nicer UI controls, such as a jQuery UI date picker. Forms are also fully i18n-ready, so you can support a global community of users. And when you have more specific needs, you can slap on some validation functions to an existing field, or write a new one from scratch.