Discourse toolkit to render forms

[system]

Basic Usage

FormKit exposes a single component as its public API: <Form />. All other elements are yielded as contextual components, modifiers, or plain data.

Every form is composed of one or multiple fields, representing the value, validation, and metadata of a control. Each field encapsulates a control, which is the form element the user interacts with to enter data, such as an input or select. Other utilities, like submit or alert, are also provided.

Here is the most basic example of a form:

import Component from "@glimmer/component";
import { action } from "@ember/object";
import Form from "discourse/components/form";

export default class MyForm extends Component {
  @action
  handleSubmit(data) {
    // do something with data
  }

  <template>
    <Form @onSubmit={{this.handleSubmit}} as |form|>
      <form.Field
        @name="username"
        @title="Username"
        @validation="required"
        as |field|
      >
        <field.Input />
      </form.Field>

      <form.Field @name="age" @title="Age" as |field|>
        <field.Input @type="number" />
      </form.Field>

      <form.Submit />
    </Form>
  </template>
}

Form

Yielded Parameters

form

The Form component yields a form object containing components and helpers.

Example

<Form as |form|>
  <form.Row as |row|>
    <!-- ... -->
  </form.Row>
</Form>

transientData

transientData represents the state of the data at a given time as it’s represented in the form, and not yet propagated to @data.

This is useful if you want to have conditionals in your form based on other fields.

Example

