Using BPM with Ember

ud3323 edited this page Feb 18, 2012 · 19 revisions

BPM makes it easy to get started on a new project using Ember.js. I would like to see this further simplified in the future, but for now these steps should get you going:

Create Your New App and Add Dependencies

On the console do the following:

bpm init hello_world
cd hello_world
bpm add ember
bpm add spade

This will add emberjs as a dependency on your project and use the spade module loader to manage your app code. Spade is not required to build a Ember.js app but it is highly recommended since it will minimize your app load time on mobile and make it easy to break your code up into loadable modules later on.

Add The Spade Bootstrap

Since your app is being managed by Spade for module loading, you will need to add a little code to your index.html to bootstrap your app on page ready. [NOTE: This should be actually built into spade at some point in the future - hopefully this is just temporary. But this code will always work.]

In your index.html file, just below the script that loads bpm_libs.js add:

  <script type="text/javascript">
    spade.require('hello_world');
  </script>

Of course, replace hello_world with the name of the app you supplied to bpm init earlier.

Just to test this, open the file in lib/main.js and add this line:

 alert('HELLO');

Preview Your App

Now start your preview server and make sure it works. On the console:

bpm preview

Then open http://localhost:4020/index.html. When the page loads you should see the 'HELLO' alert appear. If it does then everything is bootstrapped correctly and you can go onto the next thing.

Modify the app's package file

Open your hello_world.json file. This is the project file that is used by BPM to configure how it does builds. We want to add a version number for the project. This will be useful for keeping track of your deployed app version down the road. Look for a top level key named "bpm". Just below that add:

"version": "0.0.1",

Setup Your App Namespace

Next we want to add a core.js file where you can define your application namespace. Modify lib/main.js to the following:

modify lib/main.js:

spade.require('ember'); // load Ember.js dependencies
HelloWorld = Ember.Application.create({
  VERSION:  require('hello_world/~package').version
});

Adding Support for Templates

OK now that everything is basically working, we want to get some basic Ember.js files setup so you can start writing your app.

We are going to want a templates directory where we can keep our Handlebars templates. Create a templates directory inside of the lib directory.

Next, under the lib directory create a file called templates.js. Modify this file as follows:

lib/templates.js

Ember.TEMPLATES['main_page'] = spade.require('hello_world/templates/main_page');

Below is a breakdown of the template include statement:

Ember.TEMPLATES['TEMPLATE_NAME'] = spade.require('APP_NAME/templates/TEMPLATE_FILENAME_WITHOUT_EXTENSION');

TEMPLATE_NAME: The string used to identify the template in your app. This is the string you'd use for the templateName property on some view you're creating.

APP_NAME: The application's name.

TEMPLATE_FILENAME_WITHOUT_EXTENSION: The filename for the template you want to include minus the .handlebars extension.

Create Your First Template

Next, let's create a starter template for you also:

create lib/templates/main_page.handlebars:

Congratulations!  You are running HelloWorld v{{HelloWorld.VERSION}}

And in finally we need to update your main.js file so that it creates a view to use the template and displays it.

in lib/main.js:

spade.require('./core'); // make sure the app namespace loads first
spade.require('hello_world/templates');

HelloWorld = Ember.Application.create({
    VERSION:  '0.1.0'
});

Ember.View.create({
   templateName: 'main_page'
}).append();

Try It Out!

Now kill your bpm preview if it is still running and restart it. Then visit http://localhost:4020/index.html

You should see a page that says "Congratulations! You are now running Hello World v0.0.1"

You are all set to go!

Note: If you are getting the error "Unable to find template", please make sure you are using Ember.js 0.9.4 or greater from getbpm.org.

Adding Other Dependencies

At this time you can also add any other dependencies you might want. For example, I like to write my apps in CoffeeScript so:

bpm add coffee-script

Note that Ember.js does not ship with the DataStore or Touch system as part of the default bundle. If you want to add these two you can do so now as well:

bpm add ember-datastore ember-touch

Also, I like to use Twitter-Bootstrap in my projects. You can add it with:

bpm add twitter-bootstrap

To see a complete list of the packages available visit http://getbpm.org or you can use

bpm list --remote
bpm list --remote --pre

To see both officially released and pre-released packages.