-
Notifications
You must be signed in to change notification settings - Fork 9
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Lisa Backer
committed
Oct 30, 2020
1 parent
a70bde3
commit 815b446
Showing
1 changed file
with
272 additions
and
20 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,38 +1,290 @@ | ||
ember-one-way-select | ||
============================================================================== | ||
# ember-one-way-select [![npm version](https://badge.fury.io/js/ember-one-way-select.svg)](https://badge.fury.io/js/ember-one-way-select) [![Ember Observer Score](http://emberobserver.com/badges/ember-one-way-select.svg)](http://emberobserver.com/addons/ember-one-way-select) | ||
|
||
[Short description of the addon.] | ||
**[ember-one-way-select is built and maintained by DockYard, contact us for expert Ember.js consulting](https://dockyard.com/ember-consulting)**. | ||
|
||
## Installing the addon | ||
|
||
Compatibility | ||
------------------------------------------------------------------------------ | ||
``` | ||
ember install ember-one-way-select | ||
``` | ||
|
||
* Ember.js v3.16 or above | ||
* Ember CLI v2.13 or above | ||
* Node.js v10 or above | ||
## How to use the select component | ||
|
||
### Basics | ||
|
||
Installation | ||
------------------------------------------------------------------------------ | ||
The basic invocation of the component looks like: | ||
|
||
```hbs | ||
{{one-way-select selectedValue | ||
options=options | ||
update=(action (mut selectedValue)) | ||
}} | ||
``` | ||
ember install ember-one-way-select | ||
|
||
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: | ||
|
||
```hbs | ||
{{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: | ||
|
||
```hbs | ||
{{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: | ||
|
||
```hbs | ||
{{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: | ||
|
||
```hbs | ||
{{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: | ||
|
||
```js | ||
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: | ||
|
||
```hbs | ||
{{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`. | ||
|
||
```js | ||
data = [ | ||
{ id: 'EN', label: 'English' }, | ||
{ id: 'ES', label: 'Spanish' }, | ||
{ id: 'DE', label: 'German' } | ||
]; | ||
``` | ||
|
||
```hbs | ||
{{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 | ||
|
||
Usage | ||
------------------------------------------------------------------------------ | ||
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. | ||
|
||
[Longer description of how to use the addon in apps.] | ||
```js | ||
const countries = ['france', 'germany', 'spain']; | ||
``` | ||
|
||
```hbs | ||
{{#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. | ||
|
||
```js | ||
Model.extend({ | ||
username: attr('string'), | ||
role: attr('string') | ||
}); | ||
``` | ||
|
||
```hbs | ||
{{#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. | ||
|
||
```hbs | ||
{{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: | ||
|
||
```hbs | ||
{{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. | ||
|
||
```hbs | ||
{{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. | ||
|
||
```hbs | ||
{{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: | ||
|
||
```js | ||
[ | ||
{ | ||
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 | ||
|
||
|
||
Contributing | ||
------------------------------------------------------------------------------ | ||
For more information on using ember-cli, visit [http://www.ember-cli.com/](http://www.ember-cli.com/). | ||
|
||
See the [Contributing](CONTRIBUTING.md) guide for details. | ||
## Legal | ||
|
||
[DockYard](http://dockyard.com/ember-consulting), Inc © 2016 | ||
|
||
License | ||
------------------------------------------------------------------------------ | ||
[@dockyard](http://twitter.com/dockyard) | ||
|
||
This project is licensed under the [MIT License](LICENSE.md). | ||
[Licensed under the MIT license](http://www.opensource.org/licenses/mit-license.php) |