ampersand-select-view [source]

Lead Maintainer: Christopher Dieringer (@cdaringe)

overview

A view module for intelligently rendering and validating selectbox input. Works well with ampersand-form-view.

4.0.0 Release Plan

The upcoming release 4.x is intended to migrate ampersand-select-view to an extension of ampersand-view. Due to the refactor, merging changes becomes difficult as the module will exhibit a different structure. As such, all PRs, including bugfixes, should be submitted by April 20, 2015!

API Reference

clear() - [Function] - returns this

Alias to calling setValue(null, true). Sets the selected option to either the unselectedText option or a user defined option whose value is null. Be mindful that if no unselectedText or null option exists, the view will error.

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 option to that which matches the provided value. Updates the view's .value accordingly. SelectView will error if no matching option exists. null,undefined, and''` values will preferentially select unselectedText if defined.

constructor - [Function] new SelectView([options])

options

general options
label & validation options
collection option set

If using a collection to produce <select> <option>s, the following may also be specified:

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:

  1. An element with a data-hook="label" to annotate your select control
  2. An <select> element to hold your options
  3. An element with a data-hook="message-container" to contain validation messages
  4. 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:

<label class="select">
    <span data-hook="label"></span>
    <select></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 SelectView = require('ampersand-select-view');


module.exports = FormView.extend({
    fields: function () {
        return [
            new SelectView({
                label: 'Pick a color!',
                // actual field name
                name: 'color',
                parent: this,
                // you can pass simple string options
                options: ['blue', 'orange', 'red'],
                // if included this will add option for an unselected state
                unselectedText: 'please choose one',
                // you can specify that they have to pick one
                required: true
            }),
            new SelectView({
                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 SelectView({
                name: 'model',
                parent: this,
                // you can pass in a collection here too
                options: collection,
                // and pick an item from the collection as the selected one
                value: collection1.at(2),
                // 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 from the
                // collection, or just the id attribute.  defaults `true`
                yieldModel: false
            })
        ];
    }
});

gotchas

contributing

Due to CI browser testing issues (1, 2), a PR must receive two +1s from the core-team or maintainer, each with mention that x-browser tests pass in the PR branch (i.e. testem ci);