![](\"https://files.liveeditorcms.com/files/resources/1561/drafts-screenshot.png\")
Draftsman is a Ruby gem that lets you create draft versions of your database records. If you’re developing a system in need of simple drafts or a publishing approval queue, then Draftsman just might be what you need.
\nI built Draftsman to handle the draft logic in Live Editor. Because draft logic gets complicated pretty quickly, I felt that this warranted its own gem with its own set of tests. Plus this was a great opportunity to share a piece of Live Editor with the open source community!
\nLive Editor uses the excellent PaperTrail gem for publication revision tracking, so I built the API behind Draftsman to work much like PaperTrail.
\nHave a read of the README to see more examples of how to work with the Draftsman gem.
\nTo get up and running with Draftsman, you generally have to do a few things:
\ndraftsman to your Gemfile.drafts table to your database with the rails g draftsman:install command (or copy the migration file into your application if you’re using Sinatra).draft_id, published_at, and trashed_at columns to the database tables you want to have drafts on.has_drafts to the models you want to have drafts on.More specific installation instructions are available at the GitHub project.
\nThe Draftsman API requires you to be explicit about when you want to save data as a draft. It provides these persistence methods on your models containing has_drafts:
draft_creationdraft_updatedraft_destroydraft_creation and draft_update work like ActiveRecord’s save and update methods: they validate data in the model, run callbacks, and return true or false if everything saved successfully.
By calling draft_creation, draft_update, and draft_destroy, you’re effectively storing a copy of the record with drafted changes in the drafts table.
You can access these drafts through a query directly on the Draftsman::Draft class or through an instance method called draft on your model objects.
| \n | # Accessing drafts through the `Draftsman::Draft` class | \n
| \n | @drafts = Draftsman::Draft.order(:created_at) | \n
| \n | \n | \n
| \n | # Accessing a draft through a model | \n
| \n | @post = Post.find(params[:id]) | \n
| \n | @draft = @post.draft if @post.draft? | \n
Once you have a draft record, you can call revert! on it to undo the draft or publish! to publish the changes to the main record.
Once you’re living in the brave new world of drafts, you’ll want to query your model data differently depending on where you are in the application.
\nHere is a quick listing of scopes that Draftsman adds to your model when you add has_drafts to it:
| \n | Widget.drafted # Limits to items that have drafts. Best used in an "admin" area in your application. | \n
| \n | Widget.published # Limits to items that have been published at some point in their lifecycles. Best used in a "public" area in your application. | \n
| \n | Widget.trashed # Limits to items that have been drafted for deletion (but not fully committed for deletion). Best used in an "admin" area in your application. | \n
| \n | Widget.live # Limits to items that have not been drafted for deletion. Best used in an "admin" area in your application. | \n
Typically, the live scope is used in the “admin” section of your application because it limits the query to records that have not been put in the trash (or draft_destroyed, to use Draftsman terminology).
When you want to show only published data (usually in the public or non-admin area of your application), you should use the published scope to query your data.
In the admin area of your application, you’ll most likely want to load your data in a mixed state:
\nThe way to accomplish this is through the reify method on each record’s draft. Take a look at these sample index and show actions for a posts admin area:
| \n | class Admin::PostsController < Admin::BaseController | \n
| \n | def index | \n
| \n | @posts = Post.live.includes(:draft).to_a | \n
| \n | @posts.map! { |post| post.draft? ? post.draft.reify : post } | \n
| \n | end | \n
| \n | \n |
| \n | def show | \n
| \n | @post = Post.live.find(params[:id]) | \n
| \n | @post = @post.draft.reify if @post.draft? | \n
| \n | end | \n
| \n | end | \n
Here, reify returns a Post object with the drafted data loaded in. If any Post record is not a draft, then nothing is done.
Live Editor, using Draftsman under the hood, allows admins to browse to a Drafts section that lists all drafts polymorphically, no matter if the drafts are of content, files, or design elements.
\n
That way, you can review everything that’s in progress and publish or revert multiple drafts at once, no matter the type of content.
\nTry doing that in WordPress!
\nThere is more to this gem that I won’t cover in this introduction. Some features that I didn’t mention are as follows:
\npublish! and revert! methods handle any dependent drafts so you don’t end up with orphaned records.current_user by default if it exists, but you can have it call any method you like.draft association.For more detailed information, examples, bug reports, etc., visit the Draftsman GitHub repo. Give it a try!
","frontmatter":{"title":"Draftsman gem: Add a draft state to your Ruby on Rails and Sinatra relational models","date":"August 18, 2014","description":"Draftsman is my new Ruby gem that lets you create draft versions of your database records. If you're developing a system in need of simple drafts or a publishing approval queue, then Draftsman just might be what you need.\n"},"fields":{"slug":"/draftsman-gem-draft-state-ruby-on-rails-sinatra-relational-models/"}}},"pageContext":{"slug":"/draftsman-gem-draft-state-ruby-on-rails-sinatra-relational-models/","previous":{"fields":{"slug":"/effective-us-page-tips-best-practices-guidelines/"},"frontmatter":{"title":"Effective \"About us\" page tips, best practices, and guidelines"}},"next":{"fields":{"slug":"/simplistic-vs-simple-product-design/"},"frontmatter":{"title":"Simplistic vs. simple in product design"}}}},"staticQueryHashes":["3678401200","63159454"]}