Ember in Aperta

The purpose of this document

Provide an overview of Ember for newcomers
Explain why we use Ember in Aperta
Provide practical guidance on how to develop ember-based features in Aperta

What's ember?

It's this:

Now, go RTFM https://guides.emberjs.com/v2.8.0/getting-started/core-concepts/

Advantages of using Ember

leaves rendering to client. better performance, sometimes
data binding. Hassle free syncing of data from model to view.
decoupling of display from api.
"omakase" (irritating word from the rails ecosystem to mean "batteries included")
strong conventions around application structure and testing
very fast view-level testing (as opposed to webdriver)

Disadvantages

less popular than angular or react. people like to hate on it
large package (we currently need to send ~2MB of data before any render)
concepts are hard to learn
easy to get into trouble with performance, subtle UI timing bugs

Core concepts

"computed properties" – ember tends to favor declarative over imperative. If you feel like you're often telling ember how to do things rather than what to do, you might be using it incorrectly.

Ember in Aperta

Why are we using ember in aperta?

Inertia (let's be real)
Allows us to push data from server to subscribed clients
Using an SPA was a good tactic for rendering our "card-based" system since updating views doesn't require a full-page refresh

Project specifics

We use the ember-cli-rails ruby gem.
We use ember-cli, a command-line tool for managing an ember project (a lot like the rails shell commands)
We're currently using ember version . . . check client/package.json (as of this writing, it's 2.8.0)
Our ember application lives in client/ in our tahi project
We're trying to adopt the "pod" structure, but we have a lot of legacy code that doesn't follow the convention.

Developing with Ember

Tips

Download the Ember Inspector browser plugin. There are chrome and firefox versions. Learn how to use it.
Ember tests run in a browser. To run them, go to the client/ directory and run ember test -s. A testem server will start running. Point your browser at the url listed and your tests will start running.
Use (and update) the ember generators. For example ember g component my-awesome-component will create all the files necessary (including tests) for a new component.
Try to internalize the lifecycle of ember components. Components are created and destroyed all the time with all sorts of events you can hook into along the way. Learn how to use these.
Go read the ember-concurrency docs. It's very helpful in UI programming, and has largely supplanted our use of Promises. In particular, the animations here illustrate the different concurrency types really well
Favor computed properties over observers.
debugger
Be aware of the ember run loop. It doesn't come up much, but you might have to trigger it in tests, and use Ember.run.next()
Async is hard and we're constantly coding it wrong. Whenever you're doing something async, think about the following:
- what happens if this async code fails? Have I accounted for all the failure cases.
- what happens if this async code takes a long time?
While component states aren't conserved after being destroyed, do note that controllers are singletons and their state is conserved after transitions, so caveat embtor if you're coming from react (see APERTA-10478)

Continuing Education

http://emberweekly.com/ is a well-curated weekly email list. It's probably the best way to stay informed with the least amount of effort
https://discuss.emberjs.com/ the official ember discussion boards. If you sign up for an account, you can get a weekly digest. Lots of knowledgeable responders in there.
Our "Aperta Embereños" HipChat room. Somewhat active room where we discuss our ember problems and post articles.
The docs. Read them. For real.
Observations in teaching ember: https://madhatted.com/2017/6/1/how-201-created-teaches-ember-js