ampersand-form-view
Lead Maintainer: Michael Garvin
overview
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
value
property that is the current value of the field. - It should also store a
value
property if passed in as part of the config/options object when the view is created. - It maintains a
valid
property that is a boolean. The parent form checks this to know whether it can submit the form or not. - It has a
name
property 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.value
has changed or thethis.valid
has changed. - When rendered by a form-view, the form view creates a
parent
property that is a reference to the containing form view. - It can optionally also define a
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.
install
npm install ampersand-form-view
Example: Defining a 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 viewvar View = ;var FormView = ;var InputView = ; var AwesomeFormView = View; var awesomeFormView = ;awesomeFormView;
FormView.extend(options)
FormView Options 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
fields
array. UseautoAppend: false
in conjuction withel: yourElement
in order to use your own form layout.
- Adds new nodes for all fields defined in the
fields
: array- Array of
FieldView
s. IfautoAppend
is 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
getData
and 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
autoAppend
istrue
). - 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
=======
API Reference
formView.setValue(name, value)
setValue Sets the provided value on the field matching the provided name. Throws when invalid field name specified.
formView.getValue(name)
getValue Gets the value from the associated field matching the provided name. Throws when invalid field name specified.
formView.setValues([values])
setValues 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 = { return name: 'startsTrue' value: true name: 'startsFalse' value: false ; };myForm; // bulk update form valuesmyForm;
formView.reset()
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()
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.
Properties
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
Verbose forms
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.
Example
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 = fields: name: 'name.first' value: 'Michael' name: 'name.last' value: 'Mustermann' name: 'phone[0].type' value: 'home' name: 'phone[0].number' value: '1234567' name: 'phone[1].type' value: 'mobile' name: 'phone[1].number' value: '7654321' ; console;// {// name: {first: 'Michael', last: 'Mustermann'},// phone: [// {type: 'home', number: '1234567'},// {type: 'mobile', number: '7654321'}// ]// }
Special Events
submit
- triggered when a form is submitted. Returns thedata
of the form as the only argument
Changelog
changelog
- 6.0.0 - Upgrade to &-view 9.x
- 5.1.0 - Add
submit
andvalid
events - 5.0.0 - Extend
ampersand-view
to 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.
credits
Created by @HenrikJoreteg
license
MIT