ampersand-multifield-view
purpose
A view module for intelligently applying an hierarchy to form data. MultifieldView
gathers field views into a collection that can be treated as a single field view whose value is an object with keys and values corresponding to its sub-views' names and values. Works well with ampersand-form-view.
It does the following:
- Accepts a collection of views that implement the form field view conventions.
- Acts as a form field view and passes information about its fields to the parent form
install
npm install ampersand-multifield-view
example
var MultiFieldView = ;var InputView = ; var AddressFieldView = MultiFieldView; moduleexports = AddressFieldView
var FormView = ;var AddressFieldView = ; moduleexports = FormView;
API Reference
AmpersandMultiFieldView.extend({ })
extend Because this view is based on ampersand-state, it can be extended the same way to create your own MultiFieldView
class.
Note: If you want to add your own version of a function (such as initialize()
), remember you are overriding MultiFieldView's own functions. Thus, you should call the parent's functions manually:
var AmpersandMultiFieldView = ; var MyCustomMultiField = AmpersandMultiFieldView;
new AmpersandMultiFieldView({opts})
constructor/initialize When creating an instance of MultiFieldView
, you can pass initial values to be set to the state.
opts
name
: the field'sname
attribute's value. Used when reporting to parent form.label
: the label for the views.fields
: an array of form-vield viewsvalue
: initial value to pass on to the MultiFieldView's forms. An object where the keys match the fields'name
attributes.template
: a custom template to use.tests
(default[]
): validation functions to run on the fields' values. See below.beforeSubmit
: function called by ampersand-form-view during submit.validCallback
: function called whenever thevalid
property's value changes.
AmpersandMultiFieldView.render()
render Renders the MultiFieldView. Called automatically when used within a parent ampersand-form-view.
AmpersandMultiFieldView.reset()
reset Reset the fields' values to their starting value
AmpersandMultiFieldView.clear()
clear Clears the fields' values
AmpersandMultiFieldView.template
template This can be customized by using extend
or by passing in a template
on instantiation.
It can be a function that returns a string of HTML or DOM element -- or just an HTML string.
The resulting HTML should contain the following hooks:
- an element with a
data-hook="label"
attribute. - an element with a
data-hook="multifields"
attribute where the fields are inserted.
AmpersandMultiFieldView.tests
tests The test functions will be called in the context of the MultifieldView and receive the MultiFieldView's value
.
The tests should return an error message if invalid and return either a falsy value or not return otherwise.
It's recommended that tests validatate the relationship of the fields. As an example, validate that when the address field has a value, that the zip code field does as well.
var AmpersandMultiFieldView = ; var MyCustomMultiField = AmpersandMultiFieldView;
AmpersandMultiFieldView.beforeSubmit()
beforeSubmit This function is called by ampersand-form-view during submit and calls its fields' beforeSubmit
functions.
Note: if you want to write your own version, be sure to call the parent to ensure the MultiFieldView's fields' beforeSubmit
functions are calledd.
var AmpersandMultiFieldView = ; var MyCustomMultiField = AmpersandMultiFieldView;
AmpersandMultiFieldView.validCallback()
validCallback A function that gets called, if it exists, when the field first loads and anytime the form changes from valid to invalid or vice versa.
License
MIT