Ember Form Builder is an Ember Addon that enables you to assemble forms with labels, validations, hints without repeating yourself. It's strongly inspired by a Rails gem SimpleForm.

Note: this library only works with Ember 2.0 or newer and requires Ember CLI.

npm install --save-dev ember-form-builder

{{#form-builder for=this action="submit" as |f|}}

  {{input-on f "title"}}
  {{input-on f "category" collection=categories
             optionValuePath="content.id" optionLabelPath="content.fullName"}}
  {{input-on f "isPublished"}}
  {{input-on f "publishedOn" as="date"}}
  {{input-on f "price" unit="PLN" hint="Leave empty if this is a free article"}}

  {{submit-on f}}

{{/form-builder}}

The following inputs types are built into Ember Form Builder:

You can easily extend any of the above inputs by overriding them and requiring addon's original component. Like this:

// In app/components/inputs/text-input.js
import TextInput from "ember-form-builder/components/inputs/text-input";

export default TextInput.extend({
  init() {
    this._super();
    this.attributeBindings.push("customAttribute");
  },

  customAttribute: Ember.computed(function() {
    /* some code */
  })
});

To provide your own input types simply implement a component named your-type-input and put it into components/inputs folder. Like this:

// In app/components/inputs/your-type-input.js
import Ember from "ember";

export default Ember.Component.extend({});

You can then use your input using the as option:

{{input-on f "description" as="your-type"}}

Ember Form Builder supports validations out of the box. It will automatically mark inputs as erroneus and display error messages next to them whenever:

• the form's subject (for=this, remember?) has an errors object and there is at least one error in it for the input's attribute (e.g. errors.attributeName contains an array of error messages) and
• a user has focused out of the input at least once.

This is compatible both with Ember Data's server-provided validation messages and with client-side validations provided by Ember Validation. However none of those libraries is required by Ember Form Builder.

You can easily cusomize labels and other texts by providing values through attributes in your templates but if your app is or might become international you might wish to integrate the forms with an i18n library. Ember Form Builder only supports Ember-I18n at the moment, however other solutions might be integrated in the future.

Ember Form Builder automatically detects Ember-I18n and tries to guess the translation keys.

| label | hint | submit | required --- | --- | --- | --- | --- Explicit | label="My attribute" | hint="My hint" | text="My submit" | not possible Custom translation key | labelTranslation="custom.label.key" | hintTranslation="custom.hint.key" | translation="custom.submit.key" | not possible Custom form translation key: {{#form-for translationKey="custom.key"}} | Looks up custom.key.attributes.attribute | Looks up custom.key.hints.attribute | Looks up custom.key.actions.submit | not possible Underlying Ember Data model's modelName (e.g. article) | Looks up article.attributes.attribute | Looks up article.hints.attribute | Looks up article.actions.submit | not possible Default | humanizes attribute name | empty | Looks up formBuilder.actions.submit | Looks up formBuilder.isRequired Without ember-i18n | humanizes attribute name | empty | "Save" | "Required"

Ember Form Builder exposes all the class names it uses via environment configuration. To override them, specify your values in config/environment.js under formBuilder key (e.g. ENV.formBuilder.wrapperClass = "form-input").

Those are the default classes:

{
  wrapperClass: "input", // input's root element
  wrapperWithErrorsClass: "input-with-errors", // input's root element, when there are errors on this attribute
  wrapperWithUnitClass: "has-unit", // input's root element, when a unit has been specified
  unitClass: "input-unit", // unit element
  errorsClass: "errors", // errors container
  fieldClass: "field", // wrapper around input, errors, hint and unit
  inputClass: "input-control", // the actual input
  hintClass: "hint" // hint element
}

You'll probably want to customize the markup Ember Form Builder generates. For that, you can override the default templates.

Start by copying all or some of the default templates to your app. Then modify whatever you want.

nibynic © 2015

Licensed under the MIT license