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

1

Since the Guides are the beginning point for people new to Ember, it seems like a bad idea to have the section on Models lean so heavily on Ember Data, when Ember Data is clearly not ready to be used in production, and even some members of the Ember Core team do not have a consisten view on what works or doesn’t work.

I suggest this section is re-written to start with basic Ajax style calls, and then once those foundations have been built include a discussion on how Ember Data eases the pains of an primarily raw Ajax call driven approach.

1 Like
2

My personal experience is the reliance on em-data has been a point of confusion for people learning the framework. I think it might make more sense to start with jQuery.ajax calls and then lead up to ember-data once people have got a handle on the basics.

I think the confusion comes from mixing a pre-1.0 framework with one still under heavy development.

3

I think much of the problem here stems from the fact that Yehuda and Tom believe that Ember Data is going to be integral to most major Ember apps. That said, you’re right that Ember Data isn’t nearly as stable as Ember Core. We do hope to ship the two together at some point but we’re not there yet. At the very least I think we should put some additional information in to explain the state of Ember Data and alert people to the fact that it is not as stable as core. We should also provide some information on basic jQuery.ajax usage, though the new BasicAdapter in Ember Data will address some of these cases.

1 Like
4

I agree with @eviltrout. It may not be necessary to remove Ember Data examples, but providing some basic jQuery.ajax call examples initially would be helpful when first encountering Ember.js documentation.

5

@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.
1 Like
6

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.

7

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.

8

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

9

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.

1 Like
10

We have a Campfire room for Core Team and contributors.

11

Ah…

I pushed a documentation update to the guides: https://github.com/emberjs/website/pull/404

Does that qualify? :panda_face:

12

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.

13

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 !!!

14

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.

15

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.

16

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

17

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’.

18

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…

19

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.

2 Likes
20

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.

3 Likes