https://github.com/kylefarris/ampersand-multiselect-view
A view module for intelligently rendering and validating multiple select box input. Works well with ampersand-form-view. Based off of ampersand-select-view.
https://github.com/kylefarris/ampersand-multiselect-view
Last synced: about 1 year ago
JSON representation
A view module for intelligently rendering and validating multiple select box input. Works well with ampersand-form-view. Based off of ampersand-select-view.
- Host: GitHub
- URL: https://github.com/kylefarris/ampersand-multiselect-view
- Owner: kylefarris
- License: mit
- Created: 2015-07-20T17:58:06.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2017-04-07T21:20:14.000Z (about 9 years ago)
- Last Synced: 2025-03-03T10:25:55.915Z (over 1 year ago)
- Language: JavaScript
- Size: 31.2 MB
- Stars: 2
- Watchers: 3
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# ampersand-multiselect-view
Lead Maintainer: [Kyle Farris (@kylefarris)](https://github.com/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](http://ampersandjs.com) 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 form
- `name`: the ``'s `name` attribute's value. Used when reporting to parent form
- `parent`: parent form reference
- `options`: 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 ``. `value` **must** be a members of the `options` 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 `` ``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 by `SelectView.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 its `idAttribute` 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](#constructor---function-new-selectviewoptions) options hash. Technically, all you must provided is a `` element. However, your template may include the following under a single root element:
1. An element with a `data-hook="label"` to annotate your select control
1. An `` element to hold your `options` with the `multiple` or `multiple="multiple"` attribute.
1. An element with a `data-hook="message-container"` to contain validation messages
1. An element with a `data-hook="message-text"` nested beneath the `data-hook="message-container"` element to show validation messages
Here's the default template for reference:
```html
```
## example
```javascript
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)](https://github.com/cdaringe).
## contributing
Do it. This is still experimental--I can use all the help I can get!
## license
MIT