Add information for new users about how this works

[edsnowden]

As a new user going through the Ember quick start, this module provides the first page you see.

However, making sense of how Ember comes to present the welcome page is not trivial (I ended up on the -help slack, where @acorncom suggested I create this issue). It would be useful to neophytes like me if the page itself had some kind of "how this works" information.

The first bit of investigation led me to application.hbs which turns out to be what is served as the index page (somewhat magically, because index.html doesn't reference it explicitly - though this first led me on a detour to try to understand content-for). In application.hbs I saw {{welcome-page}}, and after realising this is nothing to do with Ember per se but rather it's a Handlebars template, understood that welcome-page is a Handlebars helper. However, I couldn't find anything registering welcome-page as a helper in my app/ folder.

A grep turned up node_modules/ember-welcome-page which seemed likely. The only reference to this is in package.json, which I understood to be a npm file, but it was conceivable that ember-cli consults this too (acorncom confirms).

However, within ember-welcome-page there appears to be no mention of "welcome-page" (as opposed to "ember-welcome-page") nor of the functions the Handlebars documentation says are used to register helpers, so it wasn't clear to me how {{welcome-page}} could resolve to anything provided by it.

@locks clued me in that it's ember-welcome-page/app/components/welcome-page.js that supplies the code. However this is an export of a non-existent file, which is hard to understand until you realise that ember-cli is a sort of compiler that will rearrange files into a layout where this export will work at runtime. Even then, the included file doesn't look like it's providing a Handlebars helper, or anything called welcome-page, but rather a subclass of Ember.Component.

So presumably Ember.Components either are callable as helpers, or somehow register a helper... the mystery deepens. That's where I've got to so far!

[edsnowden]

Here's a gist with my emerging notes, in case it's useful

https://gist.github.com/edsnowden/6046295e1c37487de5e2ee52c524a179

[sheriffderek]

This is a great example of why we don't "welcome" people to ember well.

[cyberalien]

Another new developer checking out Ember. To add to first post, after doing more digging, I'm still confused on how it is imported into application. It is not mentioned anywhere in configuration.

Does Ember go through every single dependency and scan it for potential files?

edit: quoting reply from Discord that clarifies it:

ember-welcome-page is a dependency of a new project (it's part of the default blueprint when creating a new project). ember-cli checks which dependencies are Ember Addons (Ember Addons have the ember-addon keyword defined in their package file) and includes them in the build. Components that have a re-export in the app folder of an addon are automatically available in the consuming project. More or less.

[angelayanpan]

also landed here. I think: doc can be improved.
around zoey says. I was simply trying to test some styles out. and I was thinking... ohh nice to have this welcome page that I can play with applying some styles. And then also find it not obvious how the welcome page works.