image from The Rusty Shield

Hello There!

Setting a happy tone immediately is job one, in my mind. When you add Ember to a page you want to know it's there, and it's ready for you. Moreover you want to get going writing some code!

Right now you're stopped immediately with script warnings about including Handlebars and jQuery (if you don't have them installed). Can we make that experience better?

Yes. Bundle them! Angular bundles jQlite, Ember should bundle Handlebars and the same library. If they can't do that (for whatever reason): tell me (using console.log):

Ember needs Handlebars and jQuery to run! You can download them directly or just use add these tags above the ember.js script tag:
<script src="http://cdnjs.cloudflare.com/ajax/libs/handlebars.js/1.0.0-rc.3/handlebars.min.js"</script>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>

How nice is that! I still like the idea of bundling, however.

Default App.

Ember is all about convention. Convention with naming, with various objects following MVC - what if we flexed that even more.

The assumption is this:

If you include Ember, you want to build a Javascript application

I think that's a pretty solid assumption. So let's turn this around - instead of writing this:

var App = Ember.Application.create()

Just make "App" exist already! We know that jQuery is a dependency - so go with it and load that statement up by default:

//Part of Ember.js
$(function(){
  if(!Ember.bootstrap){
    App = Ember.Application.create();
  }
});

This can be overriden (which keeps in the spirit of Ember) in a new method Ember.bootstrap:

Ember.bootstrap(function(app){
  Tekpub.MyApp = app;
  //config etc.
});

For me, 9 times out of 10 I'll just work with "App". No need to change things in my mind and if you need to - just run App.config(function(app){})" and change things in $(document).ready().

That Naming Thing

Right now there are a lot of concepts that hang loosely from a naming scheme. This is a double-whammy that I think makes Ember hard to use.

What if we reversed this entirely? What if we defined the "name" up front? Here's what the Index definition would be (it could easily be "Post" or something else):

App.Index = function(){
  //wrap the notion of an Index in a "Definition" object
  //this is clean, and in one place
  //the naming concerns are implied
  return {
    //all of the below is optional
    model : {
      //this is an Ember.Data thing
      //or I can override some methods using
      //my own Ajax stuff with jQuery
    },
    routes : [
      "/:thingy",
      "/stuff",
      "another-override"
    ],
    controller : function(model,routeParameters){
      //route params are available via route.thingy, etc
      //this function is optional and exists for you
      //created by Ember
      //this method is available in my view
      this.posts = function(){
        //fetch from the model and return the result
      }

      //another...
      this.comments = function(){
        //etc
      }

    }
  }
}

The view is just a script tag with the id "index" in keeping with the spirit of Ember. In the view I can use all the same templating and expect to use whatever method/data that I've declared on my controller.

The nice thing about this setup is that I'm using the model as a separate idea - it's not magically melded to my controller and it keeps the concepts a bit cleaner (to me).

Let's put the name first and formalize the overrides in a single place. This is how I think about things, at least, and it would be nice to see it all in one place.

A Little Help?

OK, You've installed Ember after reading a tutorial. You've seen a post with the API above and you want to get started writing some code.

Ember has created the App for you, but it doesn't have a View:

Ember is installed and ready to go! The first step is to create a view:
<script type = "text/x-handlebars" data-template-name='application'></script>

Put that tag on your page where you want to see your app.

Nice - you copy paste that into your HTML page, and the next thing you see is...

Hello, Welcome To Ember

This is your Index space and you can override me by defining an index template:

< script type="text/x-handlebars" data-template-name="index">

... and overriding App.Index:


App.Index = function(){
  return {
    //the code you see above
  }
}
  

You can read the Documentation on what this is here.

Not only did Ember create an App for us - it also created a default Index "space" if you will. That Index defaulted to a nice helpful message on what to do next.

Arm Waving

That's what this is. I might be completely crazy, I might utterly misunderstand what Ember is trying to do.

I'll tell you this, however: if this is the way Ember crafted their API, I'd love it..

So there it is! I like being constructive when I can - hopefully this helps the team :).