Today we're going to talk about versioning. How to version your models to be more specific.
Versioning my models ? What is that ?
It's simple. For example, if you have a document that many people can edit, like a Google Doc, you better keep the previous versions of the file. Just in case someone does some s*** on it. That's exactly what we're going to do in this Jutsu ! Let's get started.
The project
The web app we will create is a simplified version of Google Docs. Very, very simplified. You will have a list of files that anyone can edit, based on a very simple authentication system. You will be able to see all the previous versions of the file, and who changed it. You will also be able to rollback to a previous version of your choice. To do all this, we're going to use the PaperTrail gem.
Setup the app
In this guide, we won't build the app from scratch like usually. Instead, you can pull the code from Github.
git clone https://github.com/T-Dnzt/papertrail-jutsu-initial.git ./papertrail-jutsu && cd papertrail-jutsu
Run the migration, bundle and start the app :
rake db:migrate
bundle install
rails server
If you head over to localhost:3000, you should see the following :
You can enter your name and access the app. Once logged in, you should be able to manage documents.
PaperTrail
Let's add PaperTrail which will automatically keep track of what happened to our documents.
# Gemfile
gem 'paper_trail'
Now, 3 steps in one line to get it to work :
bundle install && bundle exec rails generate paper_trail:install && bundle exec rake db:migrate
Restart your server before continuing.
After that, we can add PaperTrail to the model we want to version :
# app/models/document.rb
class Document < ActiveRecord::Base
belongs_to :user
has_paper_trail
def user_name
user ? user.name : ''
end
end
And that's it ! Now everytime we save our model, we'll get the previous version saved by PaperTrail :
PaperTrail::Version.all
# => #<ActiveRecord::Relation [#<PaperTrail::Version id: 1, item_type: "Document", item_id: 1, event: "update", whodunnit: "1", object: "---\nid: 1\nname: Abcz\ncontent: aaa\nuser_id: 1\ncreat...", created_at: "2014-09-26 15:38:14">]>
Listing the previous versions
Now, let's see what we can do with that! First, we're going to add the list of versions for a specific document. We're going to need a way to easily get the name of someone who authored a version. For that, we need a helper method and a method in the User model :
# app/helpers/documents_helper.rb
module DocumentsHelper
def find_version_author_name(version)
user = User.find_version_author(version)
user ? user.name : ''
end
end
# app/models/user.rb
class User < ActiveRecord::Base
has_many :documents
def self.find_version_author(version)
find(version.terminator)
end
end
Now, let's add the actual list of versions to the edit document view as a partial :
# app/views/documents/_versions.html.erb
<h2>Previous Versions</h2>
<table class='table'>
<thead>
<tr>
<th>Index</th>
<th>Date</th>
<th>Author</th>
<th>Event</th>
<th></th>
<th></th>
<th></th>
</tr>
</thead>
<tbody>
<%- document.versions.reverse.each do |version| %>
<tr>
<td><%= version.index %></td>
<td><%= version.created_at %></td>
<td><%= find_version_author_name(version) %></td>
<td><%= version.event.humanize %></td>
<td><%= link_to 'Diff', '' %></td>
<td><%= link_to 'Rollback', '' %></td>
</tr>
<% end %>
</tbody>
</table>
And render this partial after the Document form :
# app/views/documents/edit.html.erb
...
<%= render 'form' %>
<%= render 'documents/versions', document: @document %>
Now you can udpate any document a few times (create one if you don't have any yet).
You should see the list of versions growing !
Add Diff & Rollback
So, you've probably noticed the two empty links named 'diff' and 'rollback'. You probably already know what we're going to do with those. Clicking on diff will show us a new page with the difference between the clicked version and the current version. Rollback will simply change the current object to be like the clicked version. Let's go!
First, we're going to update the edit document view to add action to the links :
# app/views/documents/_versions.html.erb
<td><%= link_to 'Diff', diff_document_version_path(document, version) %></td>
<td><%= link_to 'Rollback', rollback_document_version_path(document, version), method: 'PATCH' %></td>
Then we need the routes :
# config/routes.rb
resources :documents do
resources :versions, only: [:destroy] do
member do
get :diff, to: 'versions#diff'
patch :rollback, to: 'versions#rollback'
end
end
end
And finally, we create the controller :
# app/controllers/versions_controller.rb
class VersionsController < ApplicationController
before_action :require_user
before_action :set_document_and_version, only: [:diff, :rollback, :destroy]
def diff
end
def rollback
# change the current document to the specified version
# reify gives you the object of this version
document = @version.reify
document.save
redirect_to edit_document_path(document)
end
private
def set_document_and_version
@document = Document.find(params[:document_id])
@version = @document.versions.find(params[:id])
end
end
If you try to diff a version, you will get a missing template exception. However, you can already rollback to a previous version! Pretty cool, huh!
All we need for the diff to work now, is a view. We could build one by ourselves, but let's not reinvent the wheel. We're going to use the very nice gem Diffy. Diffy gives us an easy way to diff content (files or strings) in Ruby by using Unix diff.
Diff with Diffy
Add the gem to your Gemfile :
# Gemfile
...
gem 'paper_trail'
gem 'diffy'
...
bundle install and restart your server.
Since we will be using the same diff logic for the name and content of a document, let's create a helper method :
# app/helpers/documents_helper.rb
def diff(content1, content2)
changes = Diffy::Diff.new(content1, content2,
include_plus_and_minus_in_html: true,
include_diff_info: true)
changes.to_s.present? ? changes.to_s(:html).html_safe : 'No Changes'
end
Basically, we just tell Diffy that we want to generate html if there is any difference between the 2 strings. We also want to have the diff info (number of lines changed, etc) and the + and - that everbody likes!
Now the actual diff view is pretty simple to build. We're going to create it in app/views/versions/ :
# app/views/versions/diff.html.erb
<div class='row mt'>
<div class='col-sm-12'>
<h2><%= "Diff between Version #{@version.id} and Current Version" %></h2>
<style><%= Diffy::CSS %></style>
<div class='well diff'>
<p>
<strong>Name:</strong>
<%= diff(@version.reify.name, @document.name) %>
</p>
<p>
<strong>Content:</strong>
<%= diff(@version.reify.content, @document.content) %>
</p>
</div>
<p>
<%= "Version authored by #{find_version_author_name(@version)} on #{@version.created_at} by '#{@version.event.humanize}'." %>
</p>
</div>
</div>
<div class='fr'>
<%= link_to 'Back', edit_document_path(@document), class: 'btn btn-danger' %>
<%= link_to 'Rollback', rollback_document_version_path(@document, @version), class: 'btn btn-primary', method: 'PATCH' %>
</div>
If you try it, you should see something like that :
Very nice! Now, our app is missing one very important feature. A way to bring back documents from the graveyard! Who never deleted something by accident ? But before we do that, I want to show you how you can use your own version classes.
Custom Version Class
Why would we want to create custom classes to handle the versions of our models ? Well, with this approach, you can have a version model and table per model you want to version. Since you're using different tables for each of your model, you won't have one huge table that contains versions for this or that. Plus, you can add some specific field to a specific Version model by using metadata as we'll see soon.
Adding a custom version class is actually quite easy. First, we need to generate a migration :
rails g migration create_document_versions
You can paste this in it :
class CreateDocumentVersions < ActiveRecord::Migration
def change
create_table :document_versions do |t|
t.string :item_type, :null => false
t.integer :item_id, :null => false
t.string :event, :null => false
t.string :whodunnit
t.text :object
t.datetime :created_at
t.string :author_username
t.integer :word_count
end
add_index :document_versions, [:item_type, :item_id]
end
end
As you've probably noticed, we added 2 new columns : author_username and word_count. We'll use those to add some metadata to our versions later in this guide. Migrate and we can continue.
The corresponding model :
# app/models/document_version.rb
class DocumentVersion < PaperTrail::Version
self.table_name = :document_versions
default_scope { where.not(event: 'create') }
end
Note the default_scope we added. We don't really care about create events since those don't contain anything. Let's just exclude them.
The last thing to do is tell the Document model to use our custom version model instead of the default one :
# app/models/document.rb
...
has_paper_trail class_name: 'DocumentVersion'
...
Try the app and see if everything is still working. Of course, you won't have the versions that you had before because we changed the table!
Bring back Documents
To be able to bring back documents, we need to show all the deleted documents. We're going to add a route to access all the deleted documents. Here is the whole route file. We are also adding a route to undelete.
Rails.application.routes.draw do
resources :documents do
collection do
get :deleted # <= this
end
resources :versions, only: [:destroy] do
member do
get :diff, to: 'versions#diff'
patch :rollback, to: 'versions#rollback'
end
end
end
resources :versions, only: [] do
member do
patch :bringback # <= and that
end
end
resources :sessions, only: [:new, :create] do
delete 'logout', on: :collection
end
root to: 'documents#index'
end
The actions in our controllers :
# app/controllers/documents_controller.rb
...
# Get all the versions where the event was destroy
def deleted
@documents = DocumentVersion.where(event: 'destroy')
end
...
and :
# app/controllers/versions_controller.rb
...
def bringback
version = DocumentVersion.find(params[:id])
@document = version.reify
@document.save
# Let's remove the version since the document is undeleted
version.delete
redirect_to root_path, notice: 'The document was successfully brought back!'
end
...
And a view to list the deleted documents :
# app/views/documents/deleted.html.erb
<h1>Bring back documents</h1>
<table class='table'>
<thead>
<tr>
<th>ID</th>
<th>Name</th>
<th>Description</th>
<th>Deleted by</th>
<th>At</th>
<th colspan="3"></th>
</tr>
</thead>
<tbody>
<% @documents.each do |document_version| %>
<%- document = document_version.reify %>
<tr>
<td><%= document.id %></td>
<td><%= document.name %></td>
<td><%= document.content %></td>
<td><%= find_version_author_name(document_version) %></td>
<td><%= document.created_at %></td>
<td><%= link_to 'Bringback', bringback_version_path(document_version), method: 'PATCH' %></td>
</tr>
<% end %>
</tbody>
</table>
<br>
<%= link_to 'Back', documents_path %>
And finally, a link to access this view!
# app/views/documents/index.html.erb
...
<%= link_to 'See Deleted Documents', deleted_documents_path %>
<br/>
<%= link_to 'New Document', new_document_path %>
Now try it! Delete a document and it will appear in the list of deleted. You should be able to easily bring it back too. The app is pretty much done, but I'd like to share with you 2 more features of PaperTrail.
MetaData
PaperTrail gives us a way to save additional information in each version. In our case, we're going to save the author name (even if we can get it with the whodunnit id) and the number of word in the content.
Remember when we created the migration for you custom DocumentVersion model ? We're going to use those!
# app/models/document.rb
...
has_paper_trail class_name: 'DocumentVersion',
meta: { author_username: :user_name, word_count: :count_word }
...
When PaperTrail generate a new version, it will call the defined methods (user_name) on document an save it in the specified field (author_username).
We need to add a method named count_word :
def count_word
content.split(' ').count
end
And since we added all those information, we should show it in our list of versions.
# app/views/documents/_versions.html.erb
...
<th>Index</th>
<th>Date</th>
<th>Author</th>
<th>Event</th>
<th>Word Count</th>
...
<td><%= version.id %></td>
<td><%= version.created_at %></td>
<td><%= version.author_username %></td>
<td><%= version.event.humanize %></td>
<td><%= version.word_count %></td>
And save a few versions to see the metadata!
Who needs 100 versions ?
The last trick I want to show you is a way to limit the number of versions you save. We probably don't need the 100 previous versions, 10 to 30 should be enough. You can define that in PaperTrail configuration :
# config/initializers/paper_trail.rb
PaperTrail.config.version_limit = 10
Et voila!
Want more ?
You can check more about PaperTrail on the official Readme. There is also a nice Railscast showing how to create an undo system.
Source Code
You can get the starting code here and the complete code there.
Warmup
That's it ! That was a long article and I hope you enjoyed it and learned a few things ;)