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>

Like formFor but allows changing the underlying FormContext

This is how you can render a form with a id="post-form" id attribute and a custom data-post-id attribute:

renderForm :: Post -> Html
renderForm post = formForWithOptions formOptions post [hsx|
    {textField #title}
    {textareaField #body}
    {submitButton}
|]

formOptions :: FormContext Post -> FormContext Post
formOptions formContext = formContext
    |> set #formId "post-form"
    |> set #customFormAttributes [("data-post-id", show formContext.model.id)]

Like formFor but disables the IHP javascript helpers.

Use it like this:

renderForm :: Post -> Html
renderForm post = formForWithoutJavascript post [hsx|
    {textField #title}
    {textareaField #body}
    {submitButton}
|]

If you want to use this with e.g. a custom form action, remember that formForWithoutJavascript is just a shortcut for formForWithOptions:

renderForm :: Post -> Html
renderForm post = formForWithOptions formOptions post [hsx|
    {textField #title}
    {textareaField #body}
    {submitButton}
|]

formOptions :: FormContext Post -> FormContext Post
formOptions formContext = formContext
    |> set #formAction (pathTo BespokeNewPostAction)
    |> set #disableJavascriptSubmission True

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||]

Used by formFor to make a new form context

Used by formFor to render the form

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>

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>

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.

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.

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.

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.

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.

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.

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.

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.

Renders an file field

>>> {fileField #profilePicture}
<input type="file" name="profilePicture" id="user_profilePicture" class="form-control" />

See textField for examples of possible form control options.

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.

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 user = user.id
    -- And here we specify the <option>-text
    selectLabel user = user.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 (.id)
    let target = newRecord @Project |> set #userId userId
    render NewView { .. }

Radio require you to pass a list of possible values to select. We use the same mechanism as for for selectField.

formFor project [hsx|
    {radioField #userId users}
|]

In the example above the variable users contains all the possible option values for the radios.

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 user = user.id
    -- And here we specify the <option>-text
    selectLabel user = user.name

Given the above example, the rendered form will look like this (omitting classes for brevity):

<!-- Assuming: users = [User { id = 1, name = "Marc" }, User { id = 2, name = "Andreas" }] -->
<form ...>
    <fieldset>
        <div>
          <input type="radio" id="option1" value="1"/>
          <label for="option1">Marc</label>
        </div>
        <div>
          <input type="radio" id="option2" value="2"/>
          <label for="option2">Andreas</label>
        </div>
    </fieldset>
</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 (.id)
    let target = newRecord @Project |> set #userId userId
    render NewView { .. }

Returns the form's action attribute for a given record.

Renders a validation failure for a field. If the field passed all validation, no error is shown.

>>> {validationResult #email}
<div class="invalid-feedback">is not a valid email</div>

Returns the validation failure for a field. If the field passed all validation, this returns Nothing.

>>> {validationResultMaybe #email}
Just "is not a valid email"