ember-changeset

Ember.js flavored changesets, inspired by Ecto. To install:

ember install ember-changeset

Philosophy

The idea behind a changeset is simple: it represents a set of valid changes to be applied onto any Object (Ember.Object, DS.Model, POJOs, etc). Each change is tested against an optional validation, and if valid, the change is stored and applied when executed.

Given Ember's Data Down, Actions Up (DDAU) approach, a changeset is more appropriate compared to implicit 2 way bindings. Other validation libraries only validate a property after it is set on an Object, which means that your Object can enter an invalid state.

ember-changeset only allows valid changes to be set, so your Objects will never become invalid (assuming you have 100% validation coverage). Additionally, this addon is designed to be un-opinionated about your choice of form and/or validation library, so you can easily integrate it into an existing solution.

The simplest way to incorporate validations is to use ember-changeset-validations, a companion addon to this one. It has a simple mental model, and there are no Observers or CPs involved – just pure functions.

tl;dr

let changeset = new Changeset(user, validatorFn);
user.get('firstName'); // "Michael"
user.get('lastName'); // "Bolton"

changeset.set('firstName', 'Jim');
changeset.set('lastName', 'B');
changeset.get('isInvalid'); // true
changeset.get('errors'); // [{ key: 'lastName', validation: 'too short', value: 'B' }]
changeset.set('lastName', 'Bob');
changeset.get('isValid'); // true

user.get('firstName'); // "Michael"
user.get('lastName'); // "Bolton"

changeset.save(); // sets and saves valid changes on the user
user.get('firstName'); // "Jim"
user.get('lastName'); // "Bob"

Usage

First, create a new Changeset using the changeset helper or through JavaScript:

{{! application/template.hbs}}
{{dummy-form
    changeset=(changeset model (action "validate"))
    submit=(action "submit")
    rollback=(action "rollback")
}}

import Ember from 'ember';
import Changeset from 'ember-changeset';

const { Component, get } = Ember;

export default Component.extend({
  init() {
    let model = get(this, 'model');
    let validator = get(this, 'validate');
    this.changeset = new Changeset(model, validator);
  }
});

The helper receives any Object (including DS.Model, Ember.Object, or even POJOs) and an optional validator action. If a validator is passed into the helper, the changeset will attempt to call that function when a value changes.

// application/controller.js
import Ember from 'ember';

const { Controller } = Ember;

export default Controller.extend({
  actions: {
    submit(changeset) {
      return changeset.save();
    },

    rollback(changeset) {
      return changeset.rollback();
    },

    validate({ key, newValue, oldValue, changes }) {
      // lookup a validator function on your favorite validation library
      // should return a Boolean
    }
  }
});

Then, in your favorite form library, simply pass in the changeset in place of the original model.

{{! dummy-form/template.hbs}}
<form>
  {{input value=changeset.firstName}}
  {{input value=changeset.lastName}}

  <button {{action submit changeset}}>Submit</button>
  <button {{action rollback changeset}}>Cancel</button>
</form>

In the above example, when the input changes, only the changeset's internal values are updated. When the submit button is clicked, the changes are only executed if all changes are valid.

On rollback, all changes are dropped and the underlying Object is left untouched.

API

Properties
- error
- change
- errors
- changes
- isValid
- isInvalid
- isPristine
- isDirty
Methods
- get
- set
- prepare
- execute
- save
- merge
- rollback
- validate
- addError

`error`

Returns the error object.

{
  firstName: {
    value: 'Jim',
    validation: 'First name must be greater than 7 characters'
  }
}

You can use this property to locate a single error:

{{#if changeset.error.firstName}}
  <p>{{changeset.error.firstName.validation}}</p>
{{/if}}

About

Languages