Skip to content

Commit

Permalink
restore readme
Browse files Browse the repository at this point in the history
  • Loading branch information
Lisa Backer committed Oct 30, 2020
1 parent a70bde3 commit 815b446
Showing 1 changed file with 272 additions and 20 deletions.
292 changes: 272 additions & 20 deletions README.md
View file
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 &copy; 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)

0 comments on commit 815b446

Please sign in to comment.