ember-do-forms



An Ember forms library that handles the icky parts of forms that you don't want to do, but makes no other assumptions otherwise.

Get started with:

ember install ember-do-forms

Philosophy

My experience with my ambitious application has proven that other (maintained) form builder addons either do too much, or are hard to customize. So I created ember-do-forms because it assumes very little about my form needs.

The basic idea for ember-do-forms is simple: assume as little as possible about my HTML and CSS structure, while providing some syntactic sugar for the icky parts.

For example, should forms validate my inputs? I'd argue that forms are just UX glue for your data, so forms shouldn't do that. Still I'd like validation UX (CSS, text, etc) to be handled by the form builder because it's a big chunk of boilerplate.

Another icky part is customisation, which most other form builder addons fail short on in varying degrees.

Features

* Extremely easy to customize, thanks to contextual components.
* Bare minimum HTML with no CSS by default. Use it with any CSS framework you like.
* Binds error and success classes (if found) on a field focusOut or just before submit. Works with ember-cp-validations by default. ember-changeset-validations works too with a small configuration tweak.
* Uses ember-one-way-controls under the hood for controls. But easily extensible with any control type.
* Fully compatible with ember-test-selectors.

Table of contents

1. Usage
* Basic Usage
* Input field
* Checkbox field
* CSS customizations
* Component block form
* Test selectors
* Component customizations
2. Configuration
3. Contributing
4. Credits

Usage

#### Basic usage
``hbs
{{#do-form object submit=(action 'saveTask') as |form|}}

{{#form.do-field propertyName as |field|}}
{{field.do-label labelText}}
{{field.do-control controlType}}
{{field.do-feedback}}
{{field.do-hint hintText}}
{{/form.do-field}}

{{form.input-field propertyName controlType='email' label='Label' hint='Hint'}}

Save
{{/do-form}}
`
* do-form is just a component that wraps components
* object is the object the form binds to. It's the only positional param.
* propertyName is the property the field binds to on the object.
* labelText is the text to display for the label
* controlType is the type of control to render. Valid values are textarea, select, or a valid value for the HTML input type attribute. For example {{field.do-control controlType='checkbox'}} will render a and {{field.do-control controlType='select'}} will render a .
* submit pass in any action you want there. Or not, because it isn't required. Works great with ember-concurrency!
* {{do-feedback}} shows the validation error message if it exists. It is bound by default to field.errorMessage.
* {{do-hint}} shows any hint text you want via the hintText parameter.
* use any type of button you want. Use a bare , use it with ember-async-button or do it with style.

#### Input field
You can also use the {{ember-do-forms/input-field}} component to combine all of the goodness of the {{do-field}} component (and its contextual components) into a single line:

`hbs
{{#do-form object submit=(action 'saveTask') as |form|}}
{{form.input-field 'lastName' label='Last Name' hint='First name followed by last name'}}

Save
{{/do-form}}
`

If you want to skip labels and hints, just omit the label and hint arguments.

Also the classNames of its rendered sub-components can be modified using labelClasses, controlClasses, feedbackClasses and hintClasses.

#### Checkbox field
Same idea as the {{ember-do-forms/input-field}} component but providing some syntactic sugar for checkboxes.

`hbs
{{#do-form object as |form|}}
{{form.checkbox-field 'profileVisible' label='Profile visible' hint='Make your profile visible for the rest of the world?'}}
{{/do-form}}
`

If you want to skip the hint, just omit the hint argument. The same classNames that can be applied to the input-field also apply to the checkbox-field.

#### CSS customizations
You can customize the rendered CSS by modifying the default config. But you can also customize classes by individual component.

`hbs
{{#do-form user classNames='my-custom-form-class' as |form|}}

{{#form.do-field 'fullName' classNames='my-custom-field-class' as |field|}}
{{field.do-label 'fullName' classNames='my-custom-label-class'}}
{{field.do-control classNames='my-custom-control-class'}}
{{field.do-feedback classNames='my-custom-feedback-class'}}
{{field.do-hint 'First name, followed by last name' classNames='my-custom-hint-class'}}
{{/form.do-field}}

{{/do-form}}
`

#### Component block form
You can modify the contents of a field easily. Below there is a Bootstrap 4 custom checkbox for example. The default tagName for a field is

.
`hbs
{{#do-form user as |form|}}

{{#form.do-field 'profileVisible' classNames='form-group' as |field|}}
{{#field.do-label classNames='custom-control custom-checkbox'}}
{{field.do-control 'checkbox' classNames='custom-control-input'}}

Profile visible?
{{/field.do-label}}
{{field.do-hint 'Check this to make your profile visible' classNames='form-text text-muted'}}
{{/form.do-field}}

{{/do-form}}
`

You can also modify the content of the {{do-control}} component. Use whatever you like, the context has access to id, value and validationClass, so your custom control will just work™. The default tagName is ''.
`hbs
{{#do-form user as |form|}}

{{#form.do-field 'customValue' as |field|}}
{{field.do-label 'Custom Field'}}
{{#field.do-control as |context|}}



{{/field.do-control}}
{{field.do-feedback}}
{{/form.do-field}}

{{/do-form}}
`

The {{do-feedback}} component can be easily customized as well. Just pass a block and it will have access to the error message, and displays only if there is one. The caveat here is that the component tag name should only be configured via wrapperTagName, and the reason is that this component should be hidden unless an error message is present. The default wrapperTagName is