yesod-form-1.4.12: Form handling support for Yesod Web Framework

Safe Haskell | None
Language | Haskell98

Yesod.Form.Fields

Contents

- i18n
- Fields
- File `AForm`s
- Options

Description

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.

Synopsis

- data FormMessage
  - = 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
- defaultFormMessage :: FormMessage -> Text
- textField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Text
- passwordField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Text
- textareaField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Textarea
- hiddenField :: (Monad m, PathPiece p, RenderMessage (HandlerSite m) FormMessage) => Field m p
- intField :: (Monad m, Integral i, RenderMessage (HandlerSite m) FormMessage) => Field m i
- dayField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Day
- timeField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m TimeOfDay
- timeFieldTypeTime :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m TimeOfDay
- timeFieldTypeText :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m TimeOfDay
- htmlField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Html
- emailField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Text
- multiEmailField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m [Text]
- searchField :: Monad m => RenderMessage (HandlerSite m) FormMessage => AutoFocus -> Field m Text
- type AutoFocus = Bool
- urlField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Text
- doubleField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Double
- parseDate :: String -> Either FormMessage Day
- parseTime :: Text -> Either FormMessage TimeOfDay
- newtype Textarea = Textarea {
  - unTextarea :: Text
  }
- boolField :: Monad m => RenderMessage (HandlerSite m) FormMessage => Field m Bool
- checkBoxField :: Monad m => Field m Bool
- fileField :: Monad m => Field m FileInfo
- fileAFormReq :: (MonadHandler m, RenderMessage (HandlerSite m) FormMessage) => FieldSettings (HandlerSite m) -> AForm m FileInfo
- fileAFormOpt :: MonadHandler m => FieldSettings (HandlerSite m) -> AForm m (Maybe FileInfo)
- selectField :: (Eq a, RenderMessage site FormMessage) => HandlerT site IO (OptionList a) -> Field (HandlerT site IO) a
- selectFieldList :: (Eq a, RenderMessage site FormMessage, RenderMessage site msg) => [(msg, a)] -> Field (HandlerT site IO) a
- radioField :: (Eq a, RenderMessage site FormMessage) => HandlerT site IO (OptionList a) -> Field (HandlerT site IO) a
- radioFieldList :: (Eq a, RenderMessage site FormMessage, RenderMessage site msg) => [(msg, a)] -> Field (HandlerT site IO) a
- checkboxesField :: Eq a => HandlerT site IO (OptionList a) -> Field (HandlerT site IO) [a]
- checkboxesFieldList :: (Eq a, RenderMessage site msg) => [(msg, a)] -> Field (HandlerT site IO) [a]
- multiSelectField :: Eq a => HandlerT site IO (OptionList a) -> Field (HandlerT site IO) [a]
- multiSelectFieldList :: (Eq a, RenderMessage site msg) => [(msg, a)] -> Field (HandlerT site IO) [a]
- data Option a = Option {
  - optionDisplay :: Text
  - optionInternalValue :: a
  - optionExternalValue :: Text
  }
- data OptionList a = OptionList {
  - olOptions :: [Option a]
  - olReadExternal :: Text -> Maybe a
  }
- mkOptionList :: [Option a] -> OptionList a
- optionsPersist :: (YesodPersist site, PersistQueryRead backend, PathPiece (Key a), RenderMessage site msg, YesodPersistBackend site ~ backend, PersistRecordBackend a backend) => [Filter a] -> [SelectOpt a] -> (a -> msg) -> HandlerT site IO (OptionList (Entity a))
- optionsPersistKey :: (YesodPersist site, PersistQueryRead backend, PathPiece (Key a), RenderMessage site msg, backend ~ YesodPersistBackend site, PersistRecordBackend a backend) => [Filter a] -> [SelectOpt a] -> (a -> msg) -> HandlerT site IO (OptionList (Key a))
- optionsPairs :: (MonadHandler m, RenderMessage (HandlerSite m) msg) => [(msg, a)] -> m (OptionList a)
- optionsEnum :: (MonadHandler m, Show a, Enum a, Bounded a) => m (OptionList a)

# 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 # |
Methods (==) :: FormMessage -> FormMessage -> Bool # (/=) :: FormMessage -> FormMessage -> Bool #
Read FormMessage # |
Methods readsPrec :: Int -> ReadS FormMessage # readList :: ReadS [FormMessage] # readPrec :: ReadPrec FormMessage # readListPrec :: ReadPrec [FormMessage] #
Show FormMessage # |
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 #

Deprecated: `timeField` currently defaults to an input of type="text". In the next major release, it will default to type="time". To opt in to the new functionality, use `timeFieldTypeTime`. To keep the existing behavior, use `timeFieldTypeText`. See 'https://github.com/yesodweb/yesod/pull/874' for details.

An alias for `timeFieldTypeText`.

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

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 # |
Methods (==) :: Textarea -> Textarea -> Bool # (/=) :: Textarea -> Textarea -> Bool #
Ord Textarea # |
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 # |
Methods readsPrec :: Int -> ReadS Textarea # readList :: ReadS [Textarea] # readPrec :: ReadPrec Textarea # readListPrec :: ReadPrec [Textarea] #
Show Textarea # |
Methods showsPrec :: Int -> Textarea -> ShowS # show :: Textarea -> String # showList :: [Textarea] -> ShowS #
FromJSON Textarea # |
Methods parseJSON :: Value -> Parser Textarea # parseJSONList :: Value -> Parser [Textarea] #
ToJSON Textarea # |
Methods toJSON :: Textarea -> Value # toEncoding :: Textarea -> Encoding # toJSONList :: [Textarea] -> Value # toEncodingList :: [Textarea] -> Encoding #
ToMarkup Textarea # |
Methods toMarkup :: Textarea -> Markup # preEscapedToMarkup :: Textarea -> Markup #
PersistFieldSql Textarea # |
Methods sqlType :: Proxy * Textarea -> SqlType #
PersistField Textarea # |
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 `AForm`s

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.

selectField :: (Eq a, RenderMessage site FormMessage) => HandlerT site IO (OptionList a) -> Field (HandlerT site IO) 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 (HandlerT site IO) 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) => HandlerT site IO (OptionList a) -> Field (HandlerT site IO) a #

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

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

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

checkboxesField :: Eq a => HandlerT site IO (OptionList a) -> Field (HandlerT site IO) [a] #

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

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

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

multiSelectField :: Eq a => HandlerT site IO (OptionList a) -> Field (HandlerT site IO) [a] #

Creates a `<select>` tag for selecting multiple options.

multiSelectFieldList :: (Eq a, RenderMessage site msg) => [(msg, a)] -> Field (HandlerT site IO) [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
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
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) -> HandlerT site IO (OptionList (Entity a)) #

Selects a list of `Entity`s with the given `Filter` and `SelectOpt`s. 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) -> HandlerT site IO (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.