Components.Form public

Render a form with the appropriate Bootstrap layout class (see formLayout). Allows setting a model that nested Components.FormElements can access, and that can provide form validation (see below)

You can use whatever markup you like within the form. However, to benefit from features such as automatic form markup, validations and validation markup, use Components.FormElement as nested components. See below for an example.

Submitting the form

The form yields a submitButton component, which is a preconfigured <BsButton> with @type="primary" and type="submit". The button is disabled while a form submission is pending. Additionally, the button state is bound to the form submission state.

<BsForm as |form|>
  <form.submitButton>Submit</form.submitButton>
</BsForm>

When the form is submitted (e.g. by clicking the submit button), the event will be intercepted and the onSubmit action will be sent to the controller or parent component. In case the form supports validation (see "Form validation" below), the onBefore action is called (which allows you to do e.g. model data normalization), then the available validation rules are evaluated, and if those fail, the onInvalid action is sent instead of onSubmit.

Use with Components.FormElement

When using Components.FormElements with their property set to property names of the form's validation enabled model, you gain some additional powerful features:

• the appropriate Bootstrap markup for the given formLayout and the form element's controlType is automatically generated
• markup for validation states and error messages is generated based on the model's validation (if available), when submitting the form with an invalid validation, or when focusing out of invalid inputs

<BsForm @formLayout="horizontal" @model={{this}} @onSubmit={{this.submit}} as |form|>
  <form.element @controlType="email" @label="Email" @placeholder="Email" @property="email" />
  <form.element @controlType="password" @label="Password" @placeholder="Password" @property="password" />
  <form.element @controlType="checkbox" @label="Remember me" @property="rememberMe" />
  <form.submitButton>Submit</form.submitButton>
</BsForm>

See the Components.FormElement API docs for further information.

Form validation

All version of ember-bootstrap beginning from 0.7.0 do not come with built-in support for validation engines anymore. Instead, support is added usually by additional Ember addons, for example:

• ember-bootstrap-validations: adds support for ember-validations
• ember-bootstrap-cp-validations: adds support for ember-cp-validations
• ember-bootstrap-changeset-validations: adds support for ember-changeset

To add your own validation support, you have to:

• extend this component, setting hasValidator to true if validations are available (by means of a computed property for example), and implementing the validate method
• extend the Components.FormElement component and implement the setupValidations hook or simply override the errors property to add the validation error messages to be displayed

When validation fails, the appropriate Bootstrap markup is added automatically, i.e. the error classes are applied and the validation messages are shown for each form element. In case the validation library supports it, also warning messages are shown. See the Components.FormElement documentation for further details.

See the above-mentioned addons for examples.

The novalidate HTML attribute is set by default for forms that have validation.

Submission state

A isSubmitting property is yielded, which is true after submit has been triggered and before the Promise returned by onSubmit is fulfilled. It could be used to show a loading spinner instead of the form while it's submitting for example:

<BsForm @onSubmit={{this.save}} as |form|>
  {{#if form.isSubmitting}}
    <span class="spinner-border spinner-border-sm" role="status" aria-hidden="true"></span>
    Logging in...
  {{else}}
    <form.element @property="email" @label="email" />
    <form.element @property="password" @label="password" @controlType="password" />
    <form.submitButton>Login</form.submitButton>
  {{/if}}
</BsForm>

Additionaly isSubmitted and isRejected properties are yielded. isSubmitted is true if last submission was successful. isRejected is true if last submission was rejected due to validation errors or by an action bound to onSubmit event, returning a rejected promise. It could be used for visual feedback about last submission:

<BsForm @onSubmit={{this.save}} as |form|>
  <form.submitButton @type={{if form.isRejected "danger" "primary"}}>
    Save
  </form.submitButton>
</BsForm>

The submission state is reset as soon as any value of a form element changes. Additionally, it can be reset programmatically by calling the yielded resetSubmissionState function.

Note that only invoking the component in a template as shown above is considered part of its public API. Extending from it (subclassing) is generally not supported, and may break at any time.