<Form as |form transientData|>
  <form.Field @name="amount" as |field|>
    <field.Input @type="number" />
  </form.Field>

  {{#if (gt transientData.amount 200)}}
    <form.Field @name="confirmed" as |field|>
      <field.Checkbox>I know what I'm doing</field.Checkbox>
    </form.Field>
  {{/if}}
</Form>

Properties

@data

Initial state of the data you give to the form.

The keys matching the @names of the form’s fields will be prepopulated.

@data is treated as an immutable object, following Ember’s DDAU pattern. This means when the user enters new data for any of the fields, it will not cause a mutation of @data! You can mutate your initial object using @onSet.

When working with an object object we recommend to setup your form data object like this:

@cached
get formData() {
  return getProperties(this.model, "foo", "bar", "baz");
}

Parameter

• data (Object): The data object passed to the template.

Example

<Form @data={{hash foo="bar"}} as |form|>
  <form.Field @name="foo" as |field|>
    <!-- This input will have "bar" as its initial value -->
    <field.Input />
  </form.Field>
</Form>

@onRegisterApi

Callback called when the form is inserted. It allows the developer to interact with the form through JavaScript.

Parameters

• callback (Object): The object containing callback functions.
  • callback.submit (Function): Function to submit the form.
  • callback.reset (Function): Function to reset the form.
  • callback.set (Function): Function to set a key/value on the form data object.
  • callback.setProperties (Function): Function to set an object on the form data object.
  • callback.isDirty (boolean): Tracked property return the state of the form. It will be true once changes have been done on the form. Resetting the changes will bring it back to false.

Example

registerAPI({ submit, reset, set }) {
  // Interact with the form API
  submit();
  reset();
  set("foo", 1);
}

<Form @onRegisterApi={{this.registerAPI}} />

@onSubmit

Callback called when the form is submitted and valid.

Parameters

• data (Object): The object containing the form data.

Example

handleSubmit({ username, age }) {
  console.log(username, age);
}

<Form @onSubmit={{this.handleSubmit}} as |form|>
  <form.Field @name="username" as |field|>
    <field.Input />
  </form.Field>
  <form.Field @name="age" as |field|>
    <field.Input @type="number" />
  </form.Field>
  <form.Submit />
</Form>

@validate

A custom validation callback added directly to the form.

Example

@action
myValidation(data, { addError }) {
  if (data.foo !== data.bar) {
    addError("foo", { title: "Foo", message: "Bar must be equal to Foo" });
  }
}

<Form @validate={{this.myValidation}} />

An asynchronous example:

@action
async myValidation(data, { addError }) {
  try {
    await ajax("/check-username", {
      type: "POST",
      data: { username: data.username }
    });
  } catch(e) {
    addError("username", { title: "Username", message: "Already taken!" });
  }
}

Field

@name

A field must have a unique name. This name is used to set the value on the data object and is also used for validation.

Example

<form.Field @name="foo" />

@title

A field must have a title. It will be displayed above the control and is also used in validation.

Example

<form.Field @title="Foo" />

@description

The description is optional and will be shown under the title when set.

Example

<form.Field @description="Bar" />

@helpText

The help text is optional and will be shown under the field when set.

Example

<form.Field @helpText="Baz" />

@showTitle

By default, the title will be shown on top of the control. You can choose not to render it by setting this property to false.

Example

<form.Field @showTitle={{false}} />

@disabled

A field can be disabled to prevent any changes to it.

Example

<form.Field @disabled={{true}} />

@tooltip

Allows to display a tooltip next to the field’s title. Won’t display if title is not shown.
You can pass a string or a <DTooltip /> component.

Example

<Form as |form|>
  <form.Field @name="foo" @title="Foo" @tooltip="a nice input" as |field|>
    <field.Input />
  </form.Field>
</Form>

<Form as |form|>
  <form.Field
    @name="foo"
    @title="Foo"
    @tooltip={{component DTooltip content="a nice input"}}
    as |field|
  >
    <field.Input />
  </form.Field>
</Form>

@validation

Read the dedicated validation section.

@validate

Read the dedicated custom validation section.

@onSet

By default, when changing the value of a field, this value will be set on the form’s internal data object. However, you can choose to have full control over this process for a field.

Example

@action
handleFooChange(value, { set }) {
  set("foo", value + "-bar");
}

<form.Field @name="foo" @onSet={{this.handleFooChange}} as |field|>
  <field.Input />
</form.Field>

You can use @onSet to also mutate the initial data object if you need more reactivity for a specific case.

Example

@action
handleFooChange(value, { set }) {
  set("foo", value + "-bar");
  this.model.foo = value + "-bar";
}

<Form @data={{this.model}} as |form|>
  <form.Field @name="foo" @onSet={{this.handleFooChange}} as |field|>
    <field.Input />
  </form.Field>
</Form>

Controls

Controls, as we use the term here, refer to the UI widgets that allow a user to enter data. In its most basic form, this would be an input.

You can pass down HTML attributes to the underlying control.

Example

<Form as |form|>
  <form.Field
    @name="query"
    @title="Query"
    @description="You should make sure the query doesn’t include bots."
    as |field|
  >
    <field.Input placeholder="Foo" />
  </form.Field>
</Form>

@format

Controls accept a @format property which can be: small, medium, large, or full.

Form Kit sets defaults for each control, but you can override them using @format:

• small: 100px
• medium: 220px
• large: 400px
• full: 100%

Additionally, the following CSS variables are provided to customize these defaults:

• small: --form-kit-small-input
• medium: --form-kit-medium-input
• large: --form-kit-large-input

@titleFormat

Allows to override @format for the title. See @format for details.

@descriptionFormat

Allows to override @format for the description. See @format for details.

Checkbox

Renders an <input type="checkbox"> element.

When to use a single checkbox
There are only 2 options: yes/no. It feels like agreeing to something. Checking the box doesn’t save; there is a submit button further down.

Example

<Form as |form|>
  <form.Field @name="approved" @title="Approved" as |field|>
    <field.Checkbox />
  </form.Field>
</Form>

Code

Renders an <AceEditor /> component.

@height

Sets the height of the editor.

@lang

Sets the language of the editor.

Example

<Form as |form|>
  <form.Field @name="query" @title="Query" as |field|>
    <field.Code @lang="sql" @height={{400}} />
  </form.Field>
</Form>

Calendar

Renders a datepicker and a time input. On mobile the datepicker will be replaced by a date input.

@includeTime

Displays the time input or not. Defaults to true.

Example

<Form as |form|>
  <form.Field @name="start" @title="Start" as |field|>
    <field.Calendar @includeTime={{false}} />
  </form.Field>
</Form>

@expandedDatePickerOnDesktop

Displays date picker expanded on desktop. Defaults to true.

Example

<Form as |form|>
  <form.Field @name="start" @title="Start" as |field|>
    <field.Calendar @expandedDatePickerOnDesktop={{false}} />
  </form.Field>
</Form>

Composer

Renders a <DEditor /> component.

@height

Sets the height of the composer.

Example

<Form as |form|>
  <form.Field @name="message" @title="Message" as |field|>
    <field.Composer @height={{400}} />
  </form.Field>
</Form>

@preview

Controls the display the composer preview. Defaults to false.

Example

<Form as |form|>
  <form.Field @name="message" @title="Message" as |field|>
    <field.Composer @preview={{true}} />
  </form.Field>
</Form>

Icon

Renders an <IconPicker /> component.

Example

<Form as |form|>
  <form.Field @name="icon" @title="Icon" as |field|>
    <field.Icon />
  </form.Field>
</Form>

Image

Renders an <UppyImageUploader /> component.

Upload Handling

By default, the component will set an upload object. It’s common to only want the URL and the ID of the upload. To achieve this, you can use the @onSet property on the field:

@action
handleUpload(upload, { set }) {
  set("upload_id", upload.id);
  set("upload_url", getURL(upload.url));
}

<Form as |form|>
  <form.Field
    @name="upload"
    @title="Upload"
    @onSet={{this.handleUpload}}
    as |field|
  >
    <field.Image />
  </form.Field>
</Form>

Example

<Form as |form|>
  <form.Field @name="upload" @title="Upload" as |field|>
    <field.Image />
  </form.Field>
</Form>

Input

Renders an <input> element.

@type

Optional property which will default to text. Maps to <input> types.

Allowed Types

• color
• date
• datetime-local
• email
• hidden
• month
• number
• password
• range
• search
• tel
• text
• time
• url
• week

Special Cases

• file is supported only for images through image
• checkbox

Examples

<Form as |form|>
  <form.Field @name="email" @title="Email" as |field|>
    <field.Input />
  </form.Field>

  <form.Field @name="age" @title="Age" @type="number" as |field|>
    <field.Input />
  </form.Field>
</Form>

@before

Renders text before the input

Examples

<Form as |form|>
  <form.Field @name="email" @title="Email" @before="mailto:" as |field|>
    <field.Input />
  </form.Field>
</Form>

@after

Renders text after the input

Examples

<Form as |form|>
  <form.Field @name="email" @title="Email" @after=".com" as |field|>
    <field.Input />
  </form.Field>
</Form>

Menu

Renders a component.

@selection

The text to show on the trigger.

yielded parameters

Item

Renders a selectable row. Accepts @value, @icon and @action props.

• @value: allows to assign a value to a row.
• @icon: shows an icon at the start of the row.
• @action: override the default action which would set the value of the field with the value of this row.

The content will be yielded.

Divider

Renders a separator.

Container

Renders a div which will have for content the yielded content.

Examples

<Form as |form|>
  <form.Field @name="email" @title="Email" as |field|>
    <field.Menu as |menu|>
      <menu.Item @value={{1}} @icon="pencil-alt">Edit</menu.Item>
      <menu.Divider />
      <menu.Container class="foo">
        Bar
      </menu.Container>
      <menu.Item @action={{this.doSomething}}>Something</menu.Item>
    </field.Menu>
  </form.Field>
</Form>

Password

Renders an <input /> of type password. This control also includes a button which will allow to toggle the visibility of the text. When toggle the type of the input will be switched to text.

Example

<Form as |form|>
  <form.Field @name="secret" @title="Secret" as |field|>
    <field.Password />
  </form.Field>
</Form>

Question

Renders two inputs of type radio where the first one is a positive answer, the second one a negative answer.

@yesLabel

Allows to customize the positive label.

@noLabel

Allows to customize the negative label.

Examples

<Form as |form|>
  <form.Field @name="email" @title="Email" as |field|>
    <field.Question @yesLabel="Correct" @noLabel="Wrong" />
  </form.Field>
</Form>

RadioGroup

Renders a list of radio buttons sharing a common name.

Example

<Form as |form|>
  <form.Field @name="foo" @title="Foo" as |field|>
    <field.RadioGroup as |radioGroup|>
      <radioGroup.Radio @value="one">One</radioGroup.Radio>
      <radioGroup.Radio @value="two">Two</radioGroup.Radio>
      <radioGroup.Radio @value="three">Three</radioGroup.Radio>
    </field.RadioGroup>
  </form.Field>
</Form>

Radio yielded parameters

Title

Allows to render a title.

Examples

<Form as |form|>
  <form.Field @name="foo" @title="Foo" as |field|>
    <field.RadioGroup as |RadioGroup|>
      <RadioGroup.Radio @value="one" as |radio|>
        <radio.Title>One title</radio.Title>
      </RadioGroup.Radio>
    </field.RadioGroup>
  </form.Field>
</Form>

Description

Allows to render a description.

Examples

<Form as |form|>
  <form.Field @name="foo" @title="Foo" as |field|>
    <field.RadioGroup as |RadioGroup|>
      <RadioGroup.Radio @value="one" as |radio|>
        <radio.Description>One description</radio.Description>
      </RadioGroup.Radio>
    </field.RadioGroup>
  </form.Field>
</Form>

Select

Renders a <select> element.

Example

<Form as |form|>
  <form.Field @name="fruits" @title="Fruits" as |field|>
    <field.Select as |select|>
      <select.Option @value="1">Mango</select.Option>
      <select.Option @value="2">Apple</select.Option>
      <select.Option @value="3">Coconut</select.Option>
    </field.Select>
  </form.Field>
</Form>

Text

Renders a <textarea> element.

@height

Sets the height of the textarea.

Example

<Form as |form|>
  <form.Field @name="description" @title="Description" as |field|>
    <field.Textarea @height={{120}} />
  </form.Field>
</Form>

Toggle

Renders a <DToggleSwitch /> component.

There are only 2 states: enabled/disabled. It should feel like turning something on. Toggling takes effect immediately, there is no submit button.

Example

<Form as |form|>
  <form.Field @name="allowed" @title="Allowed" as |field|>
    <field.Toggle />
  </form.Field>
</Form>

Layout

Form Kit aims to provide good defaults, allowing you to mainly use fields and controls. However, if you need more control, we provide several helpers: Row and Col, Section, Fieldset, Container and Actions.

You can also use utilities like Submit, Reset,Alert and InputGroup.

Actions

Actions is a custom Container designed to wrap your buttons in the footer of your form.

Example

<Form as |form|>
  <form.Actions>
    <form.Submit />
  </form.Actions>
</Form>

Alert

Displays an alert in the form.

@icon

An optional icon to use in the alert.

Example

<form.Alert @icon="info-circle">
  Foo
</form.Alert>

@type

Specifies the type of alert. Allowed types: success, error, warning, or info.

Example

<form.Alert @type="warning">
  Foo
</form.Alert>

Checkbox Group

CheckboxGroup allows grouping checkboxes together.

Example

<form.CheckboxGroup @title="Preferences" as |group|>
  <group.Field @name="editable" @title="Editable" as |field|>
    <field.Checkbox />
  </group.Field>
  <group.Field @name="searchable" @title="Searchable" as |field|>
    <field.Checkbox />
  </group.Field>
</form.CheckboxGroup>

Container

Container allows you to render a block similar to a field without tying it to specific data. It is useful for custom controls.

Example

<Form as |form|>
  <form.Container @title="Important" @subtitle="This is important">
    <!-- Container content here -->
  </form.Container>
</Form>

Fieldset

Wraps content in a fieldset.

Example

<form.Fieldset @name="a-fieldset" class="my-fieldset">
  Foo
</form.Fieldset>

@title

Displays a title for the fieldset, will use the legend element.

Example

<form.Fieldset @title="A title">
  Foo
</form.Fieldset>

@description

Displays a description for the fieldset.

Example

<form.Fieldset @description="A description">
  Foo
</form.Fieldset>

@name

Sets the name of the fieldset. This is necessary if you want to use the fieldset test helpers.

Example

<form.Fieldset @name="a-name">
  Foo
</form.Fieldset>

Input Group

Input group allows to group multiple inputs together on one line.

Example

<Form as |form|>
  <form.InputGroup as |inputGroup|>
    <inputGroup.Field @title="Foo" @name="foo" as |field|>
      <field.Input />
    </inputGroup.Field>
    <inputGroup.Field @title="Bar" @name="bar" as |field|>
      <field.Input />
    </inputGroup.Field>
  </form.InputGroup>
</Form>

Reset

The Reset component renders a <DButton /> which will reset the form when clicked. It accepts all the same parameters as a standard <DButton />. The label and default action are set by default.

Example

<form.Reset />

To customize the Reset button further, you can pass additional parameters as needed:

Example with Additional Parameters

<form.Reset @translatedLabel="Remove changes" />

Row and Col

Row and Col enable you to utilize a simple grid system (12 columns) within your form.

Example

<Form as |form|>
  <form.Row as |row|>
    <row.Col @size={{4}}>
      <form.Field @name="foo" @title="Foo" as |field|>
        <field.Input />
      </form.Field>
    </row.Col>
    <row.Col @size={{8}}>
      <form.Field @name="bar" @title="Bar" as |field|>
        <field.Input />
      </form.Field>
    </row.Col>
  </form.Row>
</Form>

Section

Section provides a simple way to create a section with or without a title.

Example

<Form as |form|>
  <form.Section @title="Settings">
    <!-- Section content here -->
  </form.Section>
</Form>

Submit

The Submit component renders a <DButton /> which will submit the form when clicked. It accepts all the same parameters as a standard <DButton />. The label, default action, and primary style are set by default.

Example

<form.Submit />

To customize the Submit button further, you can pass additional parameters as needed:

Example with Additional Parameters

<form.Submit @translatedLabel="Send" />

Object

The object component allows to handle an object in your form.

Example

<Form @data={{hash foo=(hash bar=1 baz=2)}} as |form|>
  <form.Object @name="foo" as |object data|>
    <object.Field @name="bar" @title="Bar" as |field|>
      <field.Input />
    </object.Field>
    <object.Field @name="baz" @title="Baz" as |field|>
      <field.Input />
    </object.Field>
  </form.Object>
</Form>

@name

An object must have a unique name. This name is used as a prefix for the underlying fields.

Example

<form.Object @name="foo" />

Nesting

An object can accept a nested Object or Collection.

Example

<Form @data={{hash foo=(hash bar=(hash baz=1 bol=2))}} as |form|>
  <form.Object @name="foo" as |parentObject|>
    <parentObject.Object @name="bar" as |childObject data|>
      <childObject.Field @name="baz" @title="Baz" as |field|>
        <field.Input />
      </childObject.Field>
    </parentObject.Object>
  </form.Object>
</Form>

<Form @data={{hash foo=(hash bar=(array 1 2))}} as |form|>
  <form.Object @name="foo" as |parentObject|>
    <parentObject.Collection @name="bar" as |collection index|>
      <collection.Field @title="Baz" as |field|>
        <field.Input />
      </collection.Field>
      <form.Button
        class={{concat "remove-" index}}
        @action={{fn collection.remove index}}
      >Remove</form.Button>
    </parentObject.Collection>
  </form.Object>
</Form>

Collection

The collection component allows to handle array of objects in your form.

Example

<Form @data={{hash foo=(array (hash bar=1) (hash bar=2))}} as |form|>
  <form.Collection @name="foo" as |collection index|>
    <collection.Field @name="bar" @title="Bar" as |field|>
      <field.Input placeholder={{concat "item-" index}} />
    </collection.Field>
  </form.Collection>
</Form>

@name

A collection must have a unique name. This name is used as a prefix for the underlying fields.

For example, if collection has the name “foo”, the 2nd field of the collection with the name “bar”, will actually have “foo.1.bar” as name.

Example

<form.Collection @name="foo" />

@tagName

A collection will by default render as a <div class="form-kit__collection>, you can alter this behavior by using a @tagName.

Example

<form.Collection @name="foo" @tagName="tr" />

Primitive array

If the shape of your data is an array of primitives, eg: [1, 2, 3], form-kit is able to handle it. You just have to omit the name on the field in this case, as the name will be auto generated for you with the index.

Example

<Form @data={{hash foo=(array 1 2)}} as |form|>
  <form.Collection @name="foo" as |collection|>
    <collection.Field @title="Baz" as |field|>
      <field.Input />
    </collection.Field>
  </form.Object>
</Form>

Nesting

A collection can accept a nested Object or Collection.

Example

<Form
  @data={{hash foo=(array (hash bar=(hash baz=1)) (hash bar=(hash baz=2)))}}
  as |form|
>
  <form.Collection @name="foo" as |collection|>
    <collection.Object @name="bar" as |object|>
      <object.Field @name="baz" @title="Baz" as |field|>
        <field.Input />
      </object.Field>
    </collection.Object>
  </form.Collection>
</Form>

<Form
  @data={{hash
    foo=(array (hash bar=(array (hash baz=1))) (hash bar=(array (hash baz=2))))
  }}
  as |form|
>
  <form.Collection @name="foo" as |parent parentIndex|>
    <parent.Collection @name="bar" as |child childIndex|>
      <child.Field @name="baz" @title="Baz" as |field|>
        <field.Input />
      </child.Field>
    </parent.Collection>
  </form.Collection>
</Form>

Add an item to the collection

The <Form /> component yielded object has a addItemToCollection function that you can call to add an item to a specific collection.

Example

<Form @data={{hash foo=(array (hash bar=1) (hash bar=2))}} as |form|>
  <form.Button @action={{fn form.addItemToCollection "foo" (hash bar=3)}}>
    Add
  </form.Button>

  <form.Collection @name="foo" as |collection index|>
    <collection.Field @name="bar" @title="Bar" as |field|>
      <field.Input placeholder={{concat "item-" index}} />
    </collection.Field>
  </form.Collection>
</Form>

Remove an item from the collection

The <Collection /> component yielded object has a remove function that you can call to remove an item from this collection, it takes the index as parameter

Example

<Form @data={{hash foo=(array (hash bar=1) (hash bar=2))}} as |form|>
  <form.Collection @name="foo" as |collection index|>
    <collection.Field @name="bar" @title="Bar" as |field|>
      <field.Input />
      <form.Button @action={{fn collection.remove index}}>
        Remove
      </form.Button>
    </collection.Field>
  </form.Collection>
</Form>

Validation

Field accepts a @validation property which allows you to describe the validation rules of the field.

List of Available Rules

Accepted

The value must be "yes", "on", true, 1, or "true". Useful for checkbox inputs — often where you need to validate if someone has accepted terms.

Example

<field.Checkbox @name="terms" @validation="accepted" />

Length

Checks that the input’s value is over a given length, or between two length values.

Example

<field.Input @name="username" @validation="length:5,16" />

Number

Checks if the input is a valid number as evaluated by isNaN().

When applicable, prefer to use the number input: <field.Input @type="number" />.

Example

<field.Input @name="amount" @validation="number" />

Required

Checks if the input is empty.

Example

<field.Input @name="username" @validation="required" />

URL

Checks if the input value appears to be a properly formatted URL including the protocol. This does not check if the URL actually resolves.

Example

<field.Input @name="endpoint" @validation="url" />

integer

Checks if the input value is an integer.

Example

<field.Input @name="age" @validation="integer" />

dateAfterOrEqual

Checks if the calendar data is after or equal to the specified date. Format must be YYYY-MM-DD.

Example

<field.Calendar @name="start" @validation="dateAfterOrEqual:2022-02-01" />

dateBeforeOrEqual

Checks if the calendar data is before or equal to the specified date. Format must be YYYY-MM-DD.

Example

<field.Calendar @name="start" @validation="dateBeforeOrEqual:2022-02-01" />

Combining Rules

Rules can be combined using the pipe operator: |.

Example

<field.Input @name="username" @validation="required|length:5,16" />

Custom Validation

Field

Field accepts a @validate property which allows you to define a callback function to validate the field. Read more about addError in helpers section.

Parameters

• name (string): The name of the form field being validated.
• value (string): The value of the form field being validated.
• data (Object): The data object containing additional information for validation.
• handlers (Object): An object containing handler functions.
  • handlers.addError (Function): A function to add an error if validation fails.

Example

validateUsername(name, value, data, { addError }) {
  if (data.bar / 2 === value) {
    addError(name, { title: I18n.t(`foo.bar.${name}`), message: "That's not how maths work." });
  }
}

<form.Field @name="username" @validate={{this.validateUsername}} />

Form

Form accepts a @validate property which allows you to define a callback function to validate the form. This will be called for each field of the form.

Parameters

• data (Object): The data object containing additional information for validation.
• handlers (Object): An object containing handler functions.
  • handlers.addError (Function): A function to add an error if validation fails.

Example

validateForm(data, { addError }) {
  if (data.bar / 2 === data.baz) {
    addError(name, { title: I18n.t(`foo.bar.${name}`), message: "That's not how maths work." });
  }
}

<Form @validate={{this.validateForm}} />

Helpers

Helpers are yielded by some blocks, like Form, or provided as parameters to callbacks. They allow you to interact with the form state in a simple and clear way.

set

set allows you to assign a value to a specific field in the form’s data.

Parameters

• name (string): The name of the field to which the value is to be set.
• value (number): The value to be set.

Example

set("foo", 1);

Using the set helper yielded by the form:

<Form as |form|>
  <DButton @action={{fn form.set "foo" 1}} @translatedLabel="Set foo" />
</Form>

setProperties

setProperties allows you to assign an object to the form’s data.

Parameters

• data (object): A POJO where each key is going to be set on the form using its value.

Example

setProperties({ foo: 1, bar: 2 });

Using the setProperties helper yielded by the form:

<Form as |form|>
  <DButton
    @action={{fn form.setProperties (hash foo=1 bar=2)}}
    @translatedLabel="Set foo and bar"
  />
</Form>

addError

addError allows you to add an error message to a specific field in the form.

Parameters

• name (string): The name of the field that is invalid.
• error (object): The error’s data
  • title (string): The title of the error, usually the translated name of the field
  • message (string): The error message

Example

addError("foo", { title: "Foo", message: "This should be another thing." });

Customize

Plugin Outlets

FormKit works seamlessly with <PluginOutlet />. You can use plugin outlets inside your form to extend its functionality:

<Form as |form|>
  <PluginOutlet @name="above-foo-form" @outletArgs={{hash form=form}} />
</Form>

Then, in your connector, you can use the outlet arguments to add custom fields:

<@outletArgs.form.Field @name="bar" as |field|>
  <field.Input />
</@outletArgs.form.Field>

Styling

All FormKit components propagate attributes, allowing you to set classes and data attributes, for example:

<Form class="my-form" as |form|>
  <form.Field class="my-field" as |field|>
    <field.Input class="my-control" />
  </form.Field>
</Form>

Custom Control

Creating a custom control is straightforward with the properties yielded by form and field:

<Form as |form|>
  <form.Field class="my-field" as |field|>
    <field.Custom>
      <MyCustomControl id={{field.id}} @onChange={{field.set}} />
    </field.Custom>
  </form.Field>
</Form>

Available Parameters on form

Name	Description
set	Allows you to set the value of any field by name: set("bar", 1)

Available Parameters on field

Name	Description
id	ID to be used on the control for accessibility
name	Name of the field
value	The value of the field

Custom Validation

Field

The Field component accepts a @validate property, allowing you to define a callback function for custom field validation. Read more about addError in the helpers section.

Parameters

• name (string): The name of the form field being validated.
• value (string): The value of the form field being validated.
• data (Object): The data object containing additional information for validation.
• handlers (Object): An object containing handler functions.
  • handlers.addError (Function): A function to add an error if validation fails.

Example

validateUsername(name, value, data, { addError }) {
  if (data.bar / 2 === value) {
    addError(name, { title: I18n.t(`foo.bar.${name}`), message: "That's not how maths work." });
  }
}

<form.Field @name="username" @validate={{this.validateUsername}} />

Form

The Form component accepts a @validate property, allowing you to define a callback function for custom form validation.

Parameters

• data (Object): The data object containing additional information for validation.
• handlers (Object): An object containing handler functions.
  • handlers.addError (Function): A function to add an error if validation fails.

Example

validateForm(data, { addError }) {
  if (data.bar / 2 === data.baz) {
    addError(name, { title: I18n.t(`foo.bar.${name}`), message: "That's not how maths work." });
  }
}

<Form @validate={{this.validateForm}} />

Javascript assertions

Form

The form element assertions are available at assert.form(...).*. By default it will select the first “form” element.

Parameters

• target (string | HTMLElement): The form element or selector.

hasErrors()

Asserts that the form has errors.

Parameters

• message (string): The description of the test.

Example

assert.form().hasErrors("the form shows errors");

Field

The field element assertions are available at assert.form(...).field(...).*.

Parameters

• name (string): The name of the field.

Example

assert.form().field("foo");

hasValue()

Asserts that the value of the field matches the expected text.

Parameters

• expected (anything): The expected value.
• message (string) [optional]: The description of the test.

Example

assert.form().field("foo").hasValue("bar", "user has set the value");

isDisabled()

Asserts that the field is disabled.

Parameters

• message (string) [optional]: The description of the test.

Example

assert.form().field("foo").isDisabled("the field is disabled");

isEnabled()

Asserts that the field is enabled.

Parameters

• message (string) [optional]: The description of the test.

Example

assert.form().field("foo").isEnabled("the field is enabled");

hasError()

Asserts that the field has a specific error.

Parameters

• error (string): The error message on the field.
• message (string) [optional]: The description of the test.

Example

assert.form().field("foo").hasError("Required", "it is required");

hasNoErrors()

Asserts that the field has no error.

Parameters

• message (string) [optional]: The description of the test.

Example

assert.form().field("foo").hasNoErrors("it is valid");

exists()

Asserts that the field is present.

Parameters

• message (string) [optional]: The description of the test.

Example

assert.form().field("foo").exists("it has the food field");

doesNotExist()

Asserts that the field is not present.

Parameters

• message (string) [optional]: The description of the test.

Example

assert.form().field("foo").doesNotExist("it has no food field");

hasCharCounter()

Asserts that the field has a char counter.

Parameters

• current (integer): The current length of the field.
• max (integer): The max length of the field.
• message (string) [optional]: The description of the test.

Example

assert.form().field("foo").hasCharCounter(2, 5, "it has updated the counter");

Fieldset

The field element assertions are available at assert.form(...).fieldset(...).*.

Parameters

• name (string): The name of the fieldset.

Example

assert.form().fieldset("foo");

hasTitle()

Asserts that the title of the fieldset matches the expected value.

Parameters

• expected (anything): The expected value.
• message (string) [optional]: The description of the test.

Example

assert.form().fieldset("foo").hasTitle("bar", "it has the correct title");

hasDescription()

Asserts that the description of the fieldset matches the expected value.

Parameters

• expected (anything): The expected value.
• message (string) [optional]: The description of the test.

Example

assert
  .form()
  .fieldset("foo")
  .hasDescription("bar", "it has the correct description");

includesText()

Asserts that the fieldset has yielded the expected value.

Parameters

• expected (anything): The expected value.
• message (string) [optional]: The description of the test.

Example

assert.form().fieldset("foo").includesText("bar", "it has the correct text");

Javascript helpers

Form

The FormKit helper allows you to manipulate a form and its fields through a clear and expressive API.

Example

import formKit from "discourse/tests/helpers/form-kit";

test("fill in input", async function (assert) {
  await render(
    <template>
      <Form class="my-form" as |form data|>
        <form.Field @name="foo" as |field|>
          <field.Input />
        </form.Field>
      </Form>
    </template>
  );

  const myForm = formKit(".my-form");
});

submit()

Submits the associated form.

Example

formKit().submit();

reset()

Resets the associated form.

Example

formKit().reset();

Field

Parameters

• name (string): The name of the field.

fillIn()

Can be used on <field.Input @type="text" />, <field.Code />, <field.Textarea />, and <field.Composer />.

Parameters

• value (string | integer | undefined): The value to set on the input.

Example

await formKit().field("foo").fillIn("bar");

toggle()

Can be used on <field.Checkbox />, <field.Toggle /> or <field.Password />

Will toggle the state of the control. In the case of the password control it will actually toggle the visibility of the field.

Example

await formKit().field("foo").toggle();

accept()

Can be used on <field.Checkbox />.

Example

await formKit().field("foo").accept();

refuse()

Can be used on <field.Checkbox />.

Example

await formKit().field("foo").refuse();

select()

Can be used on <field.Select />, <field.Menu />, <field.Icon />, and <field.RadioGroup />.

Will select the given value.

Parameters

• value (string | integer | undefined): The value to select.

Example

await formKit().field("foo").select("bar");

System specs page object

Form

The FormKit page object component is available to help you write system specs for your forms.

Parameters

• target (string | Capybara::Node::Element): The selector or node of the form.

Example

form = PageObjects::Components::FormKit.new(".my-form")

form = PageObjects::Components::FormKit.new(find(".my-form"))

submit

Submits the form

Example

form.submit

reset

Reset the form

Example

form.reset

has_an_alert?

Returns if the field is enabled or not.

Example

form.has_an_alert?("message")

expect(form).to have_an_alert("message")

Field

The field helper allows you to interact with a specific field of a form.

Parameters

• name (string): The name of the field.

Example

field = form.field("foo")

value

Returns the value of the field.

Example

field.value

expect(field).to have_value("bar")

checked?

Returns if the control of a checkbox is checked or not.

Example

field.checked?

expect(field).to be_checked

unchecked?

Returns if the control of a checkbox is unchecked or not.

Example

field.unchecked?

expect(field).to be_unchecked

disabled?

Returns if the field is disabled or not.

Example

field.disabled?

expect(field).to be_disabled

enabled?

Returns if the field is enabled or not.

Example

field.enabled?

expect(field).to be_enabled

toggle

Allows toggling a field. Only available for: checkbox.

Example

field.toggle

fill_in

Allows filling a field with a given value. Only available for: input, text, code, and composer.

Example

field.fill_in("bar")

select

Allows selecting a specified value in a field. Only available for: select, icon, menu, radio-group, and question.

Example

field.select("bar")

accept

Allows accepting a field. Only available for: question.

Example

field.accept

refuse

Allows refusing a field. Only available for: question.

Example

field.refuse

upload_image

Takes an image path on the filesystem and uploads it for the field. Only available for the Image control.

Example

field.upload_image(image_file_path)

---

This document is version controlled - suggest changes on github.

[pfaffman (Jay Pfaffman)]

@system

validateUsername(name, value, data, { addError }) {
  if (data.bar / 2 === value) {
    addError(name, { title: I18n.t(`foo.bar.${name}`), message: "That's not how maths work." });
  }
}

上面的代码无法正常工作。这段代码可以：

  validateApiKeyValue(name, value, { data, addError }) {
    console.log(`validate ${name} with ${value}`, data);
  }

是文档错了还是代码错了？

编辑：我决定是文档错了，Update 21-form-kit.md by pfaffman · Pull Request #62 · discourse/discourse-developer-docs · GitHub

[NateDhaliwal]

我认为所有的@用户名都应该放在反引号里。它目前会通知用户名相同的用户。

[awesomerobot (Kris)]

我认为 Form 的导入是错误的，所以我更新了 OP

从

import Form from "discourse/form";

到

import Form from "discourse/components/form";

[pfaffman (Jay Pfaffman)]

我是否正确理解，这是创建表单的推荐方式，例如收集插件添加的新模型的数据？或者这是用于其他目的？

快速浏览核心源代码显示，除了测试之外，没有很少有示例，而且所有示例——包括我在官方插件中看到的示例——都位于 /admin

这个插件正在为 Discourse 添加一个明显不像论坛的模型（Discourse 是我唯一的工具，所以我在网上开发的任何东西都可能是 Discourse 插件）。我可以假设使用这个工具包来处理我所有的表单是有意义的吗？

[awesomerobot (Kris)]

@pfaffman

我能假设使用这个工具包来处理我所有的表单是合理的吗？

是的，这就是目的……如果所有的表单都使用相同的模式，那么我们更容易在未来的更新中支持它们。

[pfaffman (Jay Pfaffman)]

这说得通，有一天，核心插件和官方插件将切换到使用它，这样我就会有更多的例子了？

而且还没有人做太多，因为代码在没有使用这个奇妙的新模板的情况下就能正常工作？

感谢您的耐心！我花了一个小时才调试好这个插件，因为它没有启用，所以我现在对任何事情都感到非常不确定。

[pfaffman (Jay Pfaffman)]

@awesomerobot

我已更新 OP

你能也编辑一下示例代码吗？像我这样的人会直接复制粘贴到编辑器里。

@system

import Form from "discourse/form";

我尝试编辑它，但收到了关于提及超过 10 个用户的错误。

[pfaffman (Jay Pfaffman)]

在过去的几天里，我在努力让这件事奏效。我觉得我是第一个尝试遵循这些说明的人。以下是一些让我卡住的地方。我认为一个完整的可运行示例，无论是作为 gist 还是核心中的某些内容，都会非常有帮助。但是，我现在已经让它工作了！

也许可以将 transientData 移到下面，因为它并非总是必需的，而此时尚未介绍的许多内容对于可运行的示例来说是总是必需的？

同样，我不明白如何在示例中使用 formData()。除了声明它之外，它从未被使用过。也许你会这样调用它：data = formData() 或者你会这样传递它：\u003cForm @data=this.formData ...？

在真正了解字段之前，谈论验证没有意义。

@system

这是最基本的表单示例：

除非（如果你想让它使用任何数据？）你没有这样做，否则它将无法工作。

@system

像这样设置你的表单数据对象：

@system

@cached

但是你不能这样做，除非

import { cached, tracked } from "@glimmer/tracking";

或者也许你不必这样做，但你确实必须在 <Form> 标签中包含 @data={{@somethign}}？（这至少让数据显示在表单中。）

@system

Text

渲染一个 <textarea> 元素。

不。Textarea 渲染一个 textarea，如下面的示例所示。

我无法让 DEditor 显示预览窗格。我很确定当我尝试将 DEditor 制作成自定义字段时，我看到了它。

[Arkshine]

我将在即将到来的 TC 中使用它；但是，这只是基本的东西。

我同意文档可以更精确。我也遇到了困难，主要是因为解释和示例有时令人困惑。我认为这更多地与问题中解释事物的顺序有关。另外，在示例中，用 hash 声明数组最初让我感到困惑，原因不明。

话虽如此，这确实是很棒的东西，并且有一种标准化的表单制作方式真是太棒了！

我不知道这是否有帮助，但这是我基本上所做的（只保留了必需品）

import Component from "@glimmer/component";
import { cached, tracked } from "@glimmer/tracking";

const FORM_FIELDS = ["title", "maxWidth", "autoFit", "duration"];

export default class OptionsMarkmap extends Component {
  @tracked data;

  constructor() {
    super(...arguments);

    // 设置默认值
    this.data = {
      title: "",
      maxWidth: 0,
      autoFit: "true",
      duration: 400,
    };
  }

  @cached
  get formData() {
    return getProperties(this.data, ...FORM_FIELDS);
  }

  @action
  save(data) {
    // 
  }

  <template>
    <Form @data={{this.formData}} @onSubmit={{this.save}} as |form|>
      <form.Field
        @name="title"
        @title="Title"
        @format="large"
        as |field|
      >
        <form.Container>
          <field.Input />
        </form.Container>
      </form.Field>

      <form.Field
        @name="maxWidth"
        @title="Max Node Width"
        @type="number"
        as |field|
      >
        <form.Container>
          <field.Input />
        </form.Container>
      </form.Field>

      <form.Field
        @name="autoFit"
        @showTitle={{false}}
        @title="Auto Fit"
        as |field|
      >
        <form.Container>
          <field.Checkbox />
        </form.Container>
      </form.Field>

      <form.Actions>
        <form.Submit @label="Save" />
      </form.Actions>
    </Form>
  </template>
}

关于 data，这是你的初始值。
formData 的使用允许你缓存对象（因为 data 是不可变的），并且我认为 getProperties 是指定包含哪些字段的好方法。formData 是你在 <Form @data=... 中提供的内容。

get formData() {
  return getProperties(this.data, ...FORM_FIELDS);
}

[pfaffman (Jay Pfaffman)]

@Arkshine

`

`

是的。这些都说得通，但主要是等你明白了之后！

但我认为我不明白什么被缓存了，或者在哪里或为什么？

@Arkshine

    // Sets the default values

啊！那太好了。

是的。我认为这看起来是一个好得多的“最小可行模型”！

谢谢！

field.Composer 详解

~~我还是弄不明白如何让它显示预览。~~我写了一些 CSS 来显示预览，但我仍然无法让它占据整个宽度。

我有 <field.Composer @height={{80}} />，它看起来和 <field.Composer @height={{800}} /> 完全一样，（也许有一些默认的 CSS 覆盖了它？）——找到了！ --form-kit-large-input: 100%; （实际上这会影响宽度，但我仍然不确定高度）。

[j.jaffeux (Joffrey Jaffeux)]

@pfaffman

在过去几天里，我在尝试让它工作方面取得了进展。我觉得我是第一个尝试遵循这些说明的人。以下是一些让我卡住的事情。我认为一个完整的有效示例，无论是作为gist还是核心中的某些内容，都会有很大的帮助。但是，我现在已经让它工作了！

核心FTR中有完整的有效示例。

[j.jaffeux (Joffrey Jaffeux)]

@pfaffman

And more about field.Composer

~~I still can’t figure out how to get it to show the preview.~~I got some CSS to make the preview show, but I still can’t make it take up the full width.

I’ve got <field.Composer @height={{80}} /> and it looks exactly the same as <field.Composer @height={{800}} />, (maybe there is some default CSS that’s overriding this?)–found it! --form-kit-large-input: 100%; (actually that affects the width, but I’m still not sure about the height)

There were legit issues on this. I fixed them all in FIX: supports height/preview form-kit composer by jjaffeux · Pull Request #31121 · discourse/discourse · GitHub and documented in document composer preview option by jjaffeux · Pull Request #37 · discourse/discourse-developer-docs · GitHub

[pfaffman (Jay Pfaffman)]

@j.jaffeux

FTR 核心中有完整的可用示例。

我上次看的时候（没多少？）没有。要么是我上次 grep 用得不好，要么是在过去一两周里添加了很多。如果这份文档能指向其中一个很好的范例就好了。

@j.jaffeux

确实存在一些问题。我都修复了

哥们！太棒了！我迫不及待想看看。我昨天花了（感觉上）一整天时间在这个上面（至少 2 小时）。我 CSS 太差了，我以为是我自己笨。啊，你修复了隐藏和高度部分。我现在还在为宽度发愁。我无法让编辑器占据屏幕的一半，而是随着文本的输入而占据更多空间，如果字段为空，它又太小了，根本没地方输入文本。我晚点再看看，但我太兴奋了，想尽快回复。

[j.jaffeux (Joffrey Jaffeux)]

@pfaffman

我现在在为宽度而烦恼。我无法让编辑器占据屏幕的一半，而是随着文本的输入，它占据了更多的空间，而且如果字段为空，它太小了，以至于没有地方可以输入文本。我稍后会看看，但我太兴奋了，想尽快回复。

@format="full" 在包裹编辑器的字段上

[david (David Taylor)]

@pfaffman

@j.jaffeux

FTR 核心中有完整的可用示例。

我上次查看时（没有很多？）没有。

试试 这个搜索 - 它至少有 10 个“真实”示例，还有很多测试中的示例。

[j.jaffeux (Joffrey Jaffeux)]

@david

@pfaffman

@j.jaffeux

FTR 核心中有完整的可用示例。

我上次看的时候（没多少？）没有。

试试这个搜索 - 它至少有 10 个‘真实’示例，还有很多测试中的示例。

是的，老实说，我不太愿意从文档链接到示例，因为这些链接往往会很快过时，如果人们删除文件、更改路径……他们就不会知道文档链接到它。

[pfaffman (Jay Pfaffman)]

@j.jaffeux

我都修好了

确实修好了！真的管用！

非常感谢。

[merefield (Robert)]

如何正确实现“多选”？即允许用户从一组固定的枚举值中更新一个数组。

我想我可以用一个 复选框组。

但是有“下拉菜单”的选项吗？

例如，如果我有一些配料：

[“米饭”, “芒果”, “鸡蛋”, “盐”, “孜然”]

并且我希望用户能够选择零个、一个、多个或全部。

结果应该存储在一个数组中。

即为完整集合的每个成员设置一个开关。

有现成的示例吗？

[Arkshine]

也许可以和 MultiSelect 一起使用自定义字段？ https://meta.discourse.org/t/discourse-toolkit-to-render-forms/326439#p-1603904-custom-control-110

我看到核心代码中有一些示例，例如：

<form.Field
    @name="appliesTo"
    @title={{i18n "admin.config_areas.flags.form.applies_to"}}
    @validation="required"
    @validate={{this.validateAppliesTo}}
    @format="large"
    as |field|
  >
    <field.Custom>
      <MultiSelect
        @id={{field.id}}
        @value={{field.value}}
        @onChange={{field.set}}
        @content={{this.appliesToValues}}
        @options={{hash allowAny=false}}
        class="admin-flag-form__applies-to"
      />
    </field.Custom>
  </form.Field>

这能帮到你吗？