[WIP] Glimmer Components guides #764
Conversation
|
Why are they a different section from the regular components? |
|
Thanks for all your work on this, @chancancode!
I'm not really into that idea. The goal of the Guides is to show users the happy path to using Ember. When Glimmer components are released, they will be the happy path. I think we should just update (or replace) the current Components section with your content.
I think this would make a very useful blog post, but I don't think it should go in the Guides, just like we don't include deprecation info in the Guides. |
There was a problem hiding this comment.
Why are curlies needed for primitive types?
There was a problem hiding this comment.
Because <progress-bar value=2></progress-bar> is already defined in HTML as meaning:
<progress-bar value="2"></progress-bar>We can get away with some divergence, like adding support for <progress-bar />, in areas where the thing we're adding is very, very unused in practice. In the case of <progress-bar />, it is actually far more likely that the HTML definition ("ignore the /") is not what the user intended.
However, when someone writes <progress-bar value=2> in an HTML-like context, there is a very strong likelihood that they really do mean the HTML semantics, so diverging here is not acceptable.
There was a problem hiding this comment.
The only other divergence from HTML is:
In HTML, attributes without quotes are still attributes, but in Ember, the above syntax assigns a property, not an attribute.
I think we can get away with this divergence because we are introducing new syntax that allows you to add dynamic content to HTML ({{}} is pretty much the consensus syntax for this extension). Because assigning both attributes and properties to HTML (especially with web components) is common, having a terse syntax for describing each is important.
Again, this restricts the divergence from "normal" HTML to:
/>means what it means in XHTMLfoo={{}}without quotation marks around the curlies means assigning a property, not an attribute.
There was a problem hiding this comment.
Note that the DOM spec mirrors almost all properties to attributes, so leaving off quotation marks will mostly do what you expect but allow you to pass values (booleans, dates, etc.) instead of strings. This is especially important for things like value={{name}}, whose attribute assigns a "default value", but the property updates the .value.
Because of the fact that attributes and properties are melded together in the user's mental model already, the DOM has done work to make attribute strings and property values mostly mirror. What this means is if we hew closely to the same fuzzy mental model that the DOM already worked hard to support, things will work with the same caveats as DOM.
The transition to Glimmer components will take a while, and immediately removing the guides out from under existing apps seems bad. Up until the first release where we release Glimmer Components, curlies are the first-class way to do components in Ember. If they're working for you, they'll keep working, and there's no reason to make people feel like they have done something wrong for doing exactly what we told them to do. I think we should use the "Classic" moniker for existing components ("Classic components") rather than "legacy", which indicates that there is a new, better way, but that you shouldn't feel embarrassed about not using the new way yet.
I disagree. We need a new top-level transitioning section to help people transition concepts from other frameworks like Angular and React, and a guide for transitioning from curly components to angle-bracket components would fit well there. The blog is for content that, if you came back a year later, you would understand that the content is out of date, and that wouldn't be a big deal. For example, when we write a blog post talking about a release, or the progress towards a feature, nobody is going to get upset if a year later, the information in that blog post isn't precisely the current state of Ember. However, content about transitioning to angle bracket components (either from curlies or from another framework) is meant to last a long time. As we change Ember's idioms, it is important to keep content like that up to date, so it does not belong on the blog. |
This PR is not meant to reflect the final structure, which is an orthogonal question that I have been discussing with @michaelrkn. @chancancode shipped it so that people can review the "new world" before we're ready to make calls about the exact rollout. |
|
Classic is a good way to describe this. I think for busy people there should be a high level summary table somewhere that shows the important differences side by side. Also might be helpful to show pre and post glimmer components example code side by side whenever possible. I think that will drive home some of the finer points. |
|
I feel pretty strongly about is not having 2 different sections for classic components and glimmer components. I think the documentation should primarily assume the user will use glimmer components, and then note differences between the two where appropriate. Otherwise, it will be confusing for people who are new to Ember as they try to parse out the differences between the two, and it will be difficult to maintain the information, as there is significant overlap between the features of classic and glimmer components.
Hm, that's an interesting idea.
Transitioning from classic to glimmer components seems like a good candidate. I could be wrong, but my guess is that in a year from glimmer components' release, there will be a relatively small number of people who haven't switched, for whom the content is still relevant. |
I agree with this. Given the high rate of progress lately (which is overall good) it's wise to not tire people with deprecations. |
|
👍 on "Classic" I think what might not be immediately obvious here is that the two styles of components end up diverging quite a bit, so I understand the reaction here. The original plan was to call this "angle bracket components", which is the same components we have to day except blah, blah and blah. As the feature was being worked on, it ultimately become quite clear that there are a lot of important differences that basically end up requiring a pretty different mental model (we assert that it is simpler) and it also enables many scenarios that are not possible (or very annoying) before. One thing to call out specifically that it has a different base class than classic components ( It might be helpful to think of the time when Components were originally introduced in Ember. It is certainly possible to explain and describe them as "same thing as Views, except blah and blah and blah", overtime it has become quite obvious that those differences puts you in a vert different mental model and allows for very different use case, so it is more useful to talk about them as a separate feature that happens to share primitives with Views.
Which is why I suggested to keep it hidden (from navs) by default and only link to them from the banner in the introduction section. ("This guide is describing the new Glimmer Component feature introduced in 2.x; go here if you are looking for information about ..." – we can work on making this obvious that if you are a new user you won't have to care.) I think it is fine for the section to be named simply "Components". The current naming is simply because I couldn't move/hide the existing guides yet.
It will probably be the contrary – the classic components API will be supported and maintained, but they probably won't get any new features. So it is more likely that they will be quite stable but the overlap will shrink significantly overtime.
I think it is once again useful to think of the Views situation in 1.x. Since Components were introduced, people have slowly transitioned away from views, and if you are working on new ares in your apps, you probably shouldn't use views. But it wasn't an overnight transition, and it was a fully-supported feature for the 1.x series, so it is useful to have the docs still accessible. I believe it would probably be true here as well, but perhaps to a slightly lesser extent. Especially if you consider add-ons that ships components and large apps, this transition will probably take a while. Also, as Yehuda have pointed out, there is really no immediate need to switch if what you have is working well today. |
|
Great points, @chancancode. Thanks for the thorough explanation. |
|
❤️ we difinitely share the same goals (optimize for not confusing new users), so we can keep toying around with different approaches on that front while the feature/content progress :) |
|
Sounds good! |
|
I would like to assume that at 3.x A lot of people that I talk to refer to Ember as an MVC but when they start working with it they are like "Where are the Views?" and hopefully soon "Where are the Controllers?". The "big picture" ideas are outlined in blogs, but seem to have a hard time getting into the guides. This is sort of why I mentioned adding something about the programming model and methodology up front. |
|
This should be less of an issue with the new module imports.
|
Indeed.
Like views in 1.x, curly components handle a large number of use-cases simply by virtue of the fact that they have existed for a while and have accumulated subtle emergent properties that are the "canonical" solution to certain problems. For example, We will probably migrate some of these features over to GlimmerComponent to aid in the transition, but it's likely that certain use-cases that subtly depend on particular combinations of features won't work immediately. As a result, I do not intend to "deprecate" classic components until we observe that people stop asking for features in GlimmerComponent to help in the migration.
Confirm. import Component from 'ember/glimmer-component';
// now you can refer to just "Component" in the rest of the file
export default Component.extend({
}); |
I am not certain of this.
|
|
We should probably save that bikeshed for the feature PR ;) I promise I will update the docs with whatever people eventually agreed on :P |
|
Agreed. |
There was a problem hiding this comment.
semantic description of?
11 participants
The Goal
Introduce the Glimmer Component feature to new and existing users.
The actual motivations of the feature itself should already be documented in the first few sections, but the high order bid is "component as an abstraction".
Once the feature has shipped (looking like past 2.2, so maybe 2.3? see below), my current thinking is that we can somehow keep the "legacy" components guides accessible but hidden by default. For example, on the top of the "Introduction" section, there will be a highly visible "Note: this is for new stuff, for old stuff, see here", and once you navigated into the old section, it will be available in the navigation.
Philosophy
For example, I chose to not mention yielding values to blocks when the concept of "blocks" was first introduced. (As opposed to mentioning "everything you need to know about blocks" in one section, which is better for someone who already learned the concepts and want to look something up again.)
Table of Content
attrsand blocks)GlimmerComponentJS class and keeping internal states){{mut}}helper)Current Status
The feature itself is pretty close to completion in the broad strokes, but there are plenty of nuances that needs to be fleshed out. Writing these guides was quite helpful in terms of uncovering holes in the model, and we have identified the right solutions for most of these things (but not implemented at the moment).
We also identified some performance issues, which we decided to prioritize over this feature, so we will likely not ship this until ~2.3.
In particular, I am currently semi-blocked on the "Communicating With The Outside World" section by one of these issues. (I already written some of the text, but haven't committed yet. Here is the example I am planning to use.)
Since we are prioritizing performance for 2.2, this will probably be put back on the back burner for a bit until we pick up the GC feature again in a few weeks.
Grammar/spell-checks are not very high-priority at the moment (because entire sections could still be rewritten or scraped), but if you noticed anything, feel free to leave a line comment and I'll eventually deal with them.
High-level feedback (I don't like the flow here, I don't think you can assume knowledge about X here, I tried to learn it following the guides but I was confused about Y) would be quite helpful.
Misc TODOs
importsyntax/pathupdatein{{mut}}