Corpus

Corpus.js is a Javascript framework written entirely in CoffeeScript that makes it easy to develop large client side web applications without too much overhead.

Features

Light-weight URL Routing. (Does not support hashbang urls.. yet)
Modular views
Conventions for maintaining views
Models for persisting state
Model bindings
Written entirely in coffeescript
Currently developed with a RESTful ruby on rails backend in mind, but can be expanded for others.

Why not backbone, sproutcore, Sammy, etc?

Lighter weight than sproutcore
More modular than backbone (you can just take the model pieces if you want and ignore the controller/routes)
Doesn't have a view object like backbone, but merely enforces a sane and simple convention
Models have association support within a request. (backbone lacks this)
Models can bind to the changes events of form fields (backbone lacks this)
Written entirely in coffeescript. Most of the big client side microframeworks are written in javascript

Dependencies

JQuery 1.4+ (http://docs.jquery.com/Downloading_jQuery)
Underscore (http://documentcloud.github.com/underscore/)
JSON2 (https://github.com/douglascrockford/JSON-js)

Routing/Controllers

You can choose to use corpus routing or not. Presently it's only purpose is to load specific views/models when a specific page is loaded. This is helpful for consolidating behavior per page rather than having all of your JQuery selectors running on every page.

Example (posts.coffee)

$ -> 
  # Only runs the PostView.Form view when the /posts/new or /posts/:id/edit urls are requested
  _.each ["/posts/new", "/posts/:id/edit"], (route) ->
    $.R route, (id) ->
      post = new Post()
      new PostView.Form(post)

  # Only runs the PostView.Index view when the /posts url is requested
  $.R "/posts", -> new PostView.Index(post)

Models

To maintain state in the browser, Corpus provides a light-weight model layer that is similar to the popular server-side framework Ruby on Rails. Some of the features it provides are:

Key, value attributes management (managed attribute changes too)
Record UID's as well as database ID management
Associations
Persistence with a RESTful backend
Event system
Collections

Example

post.coffee

this.Post = Model "post"
Post.hasMany "comments"
Post.hasOne "user"

_.extend Post.prototype,
  initialize: (attributes) ->
    this.bind "save:before", this.onBeforeSave

  onBeforeSave: ->
    # do something

  createdAt: ->
    this.get("created_at")

  authorName: ->
    this.user.name()

comment.coffee

this.Comment = Model "comment"

This allows you to do the following:

post = new Post
post.set("body", "Lorem ipsum...")
comment = new Comment(body: "Some Comment")
post.comments.add comment
post.save
  success:
    # Do whatever
  error:
    # Validation errors

The json will look like:

{ 
  body: "Lorem Ipsum",
  comments: [
    body: "Lorem Ipsum"
  ]
}

Binding to events

post.comments.bind "add", ->
  # Will run code after a comment is added to the collection

post.comments.bind "refresh", ->
  # Will run code after the collection is changed

post.bind "change", ->
  # Will run when any of the attributes on a post have changed

Binding to forms

# Will automatically bind change events from fields in this form and update the post record. 
# Works with associations too!
post.bindTo "#post_form"

Views:

There is no special constant/class to extend for views. We merely use a convention at this point. In the future we may offer a constant/class you can extend for additional assistance but for now, the convention we've adopted has worked pretty well.

Example:

this.PostView.Form = (post) ->
  view = this
  $("#post_form").submit ->
    self = this
    post.save
      success: (respPost) ->
        if post.isNew
          post = respPost
        if $(self).data("redirect")
          document.location.href = $(self).data("redirect")
        $(self).trigger "saved"
      error: (post) ->
        $("#error_explanation ul").html("")
        messages = _.each post.errors(), (message, value) ->
          $("#error_explanation ul").append("<li>" + value + " " + message + "</li>");
        $("#error_explanation").show()

Recommended project directory structure using Barista + Ruby on Rails:

If you're using jammit with barista, you should use something like this:

app/coffeescripts/controllers/     # all of your controllers go here
app/coffeescripts/models/          # all of your models go here
app/coffeescripts/views/*/**       # all of your views go here
app/coffeescripts/vendor/          # all of your vendor files go in here. If you use only model.coffee for example, you can stick that file here.
app/coffeescripts/lib/             # all if your library files like underscore.string.coffee go here

If you're using barista, this should generate each of the above directories inside of public/javascripts/.

Recommended project directory structure using Rails 3:

app/assets/javascripts/controllers/     # all of your controllers go here
app/assets/javascripts/models/          # all of your models go here
app/assets/javascripts/views/*/**       # all of your views go here
app/assets/javascripts/vendor/          # all of your vendor files like model.coffee and route.coffee go here
app/assets/javascripts/lib/             # all if your library files like underscore.inflection.coffee go here

lancecarlson/corpus