xlogan/backbone-express-spa

Backbone.js + Express.js single page application boilerplate

Backbone.js + Express.js SPA boilerplate

To build single pages application is seconds, not hours.

NOTE: it still in progress. If you would like to contribute, please join the discussion/implementation of currently opened issues.

Contents

• Description
• Application example
• Installation
• Express.js
  • Serving master page
  • API end-points
  • Authorization and CORS
• Backbone.js
  • RequireJS and CommonJS
  • Routing
  • View Manager
  • Applications
  • Main view and subviews
  • Transitions
• Testing
  • Backbone.js (front-end) tests
  • Express.js (back-end) tests
  • Functional (web driver) tests
• SEO
• Build for production
• Deployment

## Description

SPA infrastructure setup could be time consuming. It's typical problem, to configure requirejs, initial routing and view manager, to prevent memory leaks. This project could be used as good start to build own single page application.

This project is complete and minimal setup for building single page applications running on Express.js framework as back-end and Backbone.js as front-end.

SPA itself is rather simple concept, but it requires some infrastructure to have in place, before build up new application. This project already includes this infrastructure.

## Application example

'TheMailer' - simple app for managing emails, contacts, tasks.

## Installation

Clone github repository,

$ git clone [email protected]:alexanderbeletsky/backbone-express-spa.git

Install npm dependencies,

$ npm install

Install bower dependencies,

$ bower install

Run app (development mode),

$ node app.js

## Express.js

Express.js is used as back-end development framework. It's simple and easy to configure for SPA.

In API-oriented architecture back-end is responsible for 2 main purposes:

• Serving master page html
• Providing API end-points for web client

Master page

Master page is main (and typically one) html page returned from server. It includes all styles and javascript, provides very basic layout and placeholder for application.

<div class="container">
	<div id="app" class="container"></div>
</div>

After master page is served back to client the rest of UI and logic is build by Backbone.js.

### Serving master page

To serve master pages application includes middleware component serveMaster.js. It would respond with master page html for any request, expect the requests for /api, /components, /css/ or /js.

### API end-points

API is HTTP, JSON based end-points. Sources are located at source/api. Each API module returns a function that takes app instance and setup HTTP verb handler for a route.

module.exports = function (app) {
	app.get('/api/emails', function (req, res) {
		res.json({status: 'GET /api/users'});
	});

	app.post('/api/emails', function (req, res) {
		res.json({status: 'POST /api/users'});
	});

	app.put('/api/emails/:id', function (req, res) {
		res.json({status: 'PUT /api/users/' + req.params.id});
	});

	app.del('/api/emails/:id', function (req, res) {
		res.json({status: 'DELETE /api/users/' + req.params.id});
	});
};

To enable API end-point, you should modify app.js file, like

// api endpoints
require('./source/api/emails')(app);
require('./source/api/contacts')(app);
require('./source/api/tasks')(app);

## Authorization and CORS

TODO.

## Backbone.js

Backbone.js is the one of most popular front-end development framework (library). It provides abstractions for models, views, collections and able to handle client-side routing.

Front-end architecture is build on modular structure and relying on AMD to allow build scalable applications.

### RequireJS and CommonJS

RequireJS picked up as asynchronous javascript module loading. RequireJS uses it's own style for defining modules, specifying the dependency as array of strings.

define([
	'/some/dep',
	'another/dep',
	'yet/another/dep',
	'text!./templates/template.html,
	jQuery,
	Backbone'], function(SomeDep, AnotherDep, YetAnotherDep, template, $, Backbone) {
		// module implementation...
	});

With some time spent on Node.js programming, CommonJS style becomes more convenient to use. Fortunately RequireJS has CommonJS style implementation.

define(function (require) {
	// dependencies
	var SomeDep = require('/some/dep');
	var AnotherDep = require('another/dep');

	// export
	return {};
});

### Routing

All routing logic is placed in /core/router.js. There are 3 routes defined in boilerplate.

Each route handler is responsible for starting up new application. Application run function takes ViewManager instance.

### View manager

SPA application typical threat is memory leaks. Memory leaks might appear for a few reasons, one of the most famous reason for Backbone applications are, so called, zombie views.

/core/viewManager.js is responsible for disposing views during switch from one router to another.

Besides of that, it handles transitions during application switch.

### Applications

Application is concept of grouping models, collections, views of unit in one place. The rule is, "one route - one application". Router matches the route, loading the application entry point and passes viewManager (or any other parameters, like id's or query strings) into application.

All applications are apps folder.

app.js is entry point of application and it's responsible for several things:

• Fetching initial application data
• Instantiating Main View of application

define(function(require) {
	var MainView = require('./views/MainView');

	return {
		run: function (viewManager) {
			var view = new MainView();
			viewManager.show(view);
		}
	};
});

### Main view and subviews

Main view responsible for UI of application. It's quite typically that main view is only instantiating subviews and passing the models/collections further down.

MainView.js keeps track of subviews in this.subviews arrays. Each subview will be closed by ViewManager dispose function.

var MainView = Backbone.View.extend({
	initialize: function () {
		this.subviews = [];
	},

	render: function () {
		var headerView = new HeaderView();
		this.subviews.push(headerView);
		this.$el.append(headerView.render().el);

		var footerView = new FooterView();
		this.subviews.push(footerView);
		this.$el.append(footerView.render().el);

		return this;
	}
});

### Templates

Handlebars is picked up as templating engine, powered by require-handlebars-plugin. Templates are stored on application level in template folder. Handlebars plugin is configured to keep templates in .html files.

View is loading template through !hbs plugin and uses that in render() function.

var HeaderView = Backbone.View.extend({
	template: require('hbs!./../templates/HeaderView'),

	render: function () {
		this.$el.html(this.template({title: 'Backbone SPA boilerplate'}));
		return this;
	}
});

## Transitions

Transitions is a very nice feature for single pages applications. It adds the visual effects of switching from one application to another.

Boilerplate is relying on wonderful animate.css library. core/transition.js is responsible for applying transition style. It's being called from /core/viewManager.js.

Once you decide to have transitions in your app, simply modify master.ejs and add data-transition attribute to application div.

<div class="container">
	<div id="app" class="container" data-transition="fadeOutLeft"></div>
</div>

Checkout the list of available transitions on animate.css page. You can apply anything you want, please note "Out" transition type is suited the best.

## Testing

TODO.

### Backbone.js (front-end) tests

TODO.

### Express.js (back-end) tests

TODO.

### Functional (web driver) tests

TODO.

## SEO

TODO.

## Build for production

TODO.

## Deployment

TODO.

Legal Info (MIT License)

Copyright (c) 2013 Alexander Beletsky

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.