Copyright | (c) digitally induced GmbH 2020 |
---|---|
Safe Haskell | None |
IHP.View.Form
Contents
Description
Synopsis
- formFor :: forall record parent id application. (?context :: ControllerContext, Eq record, Typeable record, ModelFormAction application record, HasField "id" record id, HasField "meta" record MetaBag, Default id, Eq id) => record -> ((?context :: ControllerContext, ?formContext :: FormContext record) => Html) -> Html
- formFor' :: forall record parent id application. (?context :: ControllerContext, Eq record, Typeable record, HasField "id" record id, HasField "meta" record MetaBag, Default id, Eq id) => record -> Text -> ((?context :: ControllerContext, ?formContext :: FormContext record) => Html) -> Html
- createFormContext :: forall record viewContext parent id application. (?context :: ControllerContext, Eq record, Typeable record, HasField "id" record id, HasField "meta" record MetaBag) => record -> FormContext record
- buildForm :: forall model parent id. (?context :: ControllerContext, HasField "id" model id, Default id, Eq id) => FormContext model -> ((?context :: ControllerContext, ?formContext :: FormContext model) => Html) -> Html
- submitButton :: forall model id. (?formContext :: FormContext model, HasField "id" model id, KnownSymbol (GetModelName model), Eq id, Default id) => SubmitButton
- textField :: forall fieldName model value. (?formContext :: FormContext model, HasField fieldName model value, HasField "meta" model MetaBag, KnownSymbol fieldName, InputValue value, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField
- numberField :: forall fieldName model value. (?formContext :: FormContext model, HasField fieldName model value, HasField "meta" model MetaBag, KnownSymbol fieldName, InputValue value, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField
- textareaField :: forall fieldName model value. (?formContext :: FormContext model, HasField fieldName model value, HasField "meta" model MetaBag, KnownSymbol fieldName, InputValue value, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField
- colorField :: forall fieldName model value. (?formContext :: FormContext model, HasField fieldName model value, HasField "meta" model MetaBag, KnownSymbol fieldName, InputValue value, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField
- emailField :: forall fieldName model. (?formContext :: FormContext model, HasField fieldName model Text, HasField "meta" model MetaBag, KnownSymbol fieldName, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField
- dateField :: forall fieldName model value. (?formContext :: FormContext model, HasField fieldName model value, HasField "meta" model MetaBag, KnownSymbol fieldName, InputValue value, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField
- passwordField :: forall fieldName model. (?formContext :: FormContext model, HasField fieldName model Text, HasField "meta" model MetaBag, KnownSymbol fieldName, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField
- dateTimeField :: forall fieldName model value. (?formContext :: FormContext model, HasField fieldName model value, HasField "meta" model MetaBag, KnownSymbol fieldName, InputValue value, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField
- hiddenField :: forall fieldName model value. (?formContext :: FormContext model, HasField fieldName model value, HasField "meta" model MetaBag, KnownSymbol fieldName, InputValue value, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField
- checkboxField :: forall fieldName model. (?formContext :: FormContext model, HasField fieldName model Bool, HasField "meta" model MetaBag, KnownSymbol fieldName, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField
- selectField :: forall fieldName model item. (?formContext :: FormContext model, HasField fieldName model (SelectValue item), HasField "meta" model MetaBag, KnownSymbol fieldName, KnownSymbol (GetModelName model), CanSelect item, InputValue (SelectValue item)) => Proxy fieldName -> [item] -> FormField
- class CanSelect model where
- type SelectValue model :: Type
- selectLabel :: model -> Text
- selectValue :: model -> SelectValue model
- class ModelFormAction application record where
- modelFormAction :: (?context :: ControllerContext) => record -> Text
- fieldNameToFieldLabel :: Text -> Text
- columnNameToFieldLabel :: Text -> Text
- removeIdSuffix :: Text -> Text
Documentation
formFor :: forall record parent id application. (?context :: ControllerContext, Eq record, Typeable record, ModelFormAction application record, HasField "id" record id, HasField "meta" record MetaBag, Default id, Eq id) => record -> ((?context :: ControllerContext, ?formContext :: FormContext record) => Html) -> Html Source #
Forms usually begin with a formFor
expression.
This is how a simple form can look like:
renderForm :: Post -> Html renderForm post = formFor post [hsx| {textField #title} {textareaField #body} {submitButton} |]
Calling this form from inside your HSX code will lead to the following HTML being generated:
<form method="POST" action="/CreatePost" id="" class="new-form"> <div class="form-group" id="form-group-post_title"> <label for="post_title">Title</label> <input type="text" name="title" id="post_title" class="form-control" /> </div> <div class="form-group" id="form-group-post_body"> <label for="post_body">Body</label> <textarea name="body" id="post_body" class="form-control"></textarea> </div> <button class="btn btn-primary">Create Post</button> </form>
You can see that the form is submitted via POST
. The form action has also been set by default to /CreatePost
.
All inputs have auto-generated class names and ids for styling. Also, all name
attributes are set as expected.
Field Values:
A form control is always filled with the value of the given field when rendering. For example, given a post
let post = Post { ..., title = "Hello World" }
Rendering this, the input value will be set like:
>>>
{textField #title}
<input ... value="Hello World" />
Validation:
When rendering a record that has failed validation, the validation error message will be rendered automatically.
Given a post like this:
let post = Post { ..., title = "" } |> validateField #title nonEmpty
Rendering {textField #title}
, the input will have the css class is-invalid
and an element with the error message will be rendered below the input:
<div class="form-group" id="form-group-post_title"> <label for="post_title">Title</label> <input type="text" name="title" placeholder="" id="post_title" class="form-control is-invalid " /> <div class="invalid-feedback">This field cannot be empty</div> </div>
formFor' :: forall record parent id application. (?context :: ControllerContext, Eq record, Typeable record, HasField "id" record id, HasField "meta" record MetaBag, Default id, Eq id) => record -> Text -> ((?context :: ControllerContext, ?formContext :: FormContext record) => Html) -> Html Source #
Allows a custom form action (form submission url) to be set
The URL where the form is going to be submitted to is specified in HTML using the form's action
attribute. When using formFor
the action
attribute is automatically set to the expected path.
E.g. given the below formFor
code, the action
is set to /CreatePost
or /UpdatePost
:
renderForm :: Post -> Html renderForm post = formFor post [hsx| {textField #title} {textareaField #body} {submitButton} |]
To override the auto-generated action
attribute use the 'formFor'' function:
renderForm :: Post -> Html renderForm post = formFor' post "/my-custom-endpoint" [hsx||]
If you pass an action to that, you need to wrap it with pathTo
:
renderForm :: Post -> Html renderForm post = formFor' post (pathTo CreateDraftAction) [hsx||]
createFormContext :: forall record viewContext parent id application. (?context :: ControllerContext, Eq record, Typeable record, HasField "id" record id, HasField "meta" record MetaBag) => record -> FormContext record Source #
Used by formFor
to make a new form context
buildForm :: forall model parent id. (?context :: ControllerContext, HasField "id" model id, Default id, Eq id) => FormContext model -> ((?context :: ControllerContext, ?formContext :: FormContext model) => Html) -> Html Source #
Used by formFor
to render the form
submitButton :: forall model id. (?formContext :: FormContext model, HasField "id" model id, KnownSymbol (GetModelName model), Eq id, Default id) => SubmitButton Source #
Renders a submit button
<button class="btn btn-primary">Create Post</button>
Example:
renderForm :: Post -> Html renderForm post = formFor post [hsx| {submitButton} |]
This will generate code like this:
<form method="POST" action="/CreatePost" id="" class="new-form"> <button class="btn btn-primary">Create Post</button> </form>
Custom Text
renderForm :: Post -> Html renderForm post = formFor post [hsx| {submitButton { label = "Create it!" } } |]
This will generate code like this:
<form method="POST" action="/CreatePost" id="" class="new-form"> <button class="btn btn-primary">Create it!</button> </form>
Custom Class
renderForm :: Post -> Html renderForm post = formFor post [hsx| {submitButton { buttonClass = "create-button" } } |]
This will generate code like this:
<form method="POST" action="/CreatePost" id="" class="new-form"> <button class="btn btn-primary create-button">Create Post</button> </form>
textField :: forall fieldName model value. (?formContext :: FormContext model, HasField fieldName model value, HasField "meta" model MetaBag, KnownSymbol fieldName, InputValue value, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField Source #
Renders a text input field
>>>
{textField #title}
<div class="form-group" id="form-group-post_title"> <label for="post_title">Title</label> <input type="text" name="title" id="post_title" class="form-control" /> </div>
Example:
renderForm :: Post -> Html renderForm post = formFor post [hsx| {textField #title} |]
This will generate code like this:
<form method="POST" action="/CreatePost" id="" class="new-form"> <div class="form-group" id="form-group-post_title"> <label for="post_title">Title</label> <input type="text" name="title" id="post_title" class="form-control" /> </div> </form>
Help Texts:
You can add a help text below a form control like this:
{(textField #title) { helpText = "Max. 140 characters"} }
This will generate code like this:
<div class="form-group" id="form-group-post_title"> <label for="post_title">Title</label> <input type="text" name="title" id="post_title" class="form-control" /> <small class="form-text text-muted">Max. 140 characters</small> </div>
Custom Field Label Text:
By default, the field name will be used as a label text. The camel case field name will be made more human-readable of course, so contactName
will turn to Contact Name
, etc. Sometimes you want to change this auto-generated input label to something custom. Use fieldLabel
for that, like this:
{(textField #title) { fieldLabel = "Post Title"} }
This will generate code like this:
<div class="form-group" id="form-group-post_title"> <label for="post_title">Post Title</label> <input type="text" name="title" id="post_title" class="form-control" /> </div>
Custom CSS Classes:
You can add custom CSS classes to the input and label for better styling. Set fieldClass
for adding a class to the input element and labelClass
for the label element:
{(textField #title) { fieldClass="title-input", labelClass = "title-label" } }
This will generate code like this:
<div class="form-group" id="form-group-post_title"> <label class="title-label" for="post_title">Title</label> <input type="text" name="title" id="post_title" class="form-control title-input" /> </div>
Of course, the CSS classes for validation are still set as expected.
Placeholder:
{(textField #title) { placeholder = "Enter your title ..." } }
This will generate code like this:
<div class="form-group" id="form-group-post_title"> <label for="post_title">Title</label> <input type="text" name="title" id="post_title" placeholder="Enter your title ..." class="form-control" /> </div>
Required Fields:
You can mark an input as required like this:
{(textField #title) { required = True } }
This will generate code like this:
<div class="form-group" id="form-group-post_title"> <label for="post_title">Title</label> <input type="text" name="title" id="post_title" required="required" class="form-control" /> </div>
Autofocus:
You can mark an input with autofocus, to ensure it will be given the input focus on page load, like this:
{(textField #title) { autofocus = True } }
This will generate code like this:
<div class="form-group" id="form-group-post_title"> <label for="post_title">Title</label> <input type="text" name="title" id="post_title" autofocus="autofocus" class="form-control" /> </div>
numberField :: forall fieldName model value. (?formContext :: FormContext model, HasField fieldName model value, HasField "meta" model MetaBag, KnownSymbol fieldName, InputValue value, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField Source #
Renders a number input field
>>>
{numberField #maxUsers}
<div class="form-group" id="form-group-company_max_users"> <label for="company_max_users">Max Users</label> <input type="number" name="maxUsers" id="company_maxUsers" class="form-control" /> </div>
See textField
for examples of possible form control options.
textareaField :: forall fieldName model value. (?formContext :: FormContext model, HasField fieldName model value, HasField "meta" model MetaBag, KnownSymbol fieldName, InputValue value, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField Source #
Renders a textarea
>>>
{textareaField #body}
<div class="form-group" id="form-group-post_body"> <label for="post_body">Body</label> <textarea name="body" id="post_body" class="form-control" /> </div>
See textField
for examples of possible form control options.
colorField :: forall fieldName model value. (?formContext :: FormContext model, HasField fieldName model value, HasField "meta" model MetaBag, KnownSymbol fieldName, InputValue value, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField Source #
Renders a color field
>>>
{colorField #color}
<div class="form-group" id="form-group-post_color"> <label for="post_color">Color</label> <input type="color" name="color" id="post_color" class="form-control" /> </div>
See textField
for examples of possible form control options.
emailField :: forall fieldName model. (?formContext :: FormContext model, HasField fieldName model Text, HasField "meta" model MetaBag, KnownSymbol fieldName, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField Source #
Renders an email field
>>>
{emailField #email}
<div class="form-group" id="form-group-user_email"> <label for="user_email">Email</label> <input type="email" name="email" id="user_email" class="form-control" /> </div>
See textField
for examples of possible form control options.
dateField :: forall fieldName model value. (?formContext :: FormContext model, HasField fieldName model value, HasField "meta" model MetaBag, KnownSymbol fieldName, InputValue value, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField Source #
Renders an date field
>>>
{dateField #createdAt}
<div class="form-group" id="form-group-user_created_at"> <label for="user_createdAt">Created At</label> <input type="date" name="createdAt" id="user_createdAt" class="form-control" /> </div>
See textField
for examples of possible form control options.
passwordField :: forall fieldName model. (?formContext :: FormContext model, HasField fieldName model Text, HasField "meta" model MetaBag, KnownSymbol fieldName, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField Source #
Renders an password field
>>>
{passwordField #password}
<div class="form-group" id="form-group-user_password"> <label for="user_password">Password</label> <input type="password" name="password" id="user_password" class="form-control" /> </div>
See textField
for examples of possible form control options.
dateTimeField :: forall fieldName model value. (?formContext :: FormContext model, HasField fieldName model value, HasField "meta" model MetaBag, KnownSymbol fieldName, InputValue value, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField Source #
Renders an date-time field
>>>
{dateTimeField #createdAt}
<div class="form-group" id="form-group-user_created_at"> <label for="user_createdAt">Created At</label> <input type="datetime-local" name="createdAt" id="user_createdAt" class="form-control" /> </div>
See textField
for examples of possible form control options.
forall fieldName model value. (?formContext :: FormContext model, HasField fieldName model value, HasField "meta" model MetaBag, KnownSymbol fieldName, InputValue value, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField Source #
::Renders an hidden field
>>>
{hiddenField #projectId}
<input type="hidden" name="projectId" id="checkoutSession_projectId" class="form-control" />
The hidden field is by default rendered without a form group and without a label.
checkboxField :: forall fieldName model. (?formContext :: FormContext model, HasField fieldName model Bool, HasField "meta" model MetaBag, KnownSymbol fieldName, KnownSymbol (GetModelName model)) => Proxy fieldName -> FormField Source #
Renders a checkbox field
>>>
{checkboxField #active}
<div class="form-group" id="form-group-user_active"> <label for="user_active">Active</label> <input type="checkbox" name="active" id="user_active" class="form-control" /> </div>
See textField
for examples of possible form control options.
selectField :: forall fieldName model item. (?formContext :: FormContext model, HasField fieldName model (SelectValue item), HasField "meta" model MetaBag, KnownSymbol fieldName, KnownSymbol (GetModelName model), CanSelect item, InputValue (SelectValue item)) => Proxy fieldName -> [item] -> FormField Source #
Select inputs require you to pass a list of possible values to select.
formFor project [hsx| {selectField #userId users} |]
In the example above the variable users contains all the possible option values for the select.
You also need to define a instance CanSelect User
:
instance CanSelect User where -- Here we specify that the <option> value should contain a `Id User` type SelectValue User = Id User -- Here we specify how to transform the model into <option>-value selectValue = get #id -- And here we specify the <option>-text selectLabel = get #name
Given the above example, the rendered form will look like this:
<!-- Assuming: users = [User { id = 1, name = "Marc" }, User { id = 2, name = "Andreas" }] --> <form ...> <select name="user_id"> <option value="1">Marc</option> <option value="2">Andreas</option> </select> </form>
If you want a certain value to be preselected, set the value in the controller. For example, to have the first user be preselected in the above example:
action NewProjectAction = do users <- query @User |> fetch let userId = headMay users |> maybe def (get #id) let target = newRecord @Project |> set #userId userId render NewView { .. }
class CanSelect model where Source #
Minimal complete definition
Nothing
Associated Types
type SelectValue model :: Type Source #
Here we specify the type of the option
value, usually an Id model
Methods
selectLabel :: model -> Text Source #
Here we specify the option-text
default selectLabel :: Show model => model -> Text Source #
selectValue :: model -> SelectValue model Source #
Here we specify how to transform the model into option
-value
default selectValue :: HasField "id" model (SelectValue model) => model -> SelectValue model Source #
class ModelFormAction application record where Source #
Returns the form's action attribute for a given record.
Methods
modelFormAction :: (?context :: ControllerContext) => record -> Text Source #
Instances
(HasField "id" record id, Eq id, Default id, KnownSymbol (GetModelName record), Show id) => ModelFormAction application record Source # | |
Defined in IHP.View.Form Methods modelFormAction :: record -> Text Source # |
fieldNameToFieldLabel :: Text -> Text Source #
Transform a data-field name like userName
to a friendly human-readable name like User name
columnNameToFieldLabel :: Text -> Text Source #
Transform a column name like user_name
to a friendly human-readable name like User name
removeIdSuffix :: Text -> Text Source #
Removes Id
from a string
>>>
removeIdSuffix "User Id"
"User"
When the string does not end with Id
, it will just return the input string:
>>>
removeIdSuffix "Project"
"Project"