Yesod.Form.Fields

Field functions allow you to easily create and validate forms, cleanly handling the uncertainty of parsing user input.

When possible, the field functions use a specific input type (e.g. "number"), allowing supporting browsers to validate the input before form submission. Browsers can also improve usability with this information; for example, mobile browsers might present a specialized keyboard for an input of type "email" or "number".

See the Yesod book chapter on forms for a broader overview of forms in Yesod.

i18n

data FormMessage

Constructors

MsgInvalidInteger Text

MsgInvalidNumber Text

MsgInvalidEntry Text

MsgInvalidUrl Text

MsgInvalidEmail Text

MsgInvalidTimeFormat

MsgInvalidHour Text

MsgInvalidMinute Text

MsgInvalidSecond Text

MsgInvalidDay

MsgCsrfWarning

MsgValueRequired

MsgInputNotFound Text

MsgSelectNone

MsgInvalidBool Text

MsgBoolYes

MsgBoolNo

MsgDelete

Instances

Eq FormMessage

Defined in Yesod.Form.Types

Methods

(==) :: FormMessage -> FormMessage -> Bool

(/=) :: FormMessage -> FormMessage -> Bool

Read FormMessage

Defined in Yesod.Form.Types

Methods

readsPrec :: Int -> ReadS FormMessage

readList :: ReadS [FormMessage]

readPrec :: ReadPrec FormMessage

readListPrec :: ReadPrec [FormMessage]

Show FormMessage

Defined in Yesod.Form.Types

Methods

showsPrec :: Int -> FormMessage -> ShowS

show :: FormMessage -> String

showList :: [FormMessage] -> ShowS

defaultFormMessage :: FormMessage -> Text

Fields

textField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Text

Creates a input with type="text".

passwordField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Text

Creates an input with type="password".

textareaField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Textarea

Creates a <textarea> tag whose returned value is wrapped in a Textarea; see Textarea for details.

hiddenField :: (Monad m, PathPiece p, RenderMessage (HandlerSite m) FormMessage) => Field m p

Creates an input with type="hidden"; you can use this to store information in a form that users shouldn't see (for example, Yesod stores CSRF tokens in a hidden field).

intField :: (Monad m, Integral i, RenderMessage (HandlerSite m) FormMessage) => Field m i

Creates a input with type="number" and step=1.

dayField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Day

Creates an input with type="date", validating the input using the parseDate function.

Add the time package and import the Data.Time.Calendar module to use this function.

timeField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m TimeOfDay

An alias for timeFieldTypeTime.

timeFieldTypeTime :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m TimeOfDay

Creates an input with type="time". Browsers not supporting this type will fallback to a text field, and Yesod will parse the time as described in timeFieldTypeText.

Add the time package and import the Data.Time.LocalTime module to use this function.

Since 1.4.2

timeFieldTypeText :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m TimeOfDay

Creates an input with type="text", parsing the time from an [H]H:MM[:SS] format, with an optional AM or PM (if not given, AM is assumed for compatibility with the 24 hour clock system).

This function exists for backwards compatibility with the old implementation of timeField, which used to use type="text". Consider using timeField or timeFieldTypeTime for improved UX and validation from the browser.

Add the time package and import the Data.Time.LocalTime module to use this function.

Since 1.4.2

htmlField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Html

Creates a <textarea> tag whose input is sanitized to prevent XSS attacks and is validated for having balanced tags.

emailField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Text

Creates an input with type="email". Yesod will validate the email's correctness according to RFC5322 and canonicalize it by removing comments and whitespace (see Text.Email.Validate).

multiEmailField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m [Text]

Creates an input with type="email" with the multiple attribute; browsers might implement this as taking a comma separated list of emails. Each email address is validated as described in emailField.

Since 1.3.7

searchField :: Monad m => RenderMessage (HandlerSite m) FormMessage => AutoFocus -> Field m Text

Creates an input with type="search". For browsers without autofocus support, a JS fallback is used if AutoFocus is true.

type AutoFocus = Bool

urlField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Text

Creates an input with type="url", validating the URL according to RFC3986.

doubleField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Double

Creates a input with type="number" and step=any.

parseDate :: String -> Either FormMessage Day

Parses a Day from a String.

parseTime :: Text -> Either FormMessage TimeOfDay

newtype Textarea

A newtype wrapper around a Text whose ToMarkup instance converts newlines to HTML <br> tags.

