backbone-hitch

Lightweight framework built on top of backbone

npm install backbone-hitch
1 downloads in the last week
1 downloads in the last month

Hitch v0.1.2

@see: CHANGES

Lightweight backbone-based single page application framework.

  • Default Hitch.Objects for users, credentials and roles
  • Powerful Access Control Layer for controlling access to Hitch.Routers
  • Auto-generate your hitch applications using the command-line tool
  • Provides a npm package.json like configuration file for building your application and to keep it up-to-date.
  • Modularized app structure based on the amd module pattern
  • Reduces glue code to a minimum
  • Generic view data binding using HTML data-attributes
  • Preloaded resources

===

Table of Contents:

Requirements

In general all necessary dependencies come with the installation of the node package. If you want Hitch to take care about the asset management you have to install lessc and/or scss to enable Hitch to use these for compiling your assets. Both tools are available as aptitude package so sudo apt-get install lessc scss will fit all your needs.

Installation

You can either install the npm package or clone this repository and build your custom Hitch installation.

Using the npm package

npm install backbone-hitch -g

Now you're ready to go.

Cloning the repository

git clone git@github.com/phillies2k/hitch.git
cd hitch && npm install

Now all necessary dependencies are available and Hitch can be used. Ensure to add the commandline tool in ./bin/hitch to your PATH variable.

Setup

Simply type in the following:

hitch create [path]

There are two ways to get your app working: Either you can configure a vhost for the public directory of your application or go to your "app/index.js" file and set the root property to your web-root pointing to your application's public directory. Point your browser to your application and have a look at your freshly created hitch application.

Configuration

Configuration means to modify your 'app.js' file which was created by either yourself or the command line tool when you created your application. The app.js is divided into several sections which specifies the application structure and environment.

Configuration Options
  • name - your application name
  • version - your application version
  • exports - Boolean (default:true) If value is a string your application will be exported with that name
  • apiUrl - your application's base api url
  • root - your application's web root path (defaults to '/')
  • pushState - Whether to use push state or not
  • resources - resource definitions
  • modules - module definitions
  • assets- your application styles and media
  • deployment- deployment configuration
Configuring resources

A resource can be configured as simple as "myresource": "true". This resource will then be loaded on initialization.

{
  ...
  resources: {
    users: "true"
  }
}
Configuring assets

Assets of type text/less or text/scss will be compiled using an appropriate compiler for either LESS- or SASS-like stylesheets.

{
  ...
  assets: [
    {
      type: "scss",
      path: "scss/layout/common"
    }
  ]
}
Configuring modules

A module can have a permissions property for configuring access to this module (e.g. access to the routes). Furthermore a special property named "resource" is available to define a resource this module manages.

{
  ...
  modules: {
    users: {
      resource: "users",
      permissions: {
        edit: {
          ...
        }
      }
    }
  }
}

Using the Command-Line Tool

Hitchs command line tool offers a bunch of helpful tools to ease up developers life when using Hitch to create single page applications. See hitch help for a detailed documentation.

The create command
hitch create [target]

your target can either be the path of the hitch application you want to create or one of the following targets:

  • resource - will create a new resource
  • module - will create a module

Its recommended that you use the create [resource|module] [name] commands with care because app.js will not be updated when creating targets manually. You have to extend the app.js file by yourself.

The build command
hitch build [target]

your build target can either be empty ( will execute all building tasks ) or one of the following tasks:

  • resources - will create non existing resources
  • modules - will initialize non existing modules
  • main - will rebuild your bootstrap file. This is necessary to call after every update to resources or modules to
         ensure everything will be loaded.
    
  • all - executes all task at once (same as calling build with no target given.
The deploy command
hitch deploy

This command tries to deploy your project to the deployment configuration found in your app.js. It will create a build/ folder in your application root and will deploy your compiled application to a new sub folder build/$version$/. It will also create build/config.js which holds the requirejs r.js build configuration to combine/uglify your applications code. It will also deploy your assets by using an appropriate compiler to compile LESS and SASS stylesheets.

Currently the deployment only works for 'deployment.server = 'local'.

Packages

Hitch.Access

The acl public interface mixin

Hitch.ACL

Represents an acl instance

Hitch.App

Represents a hitch web application

Represents a cookie

Hitch.Cookies

Provides a CRUD-like interface for cookie access.

Hitch.Credentials

A ready-to-use login interface

Hitch.Helpers

Provides several helper methods that will be mixed in into underscore for being available within the rendering context of your views.

Hitch.Object

The enhanced Backbone.Model

Hitch.Resource

The enhanced Backbone.Collection

Hitch.Role

A default role model representation

Hitch.Router

The enhanced Backbone.Router

Hitch.User

A default user model representation

Hitch.View

The enhanced Backbone.View

npm loves you