dm-is-published

This plugin makes it very easy to add different states to your models, like ‘draft’ vs ‘live’. By default it also adds validations of the field value.

Originally inspired by the Rails plugin acts_as_publishable by fr.ivolo.us.

Installation

$  gem install dm-is-published

Or add the gem to your Gemfile, and then run bundle install.

gem 'dm-is-published', 'CURRENT_VERSION_NUMBER'

Dependencies

The plugin depends upon the following:

  • dm-mysql-adapter OR dm-sqlite3-adapter ( >= 1.2.0)

  • data_mapper ( >= 1.2.0)

  • activesupport (>= 3.2.7) - method => Object#blank?

Getting Started

First of all, for a better understanding of this gem, make sure you study the ‘dm-is-published/spec/dm-is-published_spec.rb’ file.

Require dm-is-published in your app.

require 'data_mapper'         # must be required first
require 'dm-is-published'

Lets say we have an Article class, and each Article can have a current state, ie: whether it’s Live, Draft or an Obituary awaiting the death of someone famous (real or rumored)

class Article
  include DataMapper::Resource
  property :id,     Serial
  property :title,   String
  ...<snip>

  is :published

end

Once you have your Article model we can create our Articles just as normal

Article.create(:title => 'Example 1')

The instance of Article.get(1) now has the following things for free:

  • a :publish_status attribute with the value 'live'. Default choices are [ :live, :draft, :hidden ].

  • :is_live?, :is_draft? or :is_hidden? methods that returns true/false based upon the state.

  • :save_as_live, :save_as_draft or :save_as_hidden converts the instance to the state and saves it.

  • :publishable? method that returns true for models where is :published has been declared, but false for those where it has not been declared.

The Article class also gets a bit of new functionality:

Article.all(:draft)  =>  finds all Articles with :publish_status = :draft

Article.all(:draft, :author => @author_joe )  =>  finds all Articles with :publish_status = :draft and author == Joe

Todo Need to write more documentation here..

Usage Scenarios

In a Blog/Publishing scenario you could use it like this:

class Article 
  ...<snip>...

  is :published :live, :draft, :hidden

end

Whereas in another scenario - like in a MenuItem model for a Restaurant - you could use it like this:

class MenuItem
  ...<snip>...

  is :published  :on, :off  # the item is either on the menu or not

end

RTFM

For a better understanding of this gem/plugin, make sure you study the ‘dm-is-select/spec/dm-is-select_spec.rb’ file.

Errors / Bugs

If something is not behaving intuitively, it is a bug, and should be reported. Report it here: github.com/kematzy/dm-is-published/issues

Contributing to dm-is-published

  • Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet.

  • Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it.

  • Fork the project.

  • Start a feature/bugfix branch.

  • Commit and push until you are happy with your contribution.

  • Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.

  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright © 2009 - 2013 Kematzy.

Loosely based on the ActsAsPublishable plugin by [fr.ivolo.us/posts/acts-as-publishable]

Licence

Released under the MIT license.