emberx-select

by adopted-ember-addons

adopted-ember-addons / emberx-select

Select component for Ember based on the native html select element.

201 Stars 79 Forks Last release: about 5 years ago (v2.0.0) MIT License 294 Commits 26 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

emberx-select

npm version Ember Observer Score CircleCI

A select component based on the native html select.

We've tried other select components, and were missing the reliability, maintainability, and accessbility of the native html

.
 is a drop-in component to let you use any
object for your selectable options. You can use it out of the box, or
as a building block of something more ambitious.

The goal of

 is to let you see how it works and style it
right in your template, rather than passing in a ball of configuration
or wrapping a hard-coded, inaccessible jQuery plugin.

Installation

ember install emberx-select

Usage

By allowing arbitrary html to appear in the template of the select element, you can use it just like you would normally. This means things like having

 tags inside your select, or even plain
old 
 elements to represent things like empty values.

 thinly wraps a native 
 element so that it can be object
and binding aware. It is used in conjuction with the 
x-option
component to construct select boxes. E.g.

Ember >= 3.4:

handlebars

  Fred Flintstone
  Bob Newhart

Ember < 3.4:

handlebars
{{#x-select value=bob on-change=(action "selectPerson") as |xs|}}
  {{#xs.option value=fred}}Fred Flintstone{{/xs.option}}
  {{#xs.option value=bob}}Bob Newhart{{/xs.option}}
{{/x-select}}

The options are always up to date, so that when the object bound to

value
changes, the corresponding option becomes selected.

Whenever the select tag receives a change event, it will fire

onChange
action. This is the default action that is fired but not the only event that's available.

Contextual Components

As of version 3.0.0,

emberx-select
will only support contextual components. This means you will have to use Ember 2.3 or higher. Using contextual components allows
emberx-select
to skip some potentially expensive DOM traversals. Now the options can register through data rather than through the DOM.
  Active
  Inactive

Multiselect

 supports the 
multiple
option. This means you can pass an array as its value, and it will set its selections directly on that array.
 Fred Flintstone
 Bob Newhart
 Andrew WK

The selections array will be initialized to an empty array if not present.

Actions and Action Arguments

All of

s actions are closure actions. This means you must use
the 
action
helper (i.e.
@onClick={{action "onClick"}}
). The function that is dispatched by
 whenever the event fires has a function
signature of:
/**
* @param {Object} value - the value selected by the user.
* @param {Object} event - the DOM event of the action
*/
function (value, event) {
  // action body...
}

Most of the time all you need is the value that has been selected, but sometimes your action requires more context than just that. In those cases, you can pass any arguments you need from the template. For example:

  Nothing
  Something

then, inside your action handler:

import Controller from '@ember/controller';

export default Controller.extend({ actions: { didMakeSelection(value, event, isXSelectRequired) { if (!value & isXSelectRequired) { this.set('error', 'You must fill out this field'); } else { this.set('selection', value); } } } });

 provides other actions that fire on different event
types. These actions follow the HTML input event naming convention.

onBlur

onBlur
fires anytime the
blur
event is triggered on the

component. When the action fires it sends two arguments: the value,
the DOM event.

onFocusOut

onFocusOut
fires anytime the
focusOut
event is triggered on the

component. When the action fires it sends two arguments: the value,
the DOM event.

onClick

onClick
fires when
 is clicked. When the action fires it
sends two arguments: the value, the DOM event.

onDisable (x-option)

onDisable
fires when x-option detects a change to its
disabled
attribute. When the action fires it sends two arguments: the value and if it is disabled (boolean).

Test Helper

 4.0 ships with an entirely new test helper that goes
beyond just allowing you to select an option. It allows you to
interact with your 
 element in all different ways. For
example, if you need to assert your first option is 
disabled
or not:
expect(xselect.options(0).isDisabled).to.equal(true);

Under the hood this new test helper is using a BigTest Interactor. Interactors allow you to think about how you're going to interact with the DOM and abstract that into composable & immutable containers. Interactors are similar to page objects, but for components.

Using the test helper

Import the select interactor:

// you can name the import whatever you want
import XSelectInteractor from 'emberx-select/test-support/interactor';

At the top of your test file you need to initialize the interactor. This should go at the top most part of your test so it's available to all tests in the file. Here's an example in Qunit:

module("Acceptance | Your Test", function(hooks) {
  let xselect = new XSelectInteractor('.selector-for-select');
  setupApplicationTest(hooks);
  // ...
});

Once you have initialized the interactor, you're ready to start selecting!

module("Acceptance | Your Test", function(hooks) {
  let xselect = new XSelectInteractor('.selector-for-select');
  // ...

test('Selecting an option', async (assert) => { await xselect .select('Fred Flintstone') .when(() => assert.equal(xselect.options(0).isSelected, true));

// for a multiselect pass an array
// await xselect
//   .select(['Fred Flintstone', 'Bob Newhart'])
//   .when(() =&gt; assert.equal(xselect.options(0).isSelected, true));;

}); });

You can do more than just select options with this helper.

module('Acceptance | Your Test', function(hooks) {
  let xselect = new XSelectInteractor('.selector-for-select');
  // ...

test('Selecting an option', async (assert) => { await xselect.select('Fred Flintstone') // assert the change is has happened. It's important to make the // assertion inside of when, so tests are not flakey. .when(() => assert.equal(xselect.options(0).isSelected, true)); }); });

In this example we're using

@bigtest/convergence#when
to assert. The TL;DR of convergence is it basically converges on the state of the DOM. It checks every 10ms until the assertion is truthy. Once it's truthy the test passes. You can read more about convergences here

You don't need to include

@bigtest/convergence
in your project, it's already a dependency of
@bigtest/interactor
and interactor provides all of the convergence methods to you (like
when
and
do
).

This is the full interactor which has all of the attributes or interactions for an

HTMLSelectElement
.
const xSelectInteractor = interactor({
  hasFocus: is(':focus'),
  name: attribute('name'),
  form: attribute('form'),
  title: attribute('title'),
  size: attribute('size'),
  tabindex: attribute('tabindex'),
  isDisabled: property('disabled'),
  isRequired: property('required'),
  isAutofocus: property('autofocus'),

options: collection('option', { name: attribute('name'), value: property('value'), title: attribute('title'), isSelected: property('selected'), isDisabled: property('disabled'), hasSelectedClass: hasClass('is-selected') }) });

Example usage might be:

  Hello world!

let xselect = new XSelectInteractor('.x-select');

xselect.options(0).value; //=> "hello world" xselect.options(0).text; //=> "Hello World!" xselect.name; //=> "World" xselect.form; //=> null xselect.hasFocus; //=> false xselect.tabIndex; //=> 0

If you want to see this test helper used in many different ways look no further than this addons test suite!

Extending the XSelect interactor

If you want to add custom interactions to your

 interactor,
you can do so by importing it into the custom interactor you want to
create, and extend it:
import XSelectInteractor from 'emberx-select/test-support/interactor';
import { clickable } from '@bigtest/interactor';

@XSelectInteractor.extend class NewInteractor { submitForm = clickable('[data-test-form-submit]');

fillAndSubmit(value) { return this.select(value).submitForm(); } }

EmberX

emberx-select is part of the "missing components of ember" collectively known as emberx:

Other Resources

Running Tests

  • ember test
  • ember test --server

Release Process

Every commit to master results in a build and push to the demo application at http://emberx-select.netlify.com

Npm releases use semver and happen at the project owner's discretion.

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms, which can be found in the

CODE_OF_CONDUCT.md
file in this repository.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.