I’m also new to Ember, but am good at googling sample code and tutorials, so it hasn’t been a big deal to get around the docs, but it’s hard to express how right you are here. The best API docs I see are ones that try to inline examples for every API call. No one gets them all, but some manage a large majority.
This shouldn’t be so rare, but it is.
Why I am almost leaving Ember is because of how it handles animations. I am certain that I would understand Liquid Fire after reading its docs for two or three times, but since I am quite used to Angular and its (now I know) awesome $animate module, I just can’t get Liquid Fire.
$animate automatically detects the element’s transition duration and delay so you don’t have to bring those to application code. And it handles animations without producing any DOM nodes, completely based on classes.
I really am not having a hard time with other parts of Ember at all. It’s Router and Data are just remarkable, miles and miles ahead of Angular’s $route and $resource. But, comming from Angular, I think animations should be something trivial and entirely handled by CSS.
Animations can be trivial and entirely handled by CSS.
Liquid-fire is for stateful transitions, many transitions aren’t stateful and that seems to be what you are describing. It would be nice for there to be a similar library for state-less transitions, but until them using velocity jQuery.animate or similar yourself is the easiest way.
Well, I did not want to give you the idea that I was talking about general animations as it was my intention to talk about the stateful ones, as you call it. To be clear, {{#if}}, {{outlet}} and {{#each}}. I understand that, since Angular and $animate act upon real DOM nodes, while Ember acts upon string templates, it might be difficult, if not impossible, to recreate $animate functionality in Ember. Sure I can use “classNames: [‘animation-class’]” inside a component and, then, write its css as “animation materialize 1s ease 0s normal forwards”, to make sure that, at the begining of the animation, the element’s opacity is 0 and, at its end, 1, still retaining the style of the last key frame. But the real problem resides when replacing the contents of those helpers. Since de DOM nodes are immediately removed, there is nothing to animate. This is precisely the problem addressed by Liquid Fire and $animate. $animate’s simplicity is, in my opinion, a much better approach. According to the directive being used, it simply adds one initial class, which would not be present normally by the time of DOM insertion, and, very quickly, adds another one. These two classes together get the animation done without any Javascript code. Liquid fire, on the other hand, utilizes a central javascript file where pretty much everything is declared. I particularly dislike this approach. I believe that the animations should be declared in the template’s markup instead of declaring in the application code that all DOM nodes with the class “materialize” should be animated with a certain duration and after a certain delay. These variables, I believe, live happier in my SCSS files. I could get used to that, but the extra DOM nodes, serving as containers for panels to slide, settled the stone, to me, as a no go. Maybe something similar to $animate could be done in a component. As I understand, the component’s property “classNames” is the place to define the classes inherent to a given component, which must be present by the time the component is inserted. Perhaps a similar property, “insertionClassNames”, for example, could hold the classes that should not be present by the time of the component’s insertion, but right afterwards. In a similar way, the property “removalClassNames” would hold the classes that would be added to the component before its removal. I actually am doing something similar. By using “classNameBindings” I add a class suited for removing a component and, when it evaluates to true, I attach a listener for the event “animationend” in order to remove the the component from the dom. Yes, I do prefer to do that by hand instead of using Liquid Fire. Also, I believe the approach I suggested, which is quite similar to $animate’s, is much more keen to whole idea of Web Components which should, by design, encapsulate its complete behaviour and styling.
Hummm… I just realized that my suggestion would not solve the stateful transitions we talked about: {{#if}}, {{outlet}} and {{#each}}. $animate can do that because it acts upon DOM nodes that already belong to the tenplate. Liquid Fire has to rely on extra DOM nodes. It is a difficult problem to solve.
Em Dom, 27 de set de 2015 11:38 PM, Paulo Oliveira oliveira.phc@cuscuz.com escreveu:
I’m on my phone so I can’t really respond extensively but you actually grossly misunderstand how liquid fire works and tell Ember templates work.
Ember templates get compiled utilizes cloning And fragments, not string DOM.
Liquid-fire works by providing its own outlet such that it can control setup and tear down of the new DOM and old DOM both. It also adds classes, or you could add your own, and you can in fact write 100% CSS animations that work with liquid-fire quite easily.
I agree that in some cases you want to declare what animation should be used directly in your template, liquid-fire also allows this via “use”. I think it could be improved further but it works extremely well as is.
In general, transition animations between routes really don’t belong in the template, and the pattern LF uses for these mirrors patterns you will find in chrome/android itself, react libs, and many game libraries.
So here is my concern. This is a really good thread that describes a lot of the reasons why people are struggling with learning Ember (as I am). I agree that other tools like Angular have their problems, and I actually appreciate the opinionated nature of Ember.
But this thread started over a year ago, and in my opinion, nothing has been done to fix the documentation problems that several members seemed to accurately identify as a root problem. That to me speaks to a bigger problem, in that the community, while passionate and knowledgeable, isn’t large enough to tackle the problems like this without having to stop developing new features.
The documentation is still atrocious. And it (as several others pointed out) bad in the simplest ways (like omitting the top lines of the file that explains where commands like DS.Store came from. And it appears to me that all focus has been on getting to 2.0 without any regard for fixing the existing documentation.
If you really want people to use Ember and have it challenge frameworks like Angular for a larger market share, then you have to start addressing the learning curve.
But bottom line, is the community of experts needs to prioritize fixing these issues. Otherwise you are the brilliant guys sitting in the garage who have finally built the better mousetrap but can’t figure out why people aren’t knocking down your door. It doesn’t matter how good it is if you don’t make it something people can figure out.
You are right. There is, however, a very recent but substantial will to address these documentation flaws.
Absolutely.
This is a reasonable critique. Context is very important, especially for new comers. It can be difficult for more seasoned Ember veterans to see this sometimes. Experience fills in the gaps and a lot of reading between the lines is taken for granted. For anyone attempting to write documentation for Ember I would suggest erring on the side of explicitness. Even to the point it seems like it is excruciatingly obvious. Put oneself in the mind of a total novice, sometimes easier said than done though.
I am glad that their is a renewed understanding and effort to fix this, but without being too cynical, the proof is in the pudding (or documentation in this case). Until people see that it’s been fixed and made better, they aren’t going to believe that it will be.
I would be willing to even help (as a newbie) do some of that documentation, but I need help just understanding how to do it first. An example is a thread I have been having on data reformatting in the controller so I can take data retrieved in the route and restructure it to comply with a component I need to use. Several responses to the thread, but I still haven’t had anyone actually show me an example of iterating through a list and reformatting it, which seems like a very common thing.
It makes me wonder if the greater community has really adopted an interest in the growing the user base, or if (as does happen to some technologies) it’s created an “exclusivity” culture that almost subversively tries to keep new users out. That often times isn’t want the leading group wants, but happens among high level users with lots of informal sway in places like StackOverflow and discussion forums.
I have read some documentation for recently released 2.1.0 and there is a noticeable improvement.
I feel your frustration, jesmith, I really do. Based on MY own frustration, that I overcame, is that I started Ember Igniter – striving not to lose the perspective of a beginner. There is no such conspiracy to keep new users out, the proof is in the amount of conversations (especially if you join the Slack chat) trying to address these documentation shortcomings.
Ember, 2 years ago, was bad. Sure, lots of good ideas and very smart people behind it, but it was a pain in the ass. Why? Too complex. (Not that alternatives were much better.) That didn’t preclude people (even a mediocre developer like me) from shipping. But you had to be armed with a LOT of patience. Ember Data: that was not bad, it could almost be classified as shit. Totally different story today.
For the past months, and with the advent of 2.x, things have matured enough to say that it’s very good. Why? Significant conceptual simplifications and many things falling into place… finally. The prospect for the 2.x series is excellent. I for one am very excited about these upcoming releases.
Unfortunately there are a few remnants of Ember’s dark ages that the community is actively working on purging – including documentation. This is still a transition period… luckily we’re at the end of it.
It’s a good moment to invest in Ember. It’s an amazing, mature technology now.
Regarding your issue with data reformatting, I want to help you. Hit me up on the other thread, contact me directly, whatever. I won’t leave that until we make it work.
I think one of the best things that Ember should add to the documentation, is either code examples or working apps of things people frequently do.
The examples you can find across most sites are way to simplistic to be helpful outside of a classroom. They need to cover things like
But I think it’s also a problem that we are only focused on fixing the documentatin for the newest versions. My company is considering a move to Ember (which I am currently voting against based on the above mentioned issues) but have a reason I am not privy to, for sticking with the 1.13 version. So fixing the HEAD versions documentation doesnt’ help me. And I am sure that their a multiple commercial places that are wary of doing to the tip of a new technology for risk of bugs, and are going to start with a 1.13 version if they were looking at things in the short term.
I totally agree with @emberigniter. The new versions of Ember are really great and a pleasure to work with. Also the community is stunning. Getting started though still isn’t easy. I also learned Angular and their step-by-step guide helped me a lot!
I think a similar step-by-step guide for Ember would be awesome. Also it would highlight the main benefits of Ember and things like Ember-CLI would shine! Very important in this step-by-step guide would also be a guide how to test your app. I think testability is not prominent enough in Embers marketing.
Documentation is another story but I think documentation is not the first place to start learning a framework. I normally try to play around with some technology and then I decide if I like it or not. For me, documentation is most helpful during development and not at the very first beginning.
I think a good step-by-step guide like the Angular Tutorial would lower the entry barrier to Ember.
I have decided to pull out as well.
At first Ember.js appeared just what I needed. I was coming from backend experience with Django that’s MVC framework, and Ember.js seemed most familiar to me. It had CLI tool for project (just like Django), it had MVC structure (just like Django), it had templating engine that didn’t “extend” html (just like Django), it came with idea how project should be organized (just like Django) and testing out of box (just like Django) and modules extending it with features (just like you know what).
I was actually okay with dealing with limited resources and documentation. I was slowly working it out on my own, how to do common UI stuff as services, how to do RPC, how to make Ember-CLI play nice with Django’s runserver/Rest Framework. On more than one occassion I gived back either via feedback here, on Django Rest Framework Adapter’s repo. I’ve created package for using Django’s i18n system in Ember apps and small knowledge base for Djangonauts insterested in using Ember-CLI with their projects.
However I in last 7 months I have spent with Ember.js I have found it unfriendly, obstructing, and in long run frustrating technology to work with, and this ultimatelly made me drop it for something else.
For starters, there are things in Ember that feel half-baked. For example, how can I create route that has optional route segment, so I could hide page number from url for first page? Having multiple url’s point to single controller was non-issue back in 2006, yet in Ember.js its challenge enough to ruin your day.
Getting custom loading templates for “flat” routes, so you can, say, give UI preview for some list, requires nesting your route under “do-nothing” route for Ember to actually use your loading template instead of app’s default one.
Keeping ember-data’s store size under control was always a problem to me, and eventually I’ve developed habit of emptying it completely every time top-level route was entered, so I knew I’ll get up-to-date models from backend, while not using memory for holding some other stuff I’ll wont need beyond that one page.
I am big fan of code examples in Ember’s docs. Take a look on this one: Transform - 4.6 - Ember API Documentation
What’s the story being told by this code?
It is beyond me what one has to think to pick such a specific example when they could’ve have went with much more common, reallifely and frankly, obvious “string to momentjs and vice versa” example. How should I guess from this code which function is called on value returned by API, and which on value that will be sent back?
Eventually my codebase reached size in which broccoli’s build times entered domain of minutes, meaning every time I’ve hit cmd + s in my editor, I was guaranteed enough time to go make myself tea. And don’t get me started about “go buy SSD” as solution.
From the looks of it, it seems that Ember is still happy to tell you “calling set on destroyed object” error, like it did back when I was starting with it, which today I’m reading as an part of greater issue:
Ecosystem’s stability is non-concern for people in power in the project, with all focus being placed on rapid iteration towards some “perfect”. Old API’s are being constantly deprecated for sake of new, “better” apis, that don’t add any value to your project, but force you to return and iterate closed parts of your project, sometimes actually taking away features that you relied on, forcing you to hack around.
Eventually you get tired of that “WTF, how can this be stable when they change THAT” feeling you get when reading Ember’s release announcements, sit down, reconsider options and conculde that reimplementing whole thing on something else will take same time it would take to catch up with deprecations, but’ll let you then return to work on features instead of keeping up with framework.
I fail to see to whom is Ember.js really addressed.
I’ve tried it in open source development, where eventually I’ve reached place where there were more deprecations to resolve than todo’s on my roadmap.
Is it for software houses? But which softare house would want to return to project because bi-monthly in-house software evaluation their customer did has found deprecations in project that made them send that code back to us.
Oh, and the absolute icing the cake moment was when three weeks ago at work we got brief from customer (large EU financial company, to add) for small intranet app that also included research on few big profile MVC frameworks form their inhouse web team that concluded Ember.js unstable and unviable economically due to deprecation pace.
I’ve been learning (struggling with) Ember since June. The deprecations has had me close to tears. As soon as I think I’ve mastered a new concept (or at least understand a small part of Ember), it seems to get deprecated. I’m yet to upgrade to 2.x since I have add-ons that rely on deprecated functionality. I also dread the complete dropping of controllers.
HOWEVER, it feels like things are starting to stabilise. Books like Rock&Roll with Ember and Ember CLI 101 have been instrumental in getting where I am now. I do still have an incredible amount to learn though. The Ember community has been insanely helpful so far, so hopefully when I have learned enough I’ll be able to contribute back. Documentation can certainly improve. A couple of cookbooks with real world examples, for instance, would be incredible.
I’ve been very close to leaving Ember multiple times, but I’ve stuck around and the longer I stick around the more I’m convinced that it’s going to pay off. 
My problem with these books, as helpful as they are, only work when you’re doing exactly what Ember expects you to do.
If you have a non-standard API, you’re kind of out of luck for example. Yes, there are ways to get it to work, but it’s completely not obvious how to do so and may require substantial reading of the source code.
I’m kind of annoyed at Ember pushing this whole “JSON-API” thing. I don’t care about JSON-API. Nobody does outside of the Ember community, apparently, either. Ember Data does some things well, but the complete lack of flexibility is a real issue.
More in general, while Ember’s conventions (at least in part) work well in 80% of the time, the 20% of the time that you need to do something different, it ranges from extremely painful to near-impossible. It kind of reminds me of some of the people behind Rails who were always arguing from a “Basecamp doesn’t need it, so you don’t need it” perspective. Luckily for Rails, the community grew so big that eventually people started to fill in the gaps and later iterations of Rails became much, much more customizable (giving rise to great titles such as “Crafting Rails Applications”).
Ember’s community is too small for that to happen, at least at the moment.
I really like some of the things in Ember, but it’s things like these that are a real drain on productivity.
Another thing I noticed frequently. You’re trying to do something - you ask for help and (if you get any response at all, but this is more a problem with the size of the community than anything else) often people will tell you “why do you want to do this?” - “that’s the wrong way to do it” - “do it like this instead” - or the worst offenders: “why don’t you just …” or “why would you even …”.
I know people are doing this for free, I know I cannot demand anything from anyone. But in the interest of promoting the community, IMHO, answers like these are very bad. At best, they leave the beginner (or anyone) asking the question confused (why should I have to do it differently? what’s the problem with my solution? am I stupid for not seeing this?). At worst, it makes the community look arrogant and not friendly to newcomers (“if you don’t do it the Ember way™, you’re stupid”).
Please don’t pretend you know every use case. The person asking the question may have very legitimate reasons for doing things they way they do it, reasons you couldn’t possibly know when you haven’t seen the project in its entirety. Sometimes the only reason for this is that “it would take too much time to change this right now” and this is a perfect valid reason for anyone living with time constraints and having a hard time getting the fundamental concepts right.
This doesn’t mean pointing out when something is probably not the right way to do something, but the tone and context is key:
“So, here is how you might do this… code snippet or explanation… However, you might run into problems with this, this and that, so you might want to look into doing it like that.” It’s also fine to say “ok, I don’t know how do to it like that, so maybe you want to try this instead…” or “Ember currently doesn’t support this, so maybe try this instead…”.
A lot of people already do this the right way, but I still see the “why would you even…” approach, especially on the slack channel etc. I think this is hurting the adoption of Ember a lot.
@Fryle From one stumbling n00b to another, let me suggest that if you receive a reply to that effect, the best response in turn might be to politely request elaboration.
But before you do that
Sit back and carefully read the reply. If you need elaboration, don’t just say, (and i’m not accusing you of this) “wtf does that mean?” Try to understand what the person is trying to communicate, and how it fits in with Ember concepts. Obviously, this can be difficult if said concepts are already hazy, but you’re probably staring at a strong hint. Hit the docs again.
And open a text editor to compose your comment. Spend some time trying things and document them–and any results–in the file. Save the file, if necessary, and come back to it. Try to organise the comment before posting. Doing this enforces a critical examination of the issue you are encountering, and the approach(es) you are using to try to solve it. Many (and i mean many) times over the years, i’ve gone through this process only to resolve the problem myself before posting my next solemn cri de cœur to whatever forum or mailing list.
Above all, keep in mind that it’s a big community.
You need to disconnect Ember from Ember Data. They’re two separate projects where Ember can live without Ember Data. If you want to roll your own network services, go for it. There are many projects doing this successfully.
Also, I wish someone would lock this thread as it’s just a sound board for negativity.
@brian_ally - that’s some good advice. there is always two sides to the story: The one who asks questions can improve their questions and their replies and the one who answers can improve too.
I was just describing the latter side. If Ember wants to grow and to welcome newbies, it should take care about how it addresses them. Sure you can tell the newbie “toughen up and live with it”, but this is not the Linux kernel. This is a JS framework amid 1000 others, and if the newbie is not treated well (and their time being constantly wasted), they might decide - the benefits of Ember notwithstanding - “screw you, I’m doing Angular/React/Meteor/whatever”.
I think your comment of Ember being a “big community” means that you cannot tell individual members how to respond to questions. Well, first I don’t agree that Ember is a big community. Not compared to many others, so especially if you’re on the slack channel, you always see the same couple of people. And yes, you cannot tell individual members how to behave, but you can try to raise awareness, hence this post.
You need to disconnect Ember from Ember Data. They’re two separate projects where Ember can live without Ember Data. If you want to roll your own network services, go for it. There are many projects doing this successfully.
I’ll be willing to do that when Ember stops advertising Ember Data and takes it off its guides and API docs. Being honest about Ember Data - “syncing data to the server is not an easy task and there are several solutions, one of which is Ember Data” would be much more honest. Every new Ember dev is going to try out Ember Data and then throw their hands up in frustration when they realize X doesn’t work and now they either have to figure out how to get Ember Data to do X (spending hours and hours reading the source code) - or to completely rewrite their whole data solution. Notice that when I say “new Ember dev” I don’t necessarily mean “hobbyist working on some private project”, but also “people with schedules and constraints”.
Also, I wish someone would lock this thread as it’s just a sound board for negativity.
This, IMHO, would be a very, very bad idea. If you don’t listen to the feedback of the users who get so frustrated of your framework that they leave, you’re not trying to improve the framework. Now I realize no framework can and will be for everybody, but turning deaf to complaints, especially when they are so strongly voiced and show real frustration, is not a solution.
I, for one, am not rarely really, really frustrated. This is because I see that Ember does some things very, very well but fails spectacularly in other respects (again, IMHO), and this causes both a significant decrease in productivity and also a real lack of motivation. And, for months, I have been defending our choice of Ember to other even more frustrated team members again and again, and at some point it becomes really hard to do so anymore.
If you’re honest about Ember being a framework for “ambitious web applications”, then please listen to exactly the people who are trying to build those ambitious web applications and their real issues with it.
And again, keep in mind the alternatives. If I have to learn about the fundamental theorem of algebra or some complex algorithm and I struggle, well, then yes, I suck it up. But if, by using Ember, I stumble day in, day out, I might at some point just decide to throw it all away and start over from scratch with React and something.
Of course you can say “we don’t care”, and again, no framework can be for everybody, but I still think it would be a shame to ignore that feedback.