This is what I find to be the case too.
1 Like
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.
Oh man, I would love to, but the API still hasnāt solidified enough where docs wouldnāt get out or sync with code (or removed entirely).
Weāre sort of at an impasse based on the effort it would require. Replacing ember data with $.ajax in the guides is a lot of work, finishing ember data is a lot of work, writing API docs for data and keeping them in sync as the library changes is a lot of work.
In a perfect world of infinite time, weād do all three. Right now, Iām working on the getting started guide (which does use ember data at a basic level) out the door. Is this something I should stop in favor of one of the other tasks above?
So far we have:
- Read the source code. Check. I went one even better, I compared the current release with previous, thatās how I found out that findQuery had been made private.
- Use Fixtures (hi Paul!). Check. It is good for learning, but doesnāt prevent general weirdness or bugs in ember data from giving you a bad day.
- Document the interface. Check. No one has the time. Maybe someone on the core team could at least create a skeleton for how the documentation should at least be incorporated in the Guides that others could start chipping away at. Iād be happy to start adding bits and pieces, but I wouldnāt want to waste my time with a pull request that wonāt get merged or thrown away.
- People are just using it anyway, even though the label on the box says āMAY CAUSE DEATHā. Check. If this is the case wouldnāt it be lovely if those people could document their use cases, maybe even the model relationships and the kinds of queries they are running to at least define the edges of what works and what doesnāt?
Seems like the consensus is ember-data stays in the guides.
Iāll throw my hat in the ring for the third time in this thread, that I am willing to work with anyone from the core team to make this situation better, mainly because Iād need a pair to get started, and also I just donāt want to waste my time on work that wonāt be accepted.
Itās actually worth noting that Tom and Yehuda have a plan for stabilizing a subset of Ember Data. This should make it much easier to get to the point where we can have something releasable and with good documentation.
@pwagenet it would be nice to get some of the vision communicated, like an announcement of what is being worked on for ember-data. I do not mean bring it up for public discussion (not by any means) but at least let the community know what is being worked on. It would give us a sense of where this is headed short/mid/long term.
1 Like
We could also remove data related information entirely.
Thatās not a great option since most people are going to want to know how to solve these problems. It seems like the best route forward is to get a subset of ember-data stable ASAP so that we can, in good faith, tell most people that ember-data is actually a solution for them.
2 Likes
I totally agree in the long run, but today, tomorrow, and next week people are using guides and being frustrated. FWIW, I donāt think we can resolve the guide problem faster than we can resolve the ember data problem.
Let me enumerate the (count 'em, two) assumptions that Ember makes around data loading:
Your model class has a find method
If you have a route that looks like this:
this.route('post', { path: ':post_id' })
Ember will try to call App.Post.find(params.post_id). That will become the model for the post route.
Your model instances have an id property
If you have the above route, and you use linkTo or transitionTo with a model, Ember will try to fill in the :post_id dynamic segment by calling object.get('id').
Both of these integration points are documented in the naming convention guide and the routing guide.
I would definitely be open to adding the same information in a third place (perhaps a new guide on āModel Assumptionsā. Iām sorry that you didnāt find this in your initial search for information about the integration.
3 Likes
Further to what @mspisars says - the idea of a subset is great! But there have been 0 (count 'em, 0) examples of explaining this vision recently from tomhuda, and every time this or other questions about future direction come up, Trek, Wagenet or another member of the core team defer to tomhuda.
I donāt want to be critical and I sincerely appreciate everything that has been done, plus the fact that Ember is totally free, etc. etcā¦ But, for example, communicating in a blog post or on this forum will reach a lot more people than a presentation or discussion at a conference ā something to think about.
(sorry for the weird user name references - I apparently canāt refer to more than one person in a post)
Agreed. We should be saying more about the plan. We have been doing the work on BasicAdapter in public, but I understand that that isnāt the same as a document explaining the high-level.
For now, you can take a look:
I guess there is no a cut and dry solution.
The main problem is that as much as we say Ember Data is not ready, it features very prominently in the literature. People are using it and they are being nudged in that direction by the Ember guides, yet they have no support beyond the basic examples in the guides.
Itās your call what would be easier / more beneficial ā an expansion of the Ember Data section in the guides or API documentation ā but something more should be on Ember Data documentation.
What can I/we do to help?