Should the Model section of the Guides have Ember Data references and examples removed?


@pwagenet agreed that in long run Ember Data is going to be integral someday, hopefully soon.

Meantime, since ember-guides rely on ember-data, and beginners depend on the guides to learn, then they will come away from guides feeling ember itself is not ready without changes. A beginner should be able to read guides end-to-end, follow the examples and come away with an understanding of how to build an app using current version of ember.

In the near term, I suggest:

  • Create a new Model section, focused not on how models work but on how the framework expects model objects to behave.
  • Rename the Model section to Ember Data and mark it as experimental.


I think the important thing is to get some feedback from @wycats and a @tom on this. They’ve been driving a lot of the code work and guides writing in this area. If we can get a sign-off on a plan then we can probably get some help implementing it.


This has come up several times in campfire and the answer has been: go for it.

Nobody has gone for it.

I agree with the sentiment on a philosophical level, but the practicalities seem to be a blocker. Data communication for long running applications is complicated. So complicated that most frameworks punt on the difficult bits (data relationships, records that have many canonical locations, etc), just skip the data layer altogether, or simply suggest you make new xhr requests for every data access (which negates a lot of the rationale of having long running client apps).

This is all further complicated by the fact that there are no standards for data communication between server and client. Start brainstorming a data guide and you’ll quickly realize you’re solving a specific data problem along one topic (fetching, saving, associating, etc). Add another topic and you’re further shrinking the number of APIs it applies to until eventually you’ve offered guidance about how one API can interact with Ember: a great blog post, a poor guide.

If anyone thinks they cracked this nut, I encourage them to write a guide.


Additional documentation about the ember-core/ember-data interface expectations would be good, though.


I’m not sure what Campfire you’re talking about.

I’m building a product with Ember that exists because I am putting a very real amount of time and capital into it. So I speak very practically of real matters that I find come up as an Ember beginner. My position is that as a user of the Framework, I try to report things I don’t understand or don’t make sense in the hopes that it filters into the conclave and changes happen that make it easier for people to get started and be successful, beyond the case where you’re building a ToDo app.

The inclusions of em-data in the Ember Guides gives it a legitimacy that is unwarranted at this stage, by virtue of the fact that Ember itself is close to 1.0 and from what I can see em-data is a long, long way from being close to a 1.0

For example, I tried to use em-data, after seeing that the Model section now recommended it. I couldn’t get it to work when I went past trying to either load all records or none, or load a record with a subset of its hasMany relationship, couldn’t find any materials to help understand the process or the reasoning for what should happen, asked an official core member of the Ember team, was told to look into using findQuery, which has been made private in a previous release.

As @pwagenet said, I’m sure em-data will be a core part of major applications when it is ready. At the moment it just creates a confusing headache that can end up wasting a lot of time, and I wouldn’t be surprised if people completely new to Ember just stopped at that part of the Guides and wrote it off completely. I certainly briefly suffered a buyer’s remorse at that point.

While the long range academic questions about what should happen, and what the preferred protocol should be are real and should be thought about and discussed, the Ember team needs to be aware of the fact that there is a very real hole and stumbling block in the public Guides that is causing real trouble. People need to be able to be successful today, not when em-data is ready, or when they’ve learned enough from trawling the internals.

I love Ember, and I think everyone’s doing great things, and I evangelize it whenever I get a chance. But please think about this as a serious issues for new comers beyond being defensive about it or creating artificial blockers around documenting a non em-data strategy.

<3 <3 <3

P.S. If someone wants to work with me on my App and together figure out what the correct non em-data way is to handle the patterns I’m trying to use, I’m !more! than happy to write a guide that explains it.


We have a Campfire room for Core Team and contributors.



I pushed a documentation update to the guides:

Does that qualify? :panda_face:


I, at least, am aware. This topic has been brought up, privately and publicly, many times before. The solutions to this problem have not been implemented not because we don’t care but because they’re much more complicated than just providing “some information on basic jQuery.ajax usage.”

Time is a scarce commodity and people seem to prefer spending it on getting Ember data ready for when we do an actual 1.0 release.

When we had no information about data communication (which is what Angular does) we got lambasted for not providing any help on this issue. When we offered advice about basic data loading, people complain that we’re neglected to talk about how to do mutation. When we said “try using Ember data” we get grief because the API isn’t as polished as core.

Unfortunately we’re not secretly hoarding information about to robustly handle data syntonization between server and browser and just being lazy about writing that guide. It’s a complicated space and our best efforts to solve it in a generalized manner are written into ember data.

The interaction points between ember core and ember data involve very loose coupling and we could better describe them . I don’t think a generalized guide about how to handle people’s specific data needs is possible.


I’ve been developing for over 10 years. I came from a ‘Enterprise’ .NET background and lived through the birth and growth of both Hibernate and nHibernate. The picture you’re painting about how complex the issues that people need to know about isn’t strictly fair. You’re right, this conversation isn’t new, and it’s been going on for decades, and always the Framework maker wants to cook up some conceptually perfect and pure way to do everything, and then when no one uses that, after a couple of years, a host of basic methods to hydrate and dehydrate your objects appear.

There are ‘basic’ things that can be done with jQuery.ajax that should work, and could cover most of people’s use cases, and I know those need to be iterated to be clear, but they don’t work because Ember makes assumptions that aren’t documented, and those assumptions look like they are related to securing Ember Data as the only choice.

For example, because Ember assumes that object instances are retained over the lifetime of an app, if you want to have linkTo work correctly you’re going to have to build you own Identity Map and store objects in there as you load them. This fact, and all of the signals to point to that conclusion aren’t documented anywhere. If I’m wrong here, shoot me down and tell me how it is, but those are my findings so far.

Is Ember useless without Ember Data? Of course not, but the argument sounds like it is the case, and certainly some of the internal decisions might make it look like that’s what’s being engineered.

I don’t think a generalized guide about how to handle people’s specific data needs is possible.

No one is asking for that. All that’s wanted is advice and guidance on how to not use ember data and still have all of the ember functionality work.

I’m not trying to lob grenades, but these constant complaints of the community forcing you to jump from one foot to another and therefore we do nothing just don’t hold up.

<3 <3 <3 !!!


At this stage, I’m actually willing to make a brand new reference app (that isn’t a ToDo app) that works without Ember Data and has best practices to allow the rest of Ember to still work…

… if Someone will work on it with me to make sure it’s correct.


The return value of model should promise-compatible if you want to hook into the delayed activation mechanism and should remain strictly equal to itself when used in other parts of your application. If you like, the framework will infer the model class from the parameter name and call find on that object if the method exists. This should return a promise-compatible object. I think that’s pretty much the API expectation.

Route's lack of docs is because it is newer than the older router. You’ll notice it’s not just the model parts that lack docs. Route just happens to also be the integration point between the display layer of an Ember application and its underlying remote data.

Other people have release data libraries for Ember and some apps go without a library entirely. I feel your frustation in learning a pre-release framework but veiling an attack on people’s intentions behing weak language isn’t appropriate and given that other people have been able to integration also inaccurate.


What’s especially insane is I’m usually the one arguing for an ember-data-less section of the guide.


At first, I was like ‘This is really helpful, exactly the kind of information that is useful to my problem’. The ember-resource link is really interesting and I hadn’t come across it. Discourse should me a course to get where I am today.

And then:

Not every passionate Ember user is launching a ‘veiled attack’ when they question some of the core design principles and choices. Especially when you think about what good it would do to launch such an ‘attack’.


I think having the reference to Ember Data in the guides is a good thing.

The one request I have would be to add API docs for Ember Data to the main site. It’s very daunting to go source diving into Ember Data…


I completely disagree. From my perspective of sitting in the IRC for the past few months there is rarely anyone using Ember with just jQuery.ajax. Everyone hears about Ember Data, because there is a lot of buzz around it and people want to just use it.

I’ve been using Ember Data for a few months now and the most frustrating part is that the general response is yeah it’s not stable and it’s not finished. But really, people are using it anyway and they don’t care if it’s officially in the package or not.


My biggest question during development so far has been “Should I stick with Ember Data or try using plain ajax calls?”.

So far I’ve been using Ember Data because it seems to be referenced everywhere as the “One True Way”. However I’ve looked at the Discourse source code and the simplicity of straight ajax calls is appealing but it also seems to be a lot more work for less benefit.

The biggest issue I’ve found is that there is essentially no documentation for not using Ember Data and scarce or conflicting information for using Ember Data.


This is what I find to be the case too.


Since the docs aren’t ready, why don’t people read the code to find out what the interface is for the models? Yeah, it’s not ideal, but you’ll at least learn how Ember works from the inside out. It’s what I had to do when I built our ORM that sits on top of Ember’s data bindings, and it really wasn’t that bad. Will this be acceptable long term? Of course not, but Ember has gone through some very rapid changes in the last few months, and keeping the docs in line with the rapid API changes up to RC would have been a daunting task even if they were being paid to build this, which they aren’t.

My point is, if you’re interested in using a framework, you should learn the internals as well as the utilization. It’s only going to help you in the long run.

And a note to the core devs, a documented interface might be a good idea (I know JS is duck typed typically, but this might really help us devs who do really advanced things like building custom ORMs to work with). It doesn’t need to be fancy. Just the signatures and the expected return values would be more than enough for me. =D


I’m building a fairly large reporting app using Ember.js and em-data. Due to the nature of the app, it goes well outside of the standard use-case for the adapters that come built-in with data, so I’ve had to spend a lot of time reading the code to be able to write my own adapter. And let’s not even get started on the effort I’ve had to put in to be able to write tests around my app.

What I’ve found is that the code is extremely well-commented and pretty easy to follow. Ember and Data follow a very consistent structure, making it easy to find what you’re looking for. Github has also been a great source of information, between issues and developers leaving detailed commit messages. Overall, it’s a remarkably easy-to-read codebase, once you get over the hurdle that always comes with reading someone else’s code.

I agree that once a library hits 1.0 “read the code” is not a suitable answer for beginners. I also understand that most people click links to the guides without much context, and therefore expect what any reasonable person would expect: this is the source of truth for this app. Unfortunately, with the speed at which they are moving to 1.0 that is not always true, and they cannot always get the docs updated as quickly as the code. Until they reach 1.0 and get more time/volunteers to put in effort on the docs, we need to be patient and rely on the other resources we have at hand.


One thing you can do is use the FixtureAdapter for development/testing and defer working with any remote calls until ember-data is more stable.

This way you can get used to the ember-data idioms without having to write your own adapter.