ember-one-way-select
v4.0.1
Published
An easy to use native select component
Downloads
4,884
Keywords
Readme
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:
{{one-way-select selectedValue
options=options
update=(action (mut selectedValue))
}}
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:
{{one-way-select
value=selectedValue
options=options
update=(action (mut selectedValue))
}}
Select element attributes
The one-way-select component supports binding all attributes a <select>
element
can have.
An example:
{{one-way-select selectedValue
disabled=isDisabled
tabindex=3
required=true
options=options
update=(action (mut selectedValue))
}}
Adding a blank or prompt option
You can set the includeBlank
parameter to true
if you want a blank option as
the first option:
{{one-way-select selectedValue
options=options
includeBlank=true
update=(action (mut selectedValue))
}}
If you want to have the first option to have a placeholder text you can pass a string to the prompt parameter instead:
{{one-way-select selectedValue
options=options
prompt="Please select one:"
update=(action (mut selectedValue))
}}
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:
{{one-way-select selectedUser
options=users
optionValuePath="id"
optionLabelPath="username"
update=(action (mut selectedUser))
}}
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' }
];
{{one-way-select selectedLanguage
options=users
optionTargetPath="id"
optionLabelPath="label"
update=(action (mut selectedLanguage))
}}
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'];
{{#one-way-select selectedCountry
options=countries
update=(action (mut selectedCountry)) as |option index|}}
{{index}} - {{loc option}}
{{/one-way-select}}
It is, of course, possible to use the block expression with objects.
Model.extend({
username: attr('string'),
role: attr('string')
});
{{#one-way-select selectedUser
options=users
optionValuePath="id"
update=(action (mut selectedUser)) as |user|}}
{{get user "username"}} ({{loc (get user "role")}})
{{/one-way-select}}
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.
{{one-way-select selectedCountry
options=countries
optionComponent="country-option"}}
From Ember.js 2.3 and up you can also pass a component using the component
helper:
{{one-way-select selectedCountry
options=countries
optionComponent=(component "country-option")}}
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.
{{one-way-select selectedUsers
options=users
multiple=true
optionValuePath="id"
optionLabelPath="username"
update=(action (mut selectedUsers))
}}
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.
{{one-way-select selectedCity
options=cities
optionValuePath="id"
optionLabelPath="name"
groupLabelPath="state"
update=(action (mut selectedCity))
}}
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 repositorynpm 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