without_scope

I’ve been working on this on and off for the better part of the last year. Life has intruded many times but, I’ve finally got it to a point that I’m comfortable releasing as a 1.0.

This plugin grew out of Stephen Caudill and my use of Rick Olsen’s ActsAsVersioned. The application was centered around versioning of our user’s resources. Early on, AAV worked great for us but, as our requirements got more complicated we found ourselves hacking AAV more and more.

Eventually Stephen came to the conclusion that we needed to break from AAV and roll our own. So he laid out the requirements and I built it. I’m going to talk about all of AAR’s features through a series of posts but, I thought I’d quickly highlight some of it’s unique features now.

Pervasive Callbacks

AAR was created to help build applications that need precise control of the life-cycle of it’s data. In pursuit of that, there is a full suite of callbacks:

• revisable models
  • before_revise
  • after_revise
  • before_revert
  • after_revert
  • before_changeset
  • after_changeset
  • after_branch_created
  • before_revise_on_destroy
  • after_revise_on_destroy
• revision models
  • before_restore
  • after_restore
• both revisable and revision models
  • before_branch
  • after_branch

AAR callbacks act just like ActiveRecord callbacks. They accept all the same arguments and they can prevent the action being taken just like AR callbacks.

Branching and Changesets

Branching is a well understood concept, no need to go in depth on this, here’s the relevant code:

  @branch = @post.branch
  @branch.branch_source == @post # => true

Changesets are a bit more interesting. In non-trivial code you may end up a block of code that may perform many actions that each cause a revision to be saved. If you wish to group those as a single revision, you can:

  @post.changeset do 
    @post.title = "A post"
    # save would normally trigger a revision
    @post.save
    # update_attribute triggers a save triggering a revision (normally)
    @post.updated_attribute(:title, "Another Title")
    # revise! normally forces a revision to be created
    @post.revise!
  end

Deletes can be stored as a revision

This is pretty simple, #destroy no longer destroys the record. It flags it as deleted. Deleted records can then be accessed through the revision class’ #deleted named_scope.

  class Post < ActiveRecord::Base
    acts_as_revisable :on_delete => :revise
  end

  @post.destroy
  PostRevision.deleted # => [@post]

Explicit is better than implicit

ActsAsRevisable will not, by default, define the revision class for you. The most common configuration is as follows:

  class Post < ActiveRecord::Base
    acts_as_revisable
  end

  class PostRevision < ActiveRecord::Base
    acts_as_revision
  end

If you want to call your revision class something else, you can:

  class Post < ActiveRecord::Base
    acts_as_revisable :revision_class_name => 'OldPost'
  end

  class OldPost < ActiveRecord::Base
    acts_as_revision :revisable_class_name => 'Post'
  end

If you absolutely must have AAR generate the class for you:

  class Post < ActiveRecord::Base
    acts_as_revisable :generate_revision_class => true
  end

All data for a model is stored in one table

There isn’t a separate versions table. This comes from the belief that all Posts (or whatever your model happens to be) are Posts whether or not they’re the current version.

This also makes it much easier to find records whether or not they’re the current version or not:

  Post.find(:all, :conditions => {...}, :with_revisions => true)

Wrapping up, requirements and installing

There’s a lot of flexibility here. In the application AAR was built for we were using it to version entire trees of objects together, not just individual records. I plan on digging into this and more in future posts.

AAR 1.0 requires Rails 2.3. You can take a look at the code on GitHub.

  sudo gem install rich-acts_as_revisable --source=http://gems.github.com

Once the gem is installed you’ll want to activate it in your Rails app by adding the following line to config/environment.rb:

  config.gem "rich-acts_as_revisable", :lib => "acts_as_revisable", :source => "http://gems.github.com"