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:
- It maintains a
valueproperty that is the current value of the field. - It should also store a
valueproperty if passed in as part of the config/options object when the view is created. - It maintains a
validproperty that is a boolean. The parent form checks this to know whether it can submit the form or not. - It has a
nameproperty that is a string of the name of the field. - It reports changes to its parent when it deems appropriate by calling
this.parent.update(this)**note that it passes itsef to the parent. You would typically do this when thethis.valuehas changed or thethis.validhas changed. - When rendered by a form-view, the form view creates a
parentproperty that is a reference to the containing form view. - It can optionally also define a
beforeSubmitmethod. 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();Standard view conventions apply, with the following options added:
autoRender: boolean (default: true)- Render the form immediately on construction.
autoAppend: boolean (default: true)- Adds new nodes for all fields defined in the
fieldsarray. UseautoAppend: falsein conjuction withel: yourElementin order to use your own form layout.
- Adds new nodes for all fields defined in the
fields: array- Array of
FieldViews. IfautoAppendis true, nodes defined by the view are built and appended to the end of the FormView.
- Array of
submitCallback: function- Called on form submit
validCallback: function- 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.
clean: function- Lets you provide a function which will clean or modify what is returned by
getDataand passed tosubmitCallback.
- Lets you provide a function which will clean or modify what is returned by
fieldContainerEl: Element | string- Container to append fields to (when
autoAppendistrue). - This can either be a DOM element or a CSS selector string. If a string is passed, ampersand-view runs
this.query('YOUR STRING')to try to find the element that should contain the fields. If you don't supply afieldContainerEl, 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 tothis.el.
- Container to append fields to (when
=======
Sets the provided value on the field matching the provided name. Throws when invalid field name specified.
Gets the value from the associated field matching the provided name. Throws when invalid field name specified.
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
});Calls reset on all fields in the form that have the method. Intended to be used to set form back to original state.
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 }format
For 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 thedataof the form as the only argument
- 6.0.0 - Upgrade to &-view 9.x
- 5.1.0 - Add
submitandvalidevents - 5.0.0 - Extend
ampersand-viewto add state, addssetValues(),setValue(), &getValue(). Change to not render() during construction by default. - 4.0.0 - (skipped)
- 3.0.0 - Initialize prior to render, and permit
autoRender: false - 2.2.3 - Adding
reset. Starting in on building API reference.
Created by @HenrikJoreteg
MIT
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent