ChaptersInstead of having another table to store the old versions for each model, we store all the required information in the same model table. This approach is similar to the one used in i18n, and leads to bigger tables, but also provides the simplicity to treat every version as a model instance.
Since versioning is usually a feature that is used only in determinated circumstances (e.g. when restoring an old version of something), the system is built in a way that using versions is explicit, and if no versioning info is used e.g. in searches, we get the usual, unversioned behaviour.
1 Creating versionable models
In this example we will create an Article model, which will be defined as versionable
1.1 Scaffolding
If you are going to start a fresh new model, the easiest and quickiest way to create a versionable model is using the ubiquo_model scaffold:
$ script/generate ubiquo_model Article title:string description:string --versionable
If the above is new for you, see the Ubiquo Scaffold guide
This will make the necessary changes in the model and migration to create an Article model which is defined as versionable. You could also have used ubiquo_scaffold, if you need a full scaffold, and the created controller and views would have been also filled with the particular ubiquo_versions goodies.
1.2 Manual creation
If you don’t want to use scaffolding, e.g. because the model file that you want to make versionable already exists, these are the changes that you’ll need to do:
1.2.1 Migrations
This is how the migration to create a table of a versioned model looks like:
create_table :articles, :versionable => true do |t|
t.string :title
t.string :description
...
end
As you can see, the only special thing here is that a versionable option is added, and will result in adding some versionable special meaning fields to the articles table. The rest of the attributes are created as usual.
1.2.2 Models
On models, we can flag a model as versionable just adding the following line:
class Article < ActiveRecord::Base
versionable
1.3 Using versionable models
So now that we have the Article model, it’s time to use it.
Article.create(:title => 'title', :description => 'desc', :locale => 'en')
Article.first.update_attribute :title, 'new_title'
The above code will generate two rows in the ‘articles’ table. The differences between them is that the original article (the one created first) is marked as the current_version, and its title is ‘new_title’. The other row is marked as a version of this article, and keeps the previous title, ‘title’.
But don’t get it wrong, these extra rows will not disturb us when doing our usual finds and operations:
Article.count # this returns 1
What if we really want to count or find all the articles including all the old versions? We just use a parameter to the desired method:
Article.count :version => :all
Article.all :version => :all
1.4 versions() method
The versions() method is an instance method that allows us to get a history of all the versions that a current instance (article, in this example) have. It is implemented as a named scope, so you can chain it with other filtering methods.
Article.first.versions
# returns all the versions from the first article
1.5 restore() method
You can use the restore() method to take back an instance to a previous state. It works as follows:
versions = Article.first.versions
Article.first.restore(versions.first.version_number)
This restores Article.first to the first of its versions. Each instance in a versionable model has a version_number, which is the argument that restore() expects.