Unnecessary hurdles

Learning Team
1

I’ve been learning Ember. A few suggestions for newbies…

  1. Improve the docs. It wasn’t at all clear to me, for a long time, when I needed handlebars, when I need to do an Ember.get(), etc. Some of this is simpler by saying, which I didn’t see well stated, “Ember structure data isn’t available from HTML, so actions called from HTML must go get it explicitly.” Just an example.

  2. This feeds right into the next one… Once you know this, you would know that you can’t provide, e.g., an option list such as…

    {{#each model as |person|}}
    <option value="{{person}}"> {{person.name}}</option> 
{{/each}}

because {{person}} won’t survive that transition. But this should be more clearly explained in the tutorial. (Or, if it is now, I missed it.)

  1. A bit more on when and why to use this.get() vs. Ember.get() would be nice. Again, it may be there, but I’m not easily able to find it… and I don’t need it so much now.

  2. Initially, the model usage is confusing simply because the word is overloaded by using it as both the label and the value. For example, something like… {{component-name title=“MyComponent” model=model comp=“comp”}} Too many examples say “model=model”. Now I understand it, but initially, not so much. In my templates, I usually have multiple models active. Would it kill you to provide less confusing examples?

  3. Things like CORS could use a good troubleshooting section. Especially combined with what can happen with prefixes.

  4. Simple things… like initializing an input type=range with a negative value… just plain don’t seem to work. But they aren’t defined or covered, because old hands know either the secret work-around or a less obvious way to do it. (And it’s probably not user-error, as positive numbers work fine and negative numbers work as constants or not inside Ember.)

Overall, I’m reasonably pleased with Ember, and any system will have some hurdles. But it does seem like the Ember devs forget that they have years of Ember underneath their belts, and just assume that complex under-documented concepts or bizarrely non-functional code (those negative values again) are “normal.” I’d like it a bit more direct.

2 Likes
2

Hi @robomac, thank you for your constructive feedback.

I’ll try to address your points and start a conversation so we can improve the documentation.

  1. I don’t understand what you mean by “person won’t survive that transition”. Are you saying that person is an object that gets serialized to a string because HTML properties are strings? And so it is no longer a reference to the object.

  2. Can you elaborate on this? There is only two references to Ember.get() in the Guides that I could find, one in testing and one in customizing adapters.

  3. Can you point to specific examples? I have not found any model=model references in the Guides, nor even model=something, so I don’t know how to address this problem.

  4. A community member volunteered to write something on CORS. As CORS is essentially concerned with server-side, we will likely try to document how to set it up on different popular frameworks. We will also mention the proxy option for Ember CLI’s server command.

  5. This seems like a bug, can you please submit a bug report with a reproduction so we can address it?