Completely customizable form lib for bulletproof clientside forms.
Lead Maintainer: Michael Garvin
ampersand-form-view is a wrapper view for easily building complex forms on the clientside with awesome clientside validation and UX.
It would work quite well with backbone apps or anything else really, it has no external dependencies.
At a high level, the way it works is you define a view object (by making an object that following the simple view conventions of ampersand).
That form can be given an array of field views.
These fields are also views but just follow a few more conventions in order to be able to work with our form view.
Those rules are as follows:
value
property that is the current value of the field.value
property if passed in as part of the config/options object when the view is created.valid
property that is a boolean. The parent form checks this to know whether it can submit the form or not.name
property that is a string of the name of the field.this.parent.update(this)
**note that it passes itsef to the parent. You would typically do this when the this.value
has changed or the this.valid
has changed.parent
property that is a reference to the containing form view.beforeSubmit
method. This gets called by the parent if it exists. This can be useful for stuff like a required text input that you don't want to show an error for if empty until the user tries to submit the form.npm install ampersand-form-view
Here's how you might draw a form view as a subview.
// we'll just use an ampersand-view here as an
// example parent view
var View = require('ampersand-view');
var FormView = require('ampersand-form-view');
var InputView = require('ampersand-input-view');
var AwesomeFormView = View.extend({
template: '<div><p>App form</p><form data-hook="app-edit-form"></form></div>',
render: function () {
this.renderWithTemplate();
this.form = new FormView({
autoRender: true,
el: this.queryByHook('app-edit-form'),
submitCallback: function (obj) {
console.log('form submitted! Your data:', obj);
},
// this valid callback gets called (if it exists)
// when the form first loads and any time the form
// changes from valid to invalid or vice versa.
// You might use this to disable the "submit" button
// any time the form is invalid, for example.
validCallback: function (valid) {
if (valid) {
console.log('The form is valid!');
} else {
console.log('The form is not valid!');
}
},
// This is just an array of field views that follow
// the rules described above. I'm using an input-view
// here, but again, *this could be anything* you would
// pass it whatever config items needed to instantiate
// the field view you made.
fields: [
new InputView({
name: 'client_name',
label: 'App Name',
placeholder: 'My Awesome App',
// an initial value if it has one
value: 'hello',
// this one takes an array of tests
tests: [
function (val) {
if (val.length < 5) return "Must be 5+ characters.";
}
]
})
],
// optional initial form values specified by
// {"field-name": "value"} pairs. Overwrites default
// `value`s provided in your FieldView constructors, only
// after the form is rendered. You can set form values
// in bulk after the form is rendered using setValues().
values: {
client_name: 'overrides "hello" from above'
}
});
// registering the form view as a subview ensures that
// its `remove` method will get called when the parent
// view is removed.
this.registerSubview(this.form);
}
});
var awesomeFormView = new AwesomeFormView();
awesomeFormView.render();
FormView.extend(options)
Standard view conventions apply, with the following options added:
autoRender
: boolean (default: true)
autoAppend
: boolean (default: true)
fields
array. Use autoAppend: false
in conjuction with el: yourElement
in order to use your own form layout.fields
: array
FieldView
s. If autoAppend
is true, nodes defined by the view are built and appended to the end of the FormView.submitCallback
: function
validCallback
: function
clean
: function
getData
and passed to submitCallback
.fieldContainerEl
: Element | string
autoAppend
is true
).this.query('YOUR STRING')
to try to find the element that should contain the fields. If you don't supply a fieldContainerEl
, it will first try to find an element with the selector '[data-hook~=field-container]'
. If no element for appending fields to is found, it will fallback to this.el
.=======
formView.setValue(name, value)
Sets the provided value on the field matching the provided name. Throws when invalid field name specified.
formView.getValue(name)
Gets the value from the associated field matching the provided name. Throws when invalid field name specified.
formView.setValues([values])
For each key corresponding to a field's name
found in values
, the corresponding value
will be set onto the FieldView. Executes when the the formView is rendered.
myForm = new FormView({
fields: function() {
return [
new CheckboxView({
name: 'startsTrue',
value: true
}),
new CheckboxView({
name: 'startsFalse',
value: false
}),
];
}
});
myForm.render();
// bulk update form values
myForm.setValues({
startsTrue: true, //=> no change
startsFalse: true //=> becomes true
});
formView.reset()
Calls reset on all fields in the form that have the method. Intended to be used to set form back to original state.
formView.clear()
Calls clear on all fields in the form that have the method. Intended to be used to clear out the contents of the form.
The following are FormView observables, thus emit "change" events:
valid
- the valid state of the formdata
- form field view values in { fieldName: value, fieldName2: value2 }
formatFor verbose forms used to edit nested data, you can write field names as paths. Doing so, the data
observable is nested according to the paths you specified so you can set
or save
this data to a state or collection more easily.
A form with a persons first and last name and an array of phone numbers, each of which has fields for type and number:
var form = new FormView({
fields: [
new InputView({name: 'name.first', value: 'Michael'}),
new InputView({name: 'name.last', value: 'Mustermann'}),
new InputView({name: 'phone[0].type', value: 'home'}),
new InputView({name: 'phone[0].number', value: '1234567'}),
new InputView({name: 'phone[1].type', value: 'mobile'}),
new InputView({name: 'phone[1].number', value: '7654321'})
]
});
console.log(form.data);
// {
// name: {first: 'Michael', last: 'Mustermann'},
// phone: [
// {type: 'home', number: '1234567'},
// {type: 'mobile', number: '7654321'}
// ]
// }
submit
- triggered when a form is submitted. Returns the data
of the form as the only argumentsubmit
and valid
eventsampersand-view
to add state, adds setValues()
, setValue()
, & getValue()
. Change to not render() during construction by default.autoRender: false
reset
. Starting in on building API reference.Created by @HenrikJoreteg
MIT