/ember-form-for

Primary LanguageJavaScriptMIT LicenseMIT

Ember Form For

Download count all time npm version CircleCI Ember Observer Score

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
  • Compatible with ember-i18n

WARNING: This addon uses contextual helpers and is therefore only compatible 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 atleast 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 in this 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's context applied to it, you don't have to pass the target object to each form control, form-for takes care of that.

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

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

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

Table of Contents

Reference

form-for

The {{form-for}} component is the main component from this addon. All forms built 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 three arguments: object, property and value. By default it will automatically update the property on the object with the new value.

submit

This action is called when a submit button is clicked. It will pass the object as first argument. By default it will call the save function on the object.

reset

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

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-field
  • datetime-local-field
  • email-field
  • file-field
  • hidden-field
  • month-field
  • number-field
  • password-field
  • radio-field
  • radio-group
  • range-field
  • search-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 the available 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 to the {{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 be passed as the first positional param.

update

The action that handles updates to the value of the form-field by the user. By default 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 the propertyName 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 for ember-i18n. If your project has this addon installed, it will automatically lookup the translation with the following key algorithm:

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

Polyfilling i18n

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

ember-changeset

It's easy to integrate ember-changeset and ember-changeset-validations with 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 configure the following thing in your config/environment.js file:

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

  return ENV;
};

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