Ember Form For

This Ember.js addon will give you an easy way to build good forms:

• Supports all HTML5 input types, textarea and select, backed by ember-one-way-controls
• Automatically adds labels, hints and errors to the form controls
• Is built with data down - actions up in mind
• Standard markup has built-in accessibility support
• Compatible with ember-changeset (see instructions)
• Compatible with ember-i18n (see instructions)

WARNING: This addon uses contextual helpers and is therefore onlycompatible with apps built with Ember.js version 2.3 and up.

NOTE: I'm working on rewriting docs, click here for the old docs!

Installation

ember install ember-form-for

Quickstart Example

{{#form-for newUser as |f|}}
  {{f.text-field "firstName"}}
  {{f.text-field "lastName"}}

  {{#fields-for newUser.address as |fa|}}
    {{fa.text-field "street"}}
    {{fa.text-field "city"}}
    {{fa.text-field "state"}}
    {{fa.text-field "zipCode"}}
  {{/fields-for}}

  {{f.select-field "gender" "unknown male female"}}

  {{f.date-field "birthDate"}}

  {{f.email-field "emailAddress"}}
  {{f.text-field "userName"}}
  {{f.password-field "password" hint="Must be at least six characters long and include a capital letter"}}

  {{f.checkbox-field "terms" label="I agree to the Terms of Service"}}

  {{f.reset  "Clear form"}}
  {{f.submit "Create account"}}
{{/form-for}}

See this example in action: http://martndemus.github.io/ember-form-for/

Breaking down the quickstart example

Let's first take a look at the form-for component itself:

{{#form-for newUser as |f|}}
  {{! form fields go here }}
{{/form-for}}

The {{form-for}} component takes an object as first parameter, newUser inthis case, this is the object where the form fields will be created for.

It then yields f, f contains all form controls as contextual components.This means that the components rendered with f already have form-for'scontext applied to it, you don't have to pass the target object to eachform control, form-for takes care of that.

For example {{f.text-field "firstName"}} will render an input that will updatethe firstName property of the newUser object you have passed to theform-for component. You didn't have to pass newUser again, because it's takenfrom form-for's context.

Next you see the {{fields-for}} component. This component is similar toform-for, except it doesn't render a <form> element as outer element, thisis ideal to embed subsections to your form that operate on a different object.

Lastly there are the {{f.reset}} and {{f.submit}} button components. Theseare getting passed the reset and submit action from the form-for componentrespectively. By default the reset action will call the rollback function onthe object, the submit action will call the save function on the object.

Table of Contents

• Installation
• Quickstart Example
• Table of Contents
• Reference
  • form-for
  • form-fields
• Integrations
  • i18n
  • ember-changeset
• Customizing/Extending (Coming Soon™)
  • Adding Class Names (Coming Soon™)
  • Using Custom Form Controls (Coming Soon™)
  • Injecting Custom Fields Into Form For (Coming Soon™)

Reference

form-for

The {{form-for}} component is the main component from this addon. All formsbuilt with this addon should start with this component.

Syntax

{{#form-for object
    update=(action update)
    submit=(action submit)
    reset=(action reset)
    as |f|
}}
  {{! block content }}
{{/form-for}}

Parameters

object

The object the form fields are for

update

This action is called every time a field is updated. It will pass threearguments: object, property and value. By default it will automaticallyupdate the property on the object with the new value.

submit

This action is called when a submit button is clicked. It will pass the objectas first argument. By default it will call the save function on the object.This action also supports returning a promise, which the {{f.submit}} component.

reset

This action is called when a reset button is clicked. It will pass the objectas first argument. By default it will call the rollback function on theobject.

Yields

formControls

An object containing form controls as contextual components.The form controls have the object and the update action pre-bound to it.

The default form controls are:

• checkbox-field
• color-field
• date-field
• datetime-local-field
• email-field
• file-field
• hidden-field
• month-field
• number-field
• password-field
• radio-field
• radio-group
• range-field
• search-field
• select-field
• tel-field
• text-field
• textarea-field
• time-field
• url-field
• week-field
• custom-field

Additionally these buttons are also available:

• button
• reset
• submit

form-fields

The form-field components are yielded from the {{form-for}} component. All theavailable form-field components are described in the form-for section.

Syntax

{{#form-for object as |f|}}
  {{f.text-field "propertyName"}}
{{/form-for}}

Parameters

object

The object the form field is for. By default object is the object passed tothe {{form-for}} component, but you can override it if you want to.

propertyName

This tells the form field which property of the object to use as value. Can bepassed as the first positional param.

update

The action that handles updates to the value of the form-field by the user. Bydefault this action is passed down from the {{form-for}} component.

label

The text value for the label of the form-field. By default is inferred from thepropertyName attribute or lookup up from the i18n service if available.

hint

Text to be displayed along the control as a hint to the user.

required

If set to true it will mark the field as required.

Integrations

i18n

Ember Form For has out of the box support forember-i18n. If your project hasthis addon installed, it will automatically lookup the translation with thefollowing key algorithm:

• By default it will use property-name as key. (e.g. 'first-name').
• If modelName is set, or deducable from the object, then it will beprefixed to the key. (e.g. 'user.first-name')
• If i18nKeyPrefix is set on the config, then this will be prefixed beforemodelName and propertyName. (e.g. 'my.arbitrary.key.user.first-name')

Polyfilling i18n

The project does not have a hard dependency on ember-i18n, you can easilydrop-in your own implementation. All you need is a service called i18n thathas a function called t.

ember-changeset

It's easy to integrateember-changeset andember-changeset-validationswith Ember Form For. All you have to do is to pass the changeset into the{{form-for}} helper instead of the raw object:

{{#form-for (changeset model validations) as |f|}}
  {{! form fields }}
{{/form-for}}

Errors

To be able to use the errors generated by ember-changeset you need to configurethe following thing in your config/environment.js file:

module.exports = function(environment) {
  var ENV = {
    'ember-form-for': {
      errorsPath: 'error.PROPERTY_NAME.validation',
    }
  };

  return ENV;
};

This is because ember-changeset stores it's errors on the error.PROPERTY_NAME.validation property,while Ember Form For expects them (by default) to be on the errors property.

For those still using the old configuration of setting errorsProperty, this method will still work.However, if both are defined then errorsPath will take precedence.