ampersand-multiselect-view
Lead Maintainer: Kyle Farris (@kylefarris)
overview
A view module for intelligently rendering and validating selectbox input. Works well with ampersand-form-view. Based off of ampersand-select-view.
install
npm install ampersand-multiselect-view
Part of the Ampersand.js toolkit for building clientside applications.
API Reference
this
clear() - [Function] - returns Alias to calling setValue(null, true)
. Unselects all options.
this
reset() - [Function] - returns Sets the selected option and view value to the original option value provided during construction.
this
setValue([value, skipValidationMessage]) - [Function] - returns Sets the selected options to those which match the provided value(s). Updates the view's .value
accordingly. MultiSelectView will error if no matching options exist.
new MultiSelectView([options])
constructor - [Function] options
general options
autoRender
: [default:false
] generally, we leave rendering of this FieldView to its controlling formname
: the<select>
'sname
attribute's value. Used when reporting to parent formparent
: parent form referenceoptions
: array/collection of options to render into the select box[el]
: element if you want to render the view into[template]
: a custom template to use (see 'template' section, below, for more)[required]
: [default:false
] field required[eagerValidate]
: [default:false
] validate and show messages immediately. Note: field will be validated immediately to provide a true.valid
value, but messages by default are hidden.[value]
: initial value(s) (array) for the<select>
.value
must be a members of theoptions
set.
label & validation options
[label]
: [default:name
value] text to annotate your select control[invalidClass]
: [default:'select-invalid'
] class to apply to root element if invalid[validClass]
: [default:'select-valid'
] class to apply to root element if valid[requiredMessage]
: [default:'Selection required'
] message to display if invalid and required
collection option set
If using a collection to produce <select>
<option>
s, the following may also be specified:
[disabledAttribute]
: boolean model attribute to flag disabling of the option node[idAttribute]
: model attribute to use as the id for the option node. This will be returned bySelectView.prototype.value
[textAttribute]
: model attribute to use as the text of the option node in the select box[yieldModel]
: [default:true
] if options is a collection, yields the full model rather than just itsidAttribute
to.value
When the collection changes, the view will try and maintain its currently .value
. If the corresponding model is removed, the <select> control will default to the 0th index <option> and update its value accordingly.
custom template
You may override the default template by providing your own template string to the constructor options hash. Technically, all you must provided is a <select>
element. However, your template may include the following under a single root element:
- An element with a
data-hook="label"
to annotate your select control - An
<select>
element to hold youroptions
with themultiple
ormultiple="multiple"
attribute. - An element with a
data-hook="message-container"
to contain validation messages - An element with a
data-hook="message-text"
nested beneath thedata-hook="message-container"
element to show validation messages
Here's the default template for reference:
example
var FormView = ;var MultiSelectView = ; moduleexports = FormView;
browser support
changelog
- We're still on the beta version!
credits
Based considerably off of the ampersand-select-view
by Christopher Dieringer (@cdaringe).
contributing
Do it. This is still experimental--I can use all the help I can get!
license
MIT