search

AmpersandJS / ampersand-select-view

Select field for ampersand-form-views
MIT License
11 stars 26 forks source link

readme

ampersand-select-view

Lead Maintainer: Christopher Dieringer (@cdaringe)

overview

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

install

npm install ampersand-select-view

Part of the Ampersand.js toolkit for building clientside applications.

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:

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:

  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>

You may SelectView.extend({ template: ...}) to create a View definition with a more permanent default template of your liking as well.

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,
                // specify tab index for usability
                tabindex: 1,
            }),
            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] ],
                tabindex: 2,
            }),
            new SelectView({
                name: 'option',
                parent: this,
                // define groupOptions to generate <optgroup> elements. Pass it an array of
                // Objects, each object will become an <optgroup> with groupName being the
                // <optgroup>'s name and options being an array (either of strings or array, see
                // previous two examples) that will become the <option>s under that <optgroup>
                groupOptions: [
                  {
                    groupName: "Options 1",
                    options: [ ['1', 'Option 1'], ['2', 'Option 2'], ['3', 'Option 3', true] ]
                  },
                  {
                    groupName: "Options 2",
                    options: [ ['a', 'Option A'], ['b', 'Option B'], ['c', 'Option C', true] ]
                  }
                ],
                tabindex: 3,
            }),
            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,
                tabindex: 4,
            })
        ];
    }
});

gotchas

browser support

testling badge

changelog

credits

Originally designed & written by @philip_roberts.

license

MIT