jfdnc/ember-fit-form

A flexible component for form state management for use with many models and types

ember-fit-form

A form component which wraps a native <form> element and provides form state management abstractions.

ember-fit-form provides flexible state management for forms. We aim to support many data and validation libraries for use within your application's forms. We're also built on ember-concurrency, so you can easily support promise-aware hooks to manage your applications form state.

Currently supported data models:

1. ember-data

   Validation Libraries:

   • ember-cp-validations
   • ember-validations

2. ember-changeset

   Validation Libraries:

   • ember-changeset-validations

Please note that ember-fit-form does not provide form control components. It is simply an html form element with abstractions for state management.

Installation

ember install ember-fit-form

Usage

Example

{{!-- my-form.hbs --}}
{{#fit-form model oncancel=(action rollback) onsubmit=(action save) as |form|}}
  <input oninput={{action (mut model.name) value="target.value"}}>

  {{!-- other form content --}}

  <button {{form.cancel}} disabled={{form.isCancelling}}>
    {{if form.isCancelling "Cancelling..." "Cancel"}}
  </button>

  <button {{form.submit}} disabled={{form.isUnsubmittable}}>
    {{if form.isSubmitting "Saving..." "Save"}}
  </button>
{{/fit-form}}

// my-form.js
rollback() {
  return model.rollbackAttributes();
},
save() {
  return model.save();
}

Configure Adapter

By default, ember-fit-form expects Changeset models. To setup your default Model type, you should configure the component through config/environment:

module.exports = function(environment) {
  var ENV = {
    emberFitForm: {
      adapter: 'ember-changeset' // default
    }
  }
}

In the case that your forms use mixed Models throughout your application, you can overwrite the adapter at the component level.

{{#fit-form model adapter="ember-model"}}
  {{!-- form content --}}
{{/fit-form}}

Custom Adapters

Coming Soon

API

• Actions

• submit
• cancel
• validate

• Component Action Hooks

• onsubmit
• onsuccess
• onerror
• oncancel
• onvalidate
• oninvalid

• Component Event Handler Hooks

• onkeydown
• onkeyup
• keypress

• Attributes

• isUnsubmittable
• isSubmittable
• isValid
• isInvalid
• isDirty
• isPristine
• isCancelling
• isSubmitting
• isValidating
• didCancel
• didSubmit
• didValidate

Fit-Form Actions

submit

Submits the form.

Submitting a form calls the form's validate method and then calls the form's onsubmit hook if validation succeeds.

form.submit();

<button {{action form.submit}}>Submit</button>
{{!-- or --}}
<button onclick={{action form.submit}}>Submit</button>

The onsubmit hook will never be called if onvalidate hooks is rejected.

⬆️ back to top

cancel

Cancels the form. Cancelling a form calls the form's oncancel hook.

form.cancel();

<button {{action form.cancel}}>Cancel</button>
{{!-- or --}}
<button onclick={{action form.cancel}}>Cancel</button>

⬆️ back to top

validate

Validates the form. Validating a form calls the validate action for each of the form's models.

form.validate();

<button {{action form.validate}}>Check Validity</button>
{{!-- or --}}
<button onclick={{action form.validate}}>Check Validity</button>

⬆️ back to top

Fit-Form Component Action Hooks

The form object is always curried in as the last argument for all component action hooks.

onsubmit

The onsubmit hook action is a promise-aware action which is called on form submission. Form submission is triggered when calling form.submit().

{{#fit-form model onsubmit=(action save) as |form|}}
  <button {{form.submit}}>Save</button>
{{/fit-form}}

save(/* form */) {
  return model.save();
}

The onsubmit hook will not be called on form submission if onvalidate hooks is rejected.

⬆️ back to top

onsuccess

The onsuccess hook is a promise-aware action which is called when the onsubmit hook is fulfilled.

{{#fit-form model onsuccess=(action success) as |form|}}
  <button {{form.submit}}>Save</button>
{{/fit-form}}

success(/* result, form */) {
  // Do something
}

⬆️ back to top

onerror

The onerror hook is a promise-aware action which is called when the onsubmit hook is rejected.

{{#fit-form model onerror=(action error) as |form|}}
  <button {{form.submit}}>Save</button>
{{/fit-form}}

error(/* error, form */) {
  // Do something
}

⬆️ back to top

oncancel

The oncancel hook is a promise-aware action which is called on form cancellation. Form cancellation is triggered when calling form.cancel().

{{#fit-form model oncancel=(action rollback) as |form|}}
  <button {{form.cancel}}>Cancel</button>
{{/fit-form}}

rollback(/* form */) {
  return model.rollback();
}

⬆️ back to top

onvalidate

The onvalidate hook is a promise-aware action which is called on form validation. Form validation is triggered when calling form.validate() or form.submit() On form submission, if onvalidate returns a rejected Promise or false, the submission will reject, and onsubmit will not be called.

{{#fit-form model onvalidate=(action validate) as |form|}}
  <button {{form.validate}}>Check Fields</button>
  <button {{form.submit}}>Save</button>
{{/fit-form}}

validate(/* form */) {
  return model.validate();
}

⬆️ back to top

oninvalid

The oninvalid hook is a promise-aware action which is called when the onvalidate hook is rejected or returns false.

{{#fit-form model oninvalid=(action invalid) as |form|}}
  <button {{form.submit}}>Save</button>
{{/fit-form}}

invalid(/* error, form */) {
  // Do something
}

⬆️ back to top

Fit-Form Component Event Handler Hooks

The form object is always curried in as the last argument for all component event handler hooks.

onkeydown

When onkeydown is passed into fit-form component, it registers the keyDown event on the html form element. The onkeydown hook is called when the keyDown event is triggered.

{{#fit-form model onkeydown=(action handlekey) as |form|}}
  {{!-- form content --}}
{{/fit-form}}

handlekey(event, form) {
  if (event.key === "Enter" && event.shiftKey) {
    // Shift + Enter
    form.submit();
  } else if (event.key === "Escape") {
    form.cancel();
  }
}

⬆️ back to top

onkeyup

When onkeyup is passed into fit-form component, it registers the keyUp event on the html form element. The onkeyup hook is called when the keyUp event is triggered.

See onkeydown example for usage.

⬆️ back to top

keypress

When onkeypress is passed into fit-form component, it registers the keyPress event on the html form element. The onkeypress hook is called when the keyPress event is triggered.

See onkeydown example for usage.

⬆️ back to top

Fit-Form Attributes

isUnsubmittable

Returns a Boolean value of the form's (un)submittability.

form.get('isUnsubmittable'); // true

<button {{action form.submit}} disabled={{form.isUnsubmittable}}>Submit</button>

You can still call submit if isUnsubmittable is true.

⬆️ back to top

isSubmittable

Returns a Boolean value of the form's submittability.

form.get('isSubmittable'); // true

{{#if form.isSubmittable}}
  <span class=fa fa-check'></span>
{{/if}}

⬆️ back to top

isValid

Returns a Boolean value of the form's validity. A valid form is one where all of the form's models are valid.

form.get('isValid'); // true

{{#if form.isValid}}
  <span class=fa fa-check'></span>
{{/if}}

⬆️ back to top

isInvalid

Returns a Boolean value of the form's (in)validity. A invalid form is one where the some of the form's models are invalid.

form.get('isInvalid'); // true

{{#if form.isInvalid}}
  <span class=fa fa-times></span>
{{/if}}

⬆️ back to top

isDirty

Returns a Boolean value of the form's state. A dirty form is one with changes.

form.get('isDirty'); // true

⬆️ back to top

isPristine

Returns a Boolean value of the form's state. A pristine form is one with no changes.

form.get('isPristine'); // true

⬆️ back to top

isCancelling

Returns a Boolean value of the form's cancelling state. A cancelling form is one where the oncancel hook is pending. This attribute is commonly coupled with the cancel action.

form.get('isCancelling'); // true

<button {{action form.cancel}} disabled={{form.isCancelling}}>Cancel</button>

⬆️ back to top

isSubmitting

Returns a Boolean value of the form's submitting state. A submitting form is one where the onsubmit, onsuccess, or onerror hooks are pending. This attribute is commonly coupled with the submit action.

form.get('isSubmitting'); // true

<button {{action form.submit}} disabled={{form.isSubmitting}}>Submit</button>

⬆️ back to top

isValidating

Returns a Boolean value of the form's validating state. A validating form is one where the form's model(s) are validating upon form submission.

form.get('isValidating'); // true

{{#if form.isValidating}}
  <span class=fa fa-spinner></span>
{{/if}}

⬆️ back to top

didCancel

Returns a Boolean value of the form's cancelled state. A cancelled form is one where the oncancel hooks is settled.

form.get('didSubmit'); // true

{{#if form.didSubmit}}
  <span class='error'>{{model.errors}}</span>
{{/if}}

⬆️ back to top

didSubmit

Returns a Boolean value of the form's submitted state. A submitted form is one where the onsubmit hooks is settled.

form.get('didSubmit'); // true

{{#if form.didSubmit}}
  <span class='error'>{{model.errors}}</span>
{{/if}}

⬆️ back to top

didValidate

Returns a Boolean value of the form's validated state. A validated form is one where the form's model(s) were validated upon form submission.

form.get('didValidate'); // true

{{#if form.didValidate}}
  <span class='error'>{{model.errors}}</span>
{{/if}}

⬆️ back to top