How to layout a BackboneJS project in CakePHP using GruntJS

BackboneJS does not seem to come with a recommended layout for its file structure, though Yeoman suggests it’s own concept of laying out a BackboneJS project. I took inspiration from Yeoman to put together this approach for laying out a BackboneJS project inside the CakePHP framework. CakePHP is convention over configuration and expects you to put all your assets inside cakeroot/app/webroot/.

For the sake of this tutorial, I m going to create my files based on a simple ToDo project since almost every developer creates a ToDo app at least once! The ToDo list app for this project has a database with 3 tables:

users
categories
tasks

Inside webroot/js, create the following directories

vendor
src
collections
models
views

Yeoman generates directories for routes, helpers and templates. I m not going to add these coz I dont need them. For routes, I m going to use only one file and it can stay inside the js folder alongside my main.js file. I have a feeling that the convention to use main.js comes from ActionScript 3.0 projects (though I do not have any proof of this)

Once you ve created your directories in the js folder, its time to put in some files. Here is the same directory structure for the js/ directory, but includes files that are based on my database schema.

js/
  main.js
  application-router.js
  vendor/
    jquery.min.js
    underscore.min.js
    backbone.min.js
  src/
  collections/
    application-collection.js
    categories-collection.js
    tasks-collection.js
  models/
    application-model.js
    category-model.js
    task-model.js
    user-model.js
  views/
    application-view.js
    categories-view.js
    task-view.js
    user-view.js

Yeoman creates the main.js with one global variable based on the name of your project and creates placeholders within that for our models, collections, views and routes. Here s a sample of it:

window.ProjectName = {
    Models: {},
    Collections: {},
    Views: {},
    Routers: {},
}

Now, while defining your models or collections or views, make sure to namespace it inside ProjectName.Models or ProjectName.Collections or ProjectName.Views. For example, our task-model would look like this:

ProjectName.Models.TaskModel = Backbone.Model.extend({
  defaults: {}
});

Notice the name of the model. The file was named task-model.js and the model itself is called TaskModel. This is just a convention. You can change this to whatever you think is better for you.

Finally templates, Yeoman does create a structure for that but I figured that out the easy way that it has not yet implemented the feature where you can define .ejs files inside your templates directory and use em from there. At least not as of this post. So instead of trying to do that, we can just define the templates inside a directory inside app/View/Elements/Templates. We can then render that element in Cake’s view file which also has the scripts pulled in for our app. For this tutorial, I have a controller called UsersController.php and I have routed /app to UsersControllers:app

Router::connect('/app', array('controller' => 'users', 'action' => 'app'));

Since that s how the route is defined, we need to have a file at app/View/User/app.ctp. At the beginning of this render the templates file and at the end of the same file, pull in the required JS files.

For now I ll just pull all the required JS files from CakePHP’s perspective (later we’ll use Grunt):

//vendor
echo $this->Html->script('vendor/jquery-1.9.1.min');
echo $this->Html->script('vendor/underscore-min');
echo $this->Html->script('vendor/backbone-min');

//src
echo $this->Html->script('src/main');
echo $this->Html->script('src/application-router');
//collections
echo $this->Html->script('src/collections/application-collection');
echo $this->Html->script('src/collections/categories-collection');
echo $this->Html->script('src/collections/tasks-collection');
//models
echo $this->Html->script('src/models/application-model');
echo $this->Html->script('src/models/user-model');
echo $this->Html->script('src/models/category-model');
echo $this->Html->script('src/models/task-model');
//views
echo $this->Html->script('src/views/application-view');
echo $this->Html->script('src/views/user-view');
echo $this->Html->script('src/views/category-view');
echo $this->Html->script('src/views/task-view');

Lets say your application-router.js file looks like this:

ProjectName.Routers.ApplicationRouter = Backbone.Router.extend({
    routes: {
        "": "firstrun",

    },
    firstrun: function() {
        console.log("router - firstrun");
    }
});

Then at the end of all the javascript calls, create script tag and create a router object and kick start the show!

(function(){
    var router = new ProjectName.Routers.ApplicationRouter();
    Backbone.history.start();
})();

We could even use GruntJS and have all the JavaScript and CSS files uglified or minified into one single app.js and app.css file and just pull that instead. To do so you ll need NodeJS and Node Package Manager installed. If you do have these installed, then create a file called package.json inside cakeroot/app/. I m not using the webroot directory coz I dont want my Gruntfile and package.json file to be publicly accessible. Inside your package.json file you could do something like this:

{
  "name": "ProjectName",
  "title": "ProjectName",
  "version": "2.0.0",
  "devDependencies": {
    "grunt-contrib-uglify": "~0.1.1",
    "grunt-contrib-watch": "~0.2.0",
    "grunt": "~0.4.1",
    "grunt-contrib-cssmin": "~0.6.0"
  }
}

Then, add n navigate to your app folder in a terminal and run:
npm install

Once the required modules are installed, you can add app/node_modules to your .gitignore file. Then create a file (inside app/) called Gruntfile.js (unless it is not already created) and enter something like this:

module.exports = function (grunt) {
    grunt.initConfig({
        pkg: grunt.file.readJSON('package.json'),
        uglify: {
          options: {
            banner: '/*!    */'
          },
          dist: {
            src: [
              'webroot/js/src/main.js',
              'webroot/js/src/router.js',
              'webroot/js/src/collections/*',
              'webroot/js/src/models/*',
              'webroot/js/src/views/*',
            ],
            dest: 'webroot/js/app.js'
          },
        },
        cssmin: {
          compress: {
            options: {
              banner: '/*    */'
            },
            files: {
              'webroot/css/app.css': ['webroot/css/reset.css', 'webroot/css/style.css']
            }
          },
        },
        watch: {
          scripts: {
            files: [
              'webroot/js/src/main.js',
              'webroot/js/src/router.js',
              'webroot/js/src/collections/*',
              'webroot/js/src/models/*',
              'webroot/js/src/views/*',
              'webroot/css/*'
            ],
            tasks: ['uglify', 'cssmin'],
            options: {
              nospawn: true
            }
          }
        }
    });
    grunt.loadNpmTasks('grunt-contrib-uglify');
    grunt.loadNpmTasks('grunt-contrib-cssmin');
    grunt.loadNpmTasks('grunt-contrib-watch');
    //register default task
    grunt.registerTask('default', 'watch');
}

I m just using uglify and cssmin along with watch. You can add whatever else you may need. After that you wont need to pull all those JS files in your view file. As you may already know, the browser pulls 2 files at a time from the server. So if you have 16 files (including Javascript as well as CSS), then it ll make 8 trips to the server and back!

Now that we have some grunt tasks running, we can reduce the round trips to the server (and cut file size considerably). Run ‘grunt’ from the ‘app/’ directory in a terminal and marvel at the ‘magic’ from the contributors of Grunt as you make even the tiniest of the changes to the files that are being ‘watched’. These views are just my idea based on how Yeoman lays out a Backbone JS project. If you have some suggestions to improve this, then please do share.

Categories: How To, Javascript | Tags: backbonejs, cakephp, gruntjs, javascript | Leave a comment