ampersand-multiselect-view
v0.0.7
Published
A view module for intelligently rendering and validating multiple selectbox input. Works well with ampersand-form-view. Based off of ampersand-select-view.
Downloads
94
Maintainers
Readme
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
clear() - [Function] - returns this
Alias to calling setValue(null, true)
. Unselects all options.
reset() - [Function] - returns this
Sets the selected option and view value to the original option value provided during construction.
setValue([value, skipValidationMessage]) - [Function] - returns this
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.
constructor - [Function] new MultiSelectView([options])
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:
<label class="select">
<span data-hook="label"></span>
<select multiple="multiple"></select>
<span data-hook="message-container" class="message message-below message-error">
<p data-hook="message-text"></p>
</span>
</label>
example
var FormView = require('ampersand-form-view');
var MultiSelectView = require('ampersand-multiselect-view');
module.exports = FormView.extend({
fields: function () {
return [
new MultiSelectView({
label: 'Pick some colors!',
// actual field name
name: 'color',
parent: this,
// you can pass simple string options
options: ['blue', 'orange', 'red'],
// you can specify that they have to pick at least one
required: true
}),
new MultiSelectView({
name: 'option',
parent: this,
// you can also pass array, first is the value, second is used for the label
// and an optional third value can used to disable the option
options: [ ['a', 'Option A'], ['b', 'Option B'], ['c', 'Option C', true] ]
}),
new MultiSelectView({
name: 'model',
parent: this,
// you can pass in a collection here too
options: collection,
// and pick some item from the collection as the selected ones
value: [collection1.at(2), collection1.at(5)],
// here you specify which attribute on the objects in the collection
// to use for the value returned.
idAttribute: 'id',
// you can also specify which model attribute to use as the title
textAttribute: 'title',
// you can also specify a boolean model attribute to render items as disabled
disabledAttribute: 'disabled',
// here you can specify if it should return the selected model(s) from the
// collection, or just the id attribute(s). defaults `true`
yieldModel: false
})
];
}
});
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