Architecture

Architecture

This component is built using The Ember 2 Way ™ but also with a focus in composition and composability. It is also a showcase of how I think Ember components should be architectured to maximize their reusablity.

The Ember 2 Way ™

In plain English, it means that this component follows the "data down - actions up" design guidelines also known as DDAU.

  • No two way binding. None of the given properties get silently mutated.
  • Changes are propagated through actions. The user must handle that action and decide what to do.

Built with composition

Ember Power Select is built by combining existing addons/components. Each one of them focused on one simple task to create a complex piece of UI, but at the same time hides that fact and exposes itself as a single item.
Even the multiple select is built on top of the regular one.

{{power-select-multiple}}

{{power-select}}

{{basic-dropdown}}

{{#-in-element}}

Built for composability

Ember Power Select is built as as a simple skeleton that exposes some "holes" to be filled with more components to get the complete behavior. By default, those "holes" are filled with components that provide sensible defaults, but if any of the components rendered in those holes do not behave exactly as you want, you can replace them with your own.

At the moment there is a total of 7 "holes" you can fill.

  • triggerComponent: Replaces the entire trigger markup and logic.
  • selectedItemComponent: Replaces only the selected option(s) inside the trigger. By default it just yields the block given to the component.
  • beforeOptionsComponent: Contains any markup and logic displayed before the list of options (by default, a search box)
  • optionsComponent: Contains the list of options. The content of each option is the block given to the component.
  • afterOptionsComponent: Contains any markup and logic displayed after the list of options. Unused by default.
  • searchMessageComponent: Displays the "Type to search" message. By default it just displays the searchMessage.

dissection of Ember Power Select

Leave the last word to the end user

Actions exposed by the component take as little for granted as possible, and is up to you to decide what to do with each.
For that, this component's public API exposes actions like onfocus, onchange, onkeydown, onopen and onclose that allow you to decide what to do.
All those options receive the DOM event that triggered the action (if any) and the component's public API as penultimate argument, which allows you to control the component from the ouside using actions.
The component has some behavior defined for some actions, but even that behavior can be avoided by returning false from those actions, so you can decide to do something different.

You can see an extensive list of all options of the component in the next section.