npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

ember-form-for

v2.0.1

Published

Build "Data Down Actions Up" forms, with good default markup and built-in accessibility support

Downloads

140

Readme

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:

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 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 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. This action also supports returning a promise, which the {{f.submit}} component, which uses ember-async-button, will handle to show different states.

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-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:

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 property-name as key. (e.g. 'first-name').
  • If modelName is set, or deducable from the object, then it will be prefixed to the key. (e.g. 'user.first-name')
  • If i18nKeyPrefix is set on the config, then this will be prefixed before modelName 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 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': {
      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.