ember-one-way-select
ember-one-way-select is built and maintained by DockYard, contact us for expert Ember.js consulting.
Installing the addon
ember install ember-one-way-select
How to use the select component
Basics
The basic invocation of the component looks like:
This will render a <select>
element with options taken from the options
parameter and if the options contain selectedValue
, then that option will be
marked as selected.
The options
parameter can either be an array or a string of words separated by
spaces.
The action passed to the update
parameter will be called whenever the user
selects an option.
The examples here pass the value
attribute as a positional parameter, but you
can also pass value
as an ordinary parameter:
Select element attributes
The one-way-select component supports binding all attributes a <select>
element
can have.
An example:
Adding a blank or prompt option
You can set the includeBlank
parameter to true
if you want a blank option as
the first option:
If you want to have the first option to have a placeholder text you can pass a string to the prompt parameter instead:
Set the promptIsSelectable
to true
if you want the user to be able to select
the blank/prompt option.
Working with objects instead of strings
Let's say you have an array filled with instances of the following user
model:
Model.extend({
username: attr('string'),
email: attr('string')
});
If you want to render a select with all the users with the option's labels being
the username of the user, then you can set the optionValuePath
and the
optionLabelPath
parameters with the apropriate values:
When an option is selected then update will receive the full object as
parameter, not just the value specified by optionValuePath
.
If you do want to use a specific attribute of the object, then there is
optionTargetPath
, this behaves similarly to optionValuePath
except that the
selected value is equals to one of values of the property behind
optionTargetPath
.
data = [
{ id: 'EN', label: 'English' },
{ id: 'ES', label: 'Spanish' },
{ id: 'DE', label: 'German' }
];
In this case, when a user selects a different language, the value of
selectedLanguage
gets updated to the id
of the object (e.g. EN
).
Block expression / optionComponent
Sometimes you may want to use handlebars helpers to express the label. In this
case you may use one-way-select
as a block expression. The first block
parameter is an option object/value. The second parameter is option index. If
option groups are used, the index will be scoped to the group and the third
parameter will be the group index.
const countries = ['france', 'germany', 'spain'];
It is, of course, possible to use the block expression with objects.
Model.extend({
username: attr('string'),
role: attr('string')
});
In even more extreme cases, where you feel you need to reuse the contents of the
block expression, you can pass a component to optionComponent
instead. The
component is rendered for each option and it will pass the same parameters as
are yielded to the block (option
, index
, groupIndex
) to the component.
From Ember.js 2.3 and up you can also pass a component using the component
helper:
Multiple select
Changing the one-way-select into a multiple select is as easy as setting the
multiple
parameter to true
. Please note that value should now be an array of
selected items, instead of just a single item.
Grouping options
Setting the groupLabelPath
parameter will cause all options which have the
same value on the given path to be grouped in an <optgroup>
element. The label
of the <optgroup>
element will be the value of the given path.
Optionally you can pass the options pre-grouped, the options then need to adhere to the following structure:
[
{
groupName: 'Trappist',
options: [
{ id: 1, label: 'Dubbel', type: 'Trappist' },
{ id: 2, label: 'Tripel', type: 'Trappist' }
]
},
{
groupName: 'IPA',
options: [
{ id: 3, label: 'IPA', type: 'IPA' }
]
}
]
Contributing
Installation
-
git clone
this repository npm install
bower install
Running
ember server
- Visit your app at http://localhost:4200.
Running Tests
ember test
ember test --server
Building
ember build
Compatibility
- Ember.js v3.16 or above
- Ember CLI v2.13 or above
- Node.js v10 or above
For more information on using ember-cli, visit http://www.ember-cli.com/.
Legal
DockYard, Inc © 2016