Skip to content
Browse files

nicer, shorter README in markdown

  • Loading branch information...
1 parent dbfdd14 commit a9f2fdd0225431123c97d3e71489f47c6834accc @mislav committed Oct 15, 2009
Showing with 65 additions and 76 deletions.
  1. +65 −0 README.markdown
  2. +0 −76 README.textile
View
65 README.markdown
@@ -0,0 +1,65 @@
+Are you paranoid?
+=================
+
+Destroying records is a one-way ticket--you are permanently sending data
+down the drain. *Unless*, of course, you are using this plugin.
+
+Simply declare models paranoid:
+
+ class User < ActiveRecord::Base
+ is_paranoid
+ end
+
+You will need to add the "deleted_at" datetime column on each model table
+you declare paranoid. This is how the plugin tracks destroyed state.
+
+
+Destroying
+----------
+
+Calling `destroy` should work as you expect, only it doesn't actually delete the record:
+
+ User.count #=> 1
+
+ User.first.destroy
+
+ User.count #=> 0
+
+ # user is still there, only hidden:
+ User.count_with_destroyed #=> 1
+
+What `destroy` does is that it sets the "deleted\_at" column to the current time.
+Records that have a value for "deleted\_at" are considered deleted and are filtered
+out from all requests using `default_scope` ActiveRecord feature:
+
+ default_scope :conditions => {:deleted_at => nil}
+
+Restoring
+---------
+
+No sense in keeping the data if we can't restore it, right?
+
+ user = User.find_with_destroyed(:first)
+
+ user.restore
+
+ User.count #=> 1
+
+Restoring resets the "deleted_at" value back to `nil`.
+
+Extra methods
+-------------
+
+Extra class methods provided by this plugin are:
+
+1. `Model.count_with_destroyed(*args)`
+2. `Model.find_with_destroyed(*args)`
+2. `Model.find_only_destroyed(*args)`
+
+
+Pitfalls
+--------
+
+* `validates_uniqueness_of` does not ignore items marked with a "deleted_at" flag
+* various eager-loading and associations-related issues (see ["Killing is_paranoid"](http://blog.semanticart.com/killing_is_paranoid/))
+* `find/count_with_destroyed` uses `with_exclusive_scope` and thus doesn't play nicely with named scopes
View
76 README.textile
@@ -1,76 +0,0 @@
-h1. is_paranoid ( same as it ever was )
-
-h3. and you may ask yourself, well, how did I get here?
-
-Sometimes you want to delete something in ActiveRecord, but you realize you might need it later (for an undo feature, or just as a safety net, etc.). There are a plethora of plugins that accomplish this, the most famous of which is the venerable acts_as_paranoid which is great but not really actively developed any more. What's more, acts_as_paranoid was written for an older version of ActiveRecord and, with default_scope in 2.3, it is now possible to do the same thing with significantly less complexity. Thus, *is_paranoid*.
-
-h3. and you may ask yourself, how do I work this?
-
-You should read the specs, or the RDOC, or even the source itself (which is very readable), but for the lazy, here's the hand-holding:
-
-You need ActiveRecord 2.3 and you need to properly install this gem. Then you need a model with a deleted_at timestamp column on its database table. If that column is null, the item isn't deleted. If it has a timestamp, it should count as deleted.
-
-So let's assume we have a model Automobile that has a deleted_at column on the automobiles table.
-
-If you're working with Rails, in your environment.rb, add the following to your initializer block.
-
-<pre>
-Rails::Initializer.run do |config|
- # ...
- config.gem "jchupp-is_paranoid", :lib => 'is_paranoid', :version => ">= 0.0.1"
-end
-</pre>
-
-Then in your ActiveRecord model
-
-<pre>
-class Automobile < ActiveRecord::Base
- is_paranoid
-end
-</pre>
-
-Now our automobiles are now soft-deleteable.
-
-<pre>
- that_large_automobile = Automobile.create()
- Automobile.count # => 1
-
- that_large_automobile.destroy
- Automobile.count # => 0
- Automobile.count_with_destroyed # => 1
-
- # where is that large automobile?
- that_large_automobile = Automobile.find_with_destroyed(:all).first
- that_large_automobile.restore
- Automobile.count # => 1
-</pre>
-
-One thing to note, destroying is always undo-able, but deleting is not.
-
-<pre>
- Automobile.destroy_all
- Automobile.count # => 0
- Automobile.count_with_destroyed # => 1
-
- Automobile.delete_all
- Automobile.count_with_destroyed # => 0
- # And you may say to yourself, "My god! What have I done?"
-</pre>
-
-h3. Note:
-
- validates_uniqueness_of does not ignore items marked with a deleted_at flag. This is a behavior difference between is_paranoid and acts_as_paranoid. I'm going to treat this as a bug until I get a chance to make it an optional feature. Be aware of it.
-
-h3. and you may ask yourself, where does that highway go to?
-
-If you find any bugs, have any ideas of features you think are missing, or find things you're like to see work differently, feel free to send me a message or a pull request.
-
-Currently on the todo list:
-* deal with validates_uniqueness_of issue
-* add options for merging additional default_scope options (i.e. order, etc.)
-
-h3. Thanks
-
-Thanks to Rick Olson for acts_as_paranoid which is obviously an inspiration in concept and execution, Ryan Bates for mentioning the idea of using default_scope for this on Ryan Daigle's "post introducing default_scope":defscope, and the Talking Heads for being the Talking Heads.
-
-[defscope]http://ryandaigle.com/articles/2008/11/18/what-s-new-in-edge-rails-default-scoping

0 comments on commit a9f2fdd

Please sign in to comment.
Something went wrong with that request. Please try again.