module DataMapper::Is::Published
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'
Getting Started¶ ↑
First of all, for a better understanding of this gem, make sure you study the ‘dm-is-published/spec/integration/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 whereis :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
-
add 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 ¶ ↑
As I said above, for a better understanding of this gem/plugin, make sure you study the ‘dm-is-published/spec/integration/published_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
Credits¶ ↑
Copyright © 2008 - 2013 [Kematzy at gmail]
Loosely based on the ActsAsPublishable plugin by [fr.ivolo.us/posts/acts-as-publishable]
Licence¶ ↑
Released under the MIT license.
Constants
- VERSION
Public Instance Methods
method that adds a basic published status attribute to your model
params ¶ ↑
-
states
- an array of ‘states’ as symbols or strings. ie: :live, :draft, :hidden
Examples¶ ↑
is :published :on, :off is :published %w(a b c d)
@api public
# File lib/is/published.rb, line 133 def is_published(*args) # set default args if none passed in args = [:live, :draft, :hidden] if args.blank? args = args.first if args.first.is_a?(Array) # the various publish states accepted. @publish_states = args.collect{ |state| state.to_s.downcase.to_sym } @publish_states_for_validation = args.collect{ |state| state.to_s.downcase } extend DataMapper::Is::Published::ClassMethods include DataMapper::Is::Published::InstanceMethods # do we have a :publish_status declared if properties.any?{ |p| p.name == :publish_status } # set default value to first value in declaration or the given value d = properties[:publish_status].default.blank? ? @publish_states.first.to_s : properties[:publish_status].default # set the length to 10 if missing or if shorter than 5, otherwise use the given value l = 5 if properties[:publish_status].length.blank? l = (properties[:publish_status].length <= 10 ? 10 : properties[:publish_status].length) property :publish_status, String, :length => l, :default => d.to_s else # no such property, so adding it with default values property :publish_status, String, :length => 10, :default => @publish_states.first.to_s end # create the state specific instance methods self.publish_states.each do |state| define_method("is_#{state}?") do self.publish_status == state.to_s end define_method("save_as_#{state}") do self.publish_status = state.to_s save end end # ensure we are always saving publish_status values as strings before :valid? do self.publish_status = self.publish_status.to_s if self.respond_to?(:publish_status) end validates_within :publish_status, :set => @publish_states_for_validation, :message => "The publish_status value can only be one of these values: [ #{@publish_states_for_validation.join(', ')} ]" end