ui-bs-button-choice

A Bootstrap button selector for both radio and checkbox scopes

Usage

Provides a familiar Bootstrap styled button choice bar as an Ember component:

Basic syntax is:

 {{ui-bs-button-choice choices=choices selected=selected}}

To make things a bit less wordy you can now use the following shortcuts:

 {{ui-button-checkbox}} - checkbox style state-machine
 {{ui-button-radio}} - radio styled state-machine

Note: if you're not using HTMLbars yet you'll need to stick with NPM version 0.0.8 which does not include these shortcuts

Dependencies

You'll need to include the Bootstrap CSS and the button.js JS module from Bootstrap.

Parameters / API

The specific properties available to this control include:

Core Content Properties

| Variable | Type | Default | Description | | -------- | ---- | :-----: | ----------- | | choices | string / array / hash | | The buttons which will be displayed. If a string is passed in then it will be split into an array using , as a delimiter| | selected | string / array | null | The id of the actively selected button (in the case of a "checkbox" control this would be an array of strings) | | type | string | 'radio' | Specifies whether the control should act like a "radio button" or "checkbox" selector |

Other Properties

| Variable | Type | Default | Description | | -------- | ---- | :-----: | ----------- | | color | string | 'default' | Allows specifying what "color class" should be applied to the buttons. By default you can use the Bootstrap supplied [default, primary, info, warning] but you can add your own class definitions too if its needed| | size | string | 'default' | Allows specifying the size of the buttons. Valid sizes are [default, large, small, tiny] | | labelProp | string | name| In the case an array of hashes has been passed in this property distinguishes which attribute should be considered the display property | | valueProp | string | id | In the case an array of hashes has been passed in this property distinguishes which attribute should be considered the value property | | canBeNull | boolean | mixed | Specifies whether a 'null' value is considered acceptable; the default for a radio control is false but for a checkbox it is true | | missingChoicesText | string | 'no choices available' | Allows a message to be created if no choices are provided |

Events

| Variable | Type | Default | Description | | -------- | ---- | :-----: | ----------- | | changeEvent | function(object) | | Allows containing view to be notified whenever a change to the control has taken place. Action will send an action object with the current list of selected ID(s), the selectedObject with full hash properties, and a trigger which indicates what caused the change; values are [clicked, external]|

Example App

You can checkout a running version of the dummy app which shows a large number of uses of this control:

Demo App

Dependencies

This UI control depends on Twitter Bootstrap 3.x CSS as well as the Bootstrap button.js javascript. Installing this addon does not install this for you … we leave that in your very capable hands. If your hands aren't that capable then the basic idea is to:

1. Install Bootstrap with Bower (you'll need to choose the traditional repo or the SASS repo), in any case let's assume traditional for demonstration purposes:

   bower install bootstrap --save

2. Add assets in your Brocfile:

   app.import('bower_components/bootstrap/dist/css/bootstrap.css');
   app.import('bower_components/bootstrap/dist/js/bootstrap.js');

Of course you might just decide to install a add-on that does all this nonsense reducing the documentation in this section to needless lip flapping.

Addon Installation

• change directories to your project folder
• at terminal: npm install ui-bs-button-choice --save-dev

Assuming you have met the dependencies stated above you are now ready to start using the control in your project. Happy trails.

Contributing

We're open to your creative suggestions but please move past the "idea" stage and send us a PR so we can incorporate your ideas without killing ourselves. :)

License

Copyright (c) 2014 LifeGadget Ltd

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.