The landscape of web application development is constantly changing. New technologies pop up all around, and “definition” of a modern web application becomes more and more complex.
Ember.js is one of these new technologies. It is a rich front end application framework for developing ambitious web applications. Ember borrows many core ideas from desktop frameworks like Cocoa, which has been used in building desktop/mobile applications for decades. Ember also relies heavily on the concept of “Convention over Configuration”. When building Ember applications, a developer can lean on these conventions and their applications will “just work”.
I have been working with Ember.js extensively for the last few months, and have found that Ember is even better when there is a build process backing it. The CakePHP-Ember-Skel is a starting point for CakePHP developers to use Ember.js without having to spend a ton of time setting up the build process. This skeleton should get you up and running quickly, and includes all the files necessary to do so. If you’d like to tweak the build process in the future, everything you’ll need is here. Let’s get started.
Requirements
Before we begin installing and setting up our first CakePHP Ember app, lets review the requirements. This skeleton utilizes grunt, which can be installed with npm (the package system for Node.js). To use grunt, you’ll need the following tools installed:
Once you’ve installed these tools, come back and we’ll start the installation.
Installation
The CakePHP-Ember-Skel is a replacement for the default project skeleton that is used when you bake a new CakePHP project. A project skeleton is simply the files that are copied into place during the project setup. To tell CakePHP to use a different skeleton, use the ‐‐skel /path/to/CakePHP-Ember-Skel option. Lets set that up.
We’ll want to install the CakePHP-Ember-Skel in a location that you’ll remember. I personally use /Developer from the days when Xcode would install itself there (I also install versions of CakePHP there too). For the remainder of this tutorial, I’m going to reference the installation directory as /Developer/Skel, so replace that with the path that you have chosen.
Lets create the directory that the CakePHP-Ember-Skel is going to live in, and move into that directory:
mkdir -p /Developer/Skel cd /Developer/Skel
Now lets clone the CakePHP-Ember-Skel into this directory:
git clone https://github.com/loadsys/CakePHP-Ember-Skel.git
The last step is to create our CakePHP project:
cd /path/to/www_root /path/to/cakephp2/lib/Cake/Console/cake bake project ember_test --skel /Developer/Skel/CakePHP-Ember-Skel
Now you should have a fresh CakePHP project in a directory called ember_test that contains the content of the CakePHP-Ember-Skel. Next we’ll handle a few project cleanup tasks before digging into what is included with the CakePHP-Ember-Skel.
You may have noticed that I used /path/to/cakephp2/lib/Cake/Console/cake above to access the cake command. We feel that it is a good practice to install versions of CakePHP into a globally accessible location. Since typing /path/to/cakephp2/lib/Cake/Console/cake is long and annoying, I would recommend setting up an alias in your ~/.bash_profile (or ~/.zshrc for zsh users). I do alias cake2=”/Developer/Frameworks/cakephp-2.3.0/lib/Cake/Console/cake” in my ~/.zshrc. During the setup process, I’ll explain why this is a good idea.
Setup
After baking this project, there are a few steps to take care of. The CakePHP-Ember-Skel comes with a interactive clean up shell that will take care of a few things.
cd ember_test Console/cake cleanup
This shell will take you through the following:
- Removing the .git/ directory that belongs to the CakePHP-Ember-Skel project
- Symlinking the CakePHP core in Lib/ and Update the CAKE_CORE_INCLUDE_PATH in webroot/index.php and webroot/test.php. Also adding Lib/ to include_path in Console/cake.php for console commands.
- Copying the Config/database.php.default to Config/database.php
- Replacing View/Pages/home.ctp with View/Pages/home.ctp.ember
Be aware that this skeleton project includes both a Config/core.php.default and Config/core.php. The included .gitignore will ignore the Config/core.php, but including it by default removes the step of copying it.
I think that most of those are pretty self explanatory, but allow me to explain number 2 some more. It seems pretty common to need multiple CakePHP core versions if you have different apps on the same system. The way we handle this is to install the core versions in the globally accessible location (I mentioned that I put mine in /Developer/Frameworks). As a convention, we set the CAKE_CORE_INCLUDE_PATH to be the Lib/ directory in each app. We then create a symlink inside of the Lib/ directory that points to the core version for this app. This is great for 2 reasons. Now it really doesn’t matter where the core is installed, and any new person on your team can have their cores installed in a different place than you. It also makes upgrading really easy because all you have to do is create a new symlink to the upgraded core.
We’ve got the project cleaned up, and it is now time to get the Ember.js application working. Before we can use grunt, we’ll have to install a few node packages.
npm install
After the required packages are installed, we can use the default grunt task to build our asset files and we can then visit the application in the browser. Run the grunt command to build the assets.
grunt
As long as Node.js, npm, and grunt are installed, you should see some output informing you of the progress. Once the task is complete, we can go to the app in the browser at http://localhost/ember_test. You should see a screen like this:
Congratulations! You’ve started an Ember.js application.
What’s Included
Now that we’ve got a new project set up with Ember.js baked in, lets review what is included with the CakePHP-Ember-Skel. We’ve already discussed the cleanup shell, but there is more shell goodness included.
Bundled with the CakePHP-Ember-Skel is the CakePHP-Ember Plugin. This plugin comes with some interactive bake shells similar to the CakePHP Bake shell. This shell will generate Ember.js class files that follow the convention we’ve put forward.
The basic usage is to just start the interactive shell:
Console/cake Ember.generate
This will start the interactive prompt where you can select the type of object you wish to create.
You can also jump into the individual class type interactive prompt by adding the class type to the end of the command (valid types are ‘controller’, ‘model’, ‘view’, and ‘route’).
Console/cake Ember.generate controller
And finally, you can skip the interactive prompt completely by specifying a class name (and optionally a object type for controllers and views) in the command itself.
// Just specify the class name Console/cake Ember.generate model Post
// Specify the class name and object type Console/cake Ember.generate view Posts View
In later tutorials, we’ll cover the different object types for controllers and views. For now, just know that for controllers the three types are Controller, Array, and Object, and for views the three types are View, Container, and Collection.
That’s it for shells. There are a few other things that come with the CakePHP-Ember Plugin though. One is a component that handles ajax data coming from Ember-Data, and we’ll discuss that when we start creating the api. The other is a helper for building the handlebars templates.
This helper is used by default in View/Pages/home.ctp (assuming you followed the bit about replacing the home.ctp in the cleanup shell). What it will do is recursively load all the templates that are in webroot/js/app/Template, and wrap the content in a script tag. The name of the template (the value added to data-template-name on the script tag) will be path/templateName. For example, there is already an application.handlebars in webroot/js/app/Template, and it’s template name would be application. If you were to create a directory called posts in Template, and add the file index.handlebars, its template name would be `posts/index’. This conforms to the conventional naming for Ember templates.
Next Time
So that’s about it for this introduction. In the next tutorial, we’ll go in depth with the grunt.js build file, our proposed file naming conventions, and the minimum viable Ember.js application. Further down the road, we’ll have a series of tutorials for building an Ember.js application that is backed by a CakePHP REST api.
Loadsys is now becoming an ember company, along with still providing CakePHP. By providing ember development we can provide ember support at an enterprise level, for companies taking on this new exciting technology.