(When text is entered into a <textarea>, newline characters are used to separate lines. If this text is then placed verbatim into HTML, the lines won't be separated, thus the need for replacing with <br> tags). If you don't need this functionality, simply use unTextarea to access the raw text.

Constructors

Textarea

Fields

• unTextarea :: Text

Instances

Eq Textarea

Defined in Yesod.Form.Fields

Methods

(==) :: Textarea -> Textarea -> Bool

(/=) :: Textarea -> Textarea -> Bool

Ord Textarea

Defined in Yesod.Form.Fields

Methods

compare :: Textarea -> Textarea -> Ordering

(<) :: Textarea -> Textarea -> Bool

(<=) :: Textarea -> Textarea -> Bool

(>) :: Textarea -> Textarea -> Bool

(>=) :: Textarea -> Textarea -> Bool

max :: Textarea -> Textarea -> Textarea

min :: Textarea -> Textarea -> Textarea

Read Textarea

Defined in Yesod.Form.Fields

Methods

readsPrec :: Int -> ReadS Textarea

readList :: ReadS [Textarea]

readPrec :: ReadPrec Textarea

readListPrec :: ReadPrec [Textarea]

Show Textarea

Defined in Yesod.Form.Fields

Methods

showsPrec :: Int -> Textarea -> ShowS

show :: Textarea -> String

showList :: [Textarea] -> ShowS

IsString Textarea

Defined in Yesod.Form.Fields

Methods

fromString :: String -> Textarea

ToJSON Textarea

Defined in Yesod.Form.Fields

Methods

toJSON :: Textarea -> Value

toEncoding :: Textarea -> Encoding

toJSONList :: [Textarea] -> Value

toEncodingList :: [Textarea] -> Encoding

FromJSON Textarea

Defined in Yesod.Form.Fields

Methods

parseJSON :: Value -> Parser Textarea

parseJSONList :: Value -> Parser [Textarea]

ToMarkup Textarea

Defined in Yesod.Form.Fields

Methods

toMarkup :: Textarea -> Markup

preEscapedToMarkup :: Textarea -> Markup

PersistFieldSql Textarea

Defined in Yesod.Form.Fields

Methods

sqlType :: Proxy Textarea -> SqlType

PersistField Textarea

Defined in Yesod.Form.Fields

Methods

toPersistValue :: Textarea -> PersistValue

fromPersistValue :: PersistValue -> Either Text Textarea

boolField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Bool

Creates a group of radio buttons to answer the question given in the message. Radio buttons are used to allow differentiating between an empty response (Nothing) and a no response (Just False). Consider using the simpler checkBoxField if you don't need to make this distinction.

If this field is optional, the first radio button is labeled "<None>", the second "Yes" and the third "No".

If this field is required, the first radio button is labeled "Yes" and the second "No".

(Exact label titles will depend on localization).

checkBoxField :: Monad m => Field m Bool

Creates an input with type="checkbox". While the default boolField implements a radio button so you can differentiate between an empty response (Nothing) and a no response (Just False), this simpler checkbox field returns an empty response as Just False.

Note that this makes the field always optional.

fileField :: Monad m => Field m FileInfo

Creates an input with type="file".

File AForms

fileAFormReq :: (MonadHandler m, RenderMessage (HandlerSite m) FormMessage) => FieldSettings (HandlerSite m) -> AForm m FileInfo

fileAFormOpt :: MonadHandler m => FieldSettings (HandlerSite m) -> AForm m (Maybe FileInfo)

Options

These functions create inputs where one or more options can be selected from a list.

The basic datastructure used is an Option, which combines a user-facing display value, the internal Haskell value being selected, and an external Text stored as the value in the form (used to map back to the internal value). A list of these, together with a function mapping from an external value back to a Haskell value, form an OptionList, which several of these functions take as an argument.

Typically, you won't need to create an OptionList directly and can instead make one with functions like optionsPairs or optionsEnum. Alternatively, you can use functions like selectFieldList, which use their [(msg, a)] parameter to create an OptionList themselves.

selectFieldHelper

Arguments

:: (Eq a, RenderMessage site FormMessage)

=> (Text -> Text -> [(Text, Text)] -> WidgetFor site () -> WidgetFor site ())

Outermost part of the field

-> (Text -> Text -> Bool -> WidgetFor site ())

An option for None if the field is optional

-> (Text -> Text -> [(Text, Text)] -> Text -> Bool -> Text -> WidgetFor site ())

Other options

-> HandlerFor site (OptionList a)

-> Field (HandlerFor site) a

A helper function for constucting selectFields. You may want to use this when you define your custom selectFields or radioFields.

Since: 1.6.2

selectField :: (Eq a, RenderMessage site FormMessage) => HandlerFor site (OptionList a) -> Field (HandlerFor site) a

Creates a <select> tag for selecting one option. Example usage:

areq (selectField $ optionsPairs [(MsgValue1, "value1"),(MsgValue2, "value2")]) "Which value?" Nothing

selectFieldList :: (Eq a, RenderMessage site FormMessage, RenderMessage site msg) => [(msg, a)] -> Field (HandlerFor site) a

Creates a <select> tag for selecting one option. Example usage:

areq (selectFieldList [("Value 1" :: Text, "value1"),("Value 2", "value2")]) "Which value?" Nothing

radioField :: (Eq a, RenderMessage site FormMessage) => HandlerFor site (OptionList a) -> Field (HandlerFor site) a

Creates an input with type="radio" for selecting one option.

radioFieldList :: (Eq a, RenderMessage site FormMessage, RenderMessage site msg) => [(msg, a)] -> Field (HandlerFor site) a

Creates an input with type="radio" for selecting one option.

checkboxesField :: Eq a => HandlerFor site (OptionList a) -> Field (HandlerFor site) [a]

Creates an input with type="checkbox" for selecting multiple options.

checkboxesFieldList :: (Eq a, RenderMessage site msg) => [(msg, a)] -> Field (HandlerFor site) [a]

Creates an input with type="checkbox" for selecting multiple options.

multiSelectField :: Eq a => HandlerFor site (OptionList a) -> Field (HandlerFor site) [a]

Creates a <select> tag for selecting multiple options.

multiSelectFieldList :: (Eq a, RenderMessage site msg) => [(msg, a)] -> Field (HandlerFor site) [a]

Creates a <select> tag for selecting multiple options.

data Option a

Constructors

Option

Fields

• optionDisplay :: Text

  The user-facing label.

• optionInternalValue :: a

  The Haskell value being selected.

• optionExternalValue :: Text

  The representation of this value stored in the form.

Instances

Functor Option

Since 1.4.6

Defined in Yesod.Form.Fields

Methods

fmap :: (a -> b) -> Option a -> Option b

(<$) :: a -> Option b -> Option a

data OptionList a

A structure holding a list of options. Typically you can use a convenience function like mkOptionList or optionsPairs instead of creating this directly.

Constructors

OptionList

Fields

• olOptions :: [Option a]
• olReadExternal :: Text -> Maybe a

  A function mapping from the form's value (optionExternalValue) to the selected Haskell value (optionInternalValue).

Instances

Functor OptionList

Since 1.4.6

Defined in Yesod.Form.Fields

Methods

fmap :: (a -> b) -> OptionList a -> OptionList b

(<$) :: a -> OptionList b -> OptionList a

mkOptionList :: [Option a] -> OptionList a

Creates an OptionList, using a Map to implement the olReadExternal function.

optionsPersist :: (YesodPersist site, PersistQueryRead backend, PathPiece (Key a), RenderMessage site msg, YesodPersistBackend site ~ backend, PersistRecordBackend a backend) => [Filter a] -> [SelectOpt a] -> (a -> msg) -> HandlerFor site (OptionList (Entity a))

Selects a list of Entitys with the given Filter and SelectOpts. The (a -> msg) function is then used to derive the display value for an OptionList. Example usage:

Country
   name Text
   deriving Eq -- Must derive Eq

data CountryForm = CountryForm
  { country :: Entity Country
  }

countryNameForm :: AForm Handler CountryForm
countryNameForm = CountryForm
        <$> areq (selectField countries) "Which country do you live in?" Nothing
        where
          countries = optionsPersist [] [Asc CountryName] countryName

optionsPersistKey :: (YesodPersist site, PersistQueryRead backend, PathPiece (Key a), RenderMessage site msg, backend ~ YesodPersistBackend site, PersistRecordBackend a backend) => [Filter a] -> [SelectOpt a] -> (a -> msg) -> HandlerFor site (OptionList (Key a))

An alternative to optionsPersist which returns just the Key instead of the entire Entity.

Since 1.3.2

optionsPairs :: (MonadHandler m, RenderMessage (HandlerSite m) msg) => [(msg, a)] -> m (OptionList a)

Creates an OptionList from a list of (display-value, internal value) pairs.

optionsEnum :: (MonadHandler m, Show a, Enum a, Bounded a) => m (OptionList a)

Creates an OptionList from an Enum, using its Show instance for the user-facing value.