Guide to Object management and dependency injection in Ember

[pksjce]

I saw @mixonic s talk at http://www.youtube.com/watch?v=iCZUKFNXA0k#t=6318
This is how I understood the Ember container to be and thought new people trying to look inside Ember should know it too.

[stefanpenner]

although the container exists, for the most part it should be considered an implementation detail.

The public api is actually only

app.inject
app.register

I would prefer for today that these are the API's we highlight

It is likely fine, to show people how the container does the magic, but I would like to convey a clear message,

[stefanpenner]

container.lookup exist to enable escape hatches, for ember API deficiencies. In lots of cases, and initializer with an injection rule is much superior. This is because it also performs validation as the object is instantiated, provided quick-fail feedback.

[pksjce]

Ok, But I would need to add documentation on initializers for that right? And mention the correct usage for lookup?

Ember.Application.initializer({
  name: "store",
  initialize: function(container, application) {
    container.register('store:main', application.Store);
    container.injection('controller', 'store', 'store.main');
  }
});

Like this? ^

[pksjce]

Shall I add an FAQ similar to the run loop page where I put up info about App.inject and App.register ?

[mixonic]

I might say "Service Lookup and Dependency Injection", though it is more technical than "Object Management". "Object Management" just strikes me as a vague title.

[mixonic]

@pksjce So though my talk dived deep into how the container powers Ember internals, there is a core team consensus that the API is not extremely stable. Because of this, they would like to steer people away from using the container API directly. For a website guide, it is probably best to give the specifics of Ember.Container a broad brush and move on.

What this means is that a guide section for Service Lookup and Dependency Injection might better focus on these container-powered APIs:

• needs:, which does dependency injection of controllers
• App.inject and App.register

I think approaching the guide with a pattern focus instead of an instruction focus may be ideal.

• Create a service with controllers (needs:)
• Injecting a new service onto all items of a type (App.register and App.inject, how to make something like this.store)
• Demonstrate the benefit of DI in tests.

Thanks for the pass at this! Let me know if you want more help on it to move it forward.

[pksjce]

I can do that. Let me have another go at this. I'll notify you on my next PR soon enough.
Thanks!

[stefanpenner]

can you please re-use this existing PR, it will make it much easier to track the comments and improvements.

[lukemelia]

Hmm, container.lookup is not public API @stefanpenner? That means that there is no public API for service location. Do we really believe you can build real-world Ember apps today without using that pattern on occasion?

[stefanpenner]

@lukemelia container.lookup directly is likely the only public api on container. Remember it exists as an escape hatchmput in place to allow for scenarios the current API's lack proper solutions for.

It's use should not be encouraged, as typically it results in more brittle failures, then it's injection based counter-parts.

[ebryn]

Let's drive this to completion

[pksjce]

@mixonic - I tried to stick to what you had advised. Have documented needs, inject/register and initializers. I'm a bit unsure of the usage of DI in testing. Can you have a look at this http://emberjs.jsbin.com/qafat/1/edit?html,js,console,output
I need some help to come up with better examples I think.

[mixonic]

@pksjce will review. Thanks for taking another pass!!

fwiw I've improved the documentation for App.register and App.inject in the API emberjs/ember.js#4577

[pksjce]

@mixonic - Thanks very much for the edit! Inline examples while explaining theory was good idea. So, do you suggest removing explanations on Application initializers?

[mixonic]

@pksjce I think using initializers for the App.register and App.inject section would be fine, even idiomatic. But we should avoid talking about the container API in this guide for now.

[ugisozols]

may be exposed

[pksjce]

Okay. I made the corrections.

[pksjce]

Hey. Any update?

[hswolff]

Hoping we can get this merged in soon!

[stefanpenner]

this must occur in an initializer

[pksjce]

@stefanpenner - That means something like

Ember.Application.initializer({
initialize: function(container, application) {
container.register('logger:main' ...
}
});


This documentation does not have information about using container object right?

[mixonic]

You can use:

Ember.Application.initializer({
  initialize: function(container, application){
    application.register('logger:main', /* ...whathaveyou... */);
  }
});

application has .register and .inject.

[stefanpenner]

ping

[mixonic]

Touched on some of @JulianLeviston's feedback in pksjce#3, but the last section still seems to need some polish. Will find more time to edit/write this week.

[mixonic]

@pksjce I'm going to fork this into a new pull request, since I presume you don't have further interest in pushing it forward. I think it will save us both a bunch of time.

[mixonic]

Forked to #1581

[rwjblue]

Closing in favor of #1581.