@@ -68,11 +68,16 @@ import Web.Internal.HttpApiData
68-- >>> :set -XFlexibleContexts
68-- >>> :set -XFlexibleContexts
69-- >>> :set -XScopedTypeVariables
69-- >>> :set -XScopedTypeVariables
70-- >>> :set -XTypeFamilies
70-- >>> :set -XTypeFamilies
71−-- >>> import Data.Either (isLeft)
71+-- >>> import Data.Char (toLower)
72−-- >>> import Data.List (sort)
72+--
73-- >>> data Person = Person { name :: String, age :: Int } deriving (Show, Generic)
73-- >>> data Person = Person { name :: String, age :: Int } deriving (Show, Generic)
74-- >>> instance ToForm Person
74-- >>> instance ToForm Person
75-- >>> instance FromForm Person
75-- >>> instance FromForm Person
77+-- >>> data Project = Project { projectName :: String, projectSize :: Int } deriving (Generic, Show)
78+-- >>> myOptions = FormOptions { fieldLabelModifier = map toLower . drop (length ("project" :: String)) }
79+-- >>> instance ToForm Project where toForm = genericToForm myOptions
80+-- >>> instance FromForm Project where fromForm = genericFromForm myOptions
77-- | Typeclass for types that can be used as keys in a 'Form'-like container (like 'Map').
82-- | Typeclass for types that can be used as keys in a 'Form'-like container (like 'Map').
78class ToFormKey k where
83class ToFormKey k where
@@ -615,6 +620,31 @@ parseUnique :: FromHttpApiData v => Text -> Form -> Either Text v
615parseUnique key form = lookupUnique key form >>= parseQueryParam
620parseUnique key form = lookupUnique key form >>= parseQueryParam
617-- | 'Generic'-based deriving options for 'ToForm' and 'FromForm'.
622-- | 'Generic'-based deriving options for 'ToForm' and 'FromForm'.
624+-- A common use case for non-default 'FormOptions'
625+-- is to strip a prefix off of field labels:
628+-- data Project = Project
629+-- { projectName :: String
630+-- , projectSize :: Int
631+-- } deriving ('Generic', 'Show')
633+-- myOptions :: 'FormOptions'
634+-- myOptions = 'FormOptions'
635+-- { 'fieldLabelModifier' = 'map' 'toLower' . 'drop' ('length' \"project\") }
637+-- instance 'ToForm' Project where
638+-- 'toForm' = 'genericToForm' myOptions
640+-- instance 'FromForm' Project where
641+-- 'fromForm' = 'genericFromForm' myOptions
644+-- >>> urlEncodeAsForm Project { projectName = "http-api-data", projectSize = 172 }
645+-- "size=172&name=http-api-data"
646+-- >>> urlDecodeAsForm "name=http-api-data&size=172" :: Either Text Project
647+-- Right (Project {projectName = "http-api-data", projectSize = 172})
618data FormOptions = FormOptions
648data FormOptions = FormOptions
619 { -- | Function applied to field labels. Handy for removing common record prefixes for example.
649 { -- | Function applied to field labels. Handy for removing common record prefixes for example.
620 fieldLabelModifier :: String -> String
650 fieldLabelModifier :: String -> String