Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 187 lines (131 sloc) 6.499 kb
2fc360f @aq1018 change readme
aq1018 authored
1 mongoid-history
2 ===============
3
30bdf2d @aq1018 fix header
aq1018 authored
4 [![Build Status](https://secure.travis-ci.org/aq1018/mongoid-history.png?branch=master)](http://travis-ci.org/aq1018/mongoid-history) [![Dependency Status](https://gemnasium.com/aq1018/mongoid-history.png?travis)](https://gemnasium.com/aq1018/mongoid-history)
2fc360f @aq1018 change readme
aq1018 authored
5
6
7 In frustration of Mongoid::Versioning, I created this plugin for tracking historical changes for any document, including embedded ones. It achieves this by storing all history tracks in a single collection that you define. (See Usage for more details) Embedded documents are referenced by storing an association path, which is an array of document_name and document_id fields starting from the top most parent document and down to the embedded document that should track history.
8
9 This plugin implements multi-user undo, which allows users to undo any history change in any order. Undoing a document also creates a new history track. This is great for auditing and preventing vandalism, but it is probably not suitable for use cases such as a wiki.
10
11 Install
12 -------
13
14 ```
15 gem install mongoid-history
16 ```
17
18 Rails 3
19 -------
20
21 In your Gemfile:
22
23 ```ruby
24 gem 'mongoid-history'
25 ```
26
27 Usage
28 -----
29
30 Here is a quick example on how to use this plugin. For more details, please look at spec/integration/integration_spec.rb. It offers more detailed examples on how to use `Mongoid::History`.
31
32 **Create a History Tracker**
33
34 Create a new class to track histories. All histories are stored in this tracker. The name of the class can be anything you like. The only requirement is that it includes `Mongoid::History::Tracker`
35
36 ```ruby
37 # app/models/history_tracker.rb
38 class HistoryTracker
39 include Mongoid::History::Tracker
40 end
41 ```
42
43 **Set Tracker Class Name**
44
45
46 You should manually set the tracker class name to make sure your tracker can be found and loaded properly. You can skip this step if you manually require your tracker before using any trackables. If you don't know what I'm talking about, then you should just follow the example below.
47
48 Here is an example of setting the tracker class name using a rails initializer
49
50 ```ruby
51 # config/initializers/mongoid-history.rb
52 # initializer for mongoid-history
53 # assuming HistoryTracker is your tracker class
54 Mongoid::History.tracker_class_name = :history_tracker
55 ```
56
57 **Set `#current_user` method name**
58
59 You can set name of method which returns currently logged in user if you don't want to set modifier explicitly on every update.
60
61 Here is an example of setting the current_user_method using a rails initializer
62
63 ```ruby
64 # config/initializers/mongoid-history.rb
65 # initializer for mongoid-history
66 # assuming you're using devise/authlogic
67 Mongoid::History.current_user_method = :current_user
68 ```
69
70 When current_user_method is set mongoid-history call this method on each update and set it as modifier
71
72 ```
73 # Assume that current_user return #<User _id: 1>
74 post = Post.first
75 post.update_attributes(:title => 'New title')
76
77 post.history_tracks.last.modifier #=> #<User _id: 1>
78 ```
79
80 ***Create Trackable classes and objects***
81
82 ```ruby
83 class Post
84 include Mongoid::Document
85 include Mongoid::Timestamps
86
87 # History tracking all Post Documents
88 # Note: Tracking will not work until #track_history is invoked
89 include Mongoid::History::Trackable
90
91 field :title
92 field :body
93 field :rating
94 embeds_many :comments
95
96 # Telling Mongoid::History how you want to track
97 track_history :on => [:title, :body], # I want to track title and body fields only. Default is :all
98 :modifier_field => :modifier, # Adds "referened_in :modifier" to track who made the change. Default is :modifier
99 :version_field => :version, # Adds "field :version, :type => Integer" to track current version. Default is :version
100 :track_create => false, # Do you want to track document creation? Default is false
101 :track_update => true, # Do you want to track document updates? Default is true
102 :track_destroy => false, # Do you want to track document destruction? Default is false
103 end
104
105 class Comment
106 include Mongoid::Document
107 include Mongoid::Timestamps
108
109 # Declare that we want to track comments
110 include Mongoid::History::Trackable
111
112 field :title
113 field :body
114 embedded_in :post, :inverse_of => :comments
115
116 # Track title and body for all comments, scope it to post (the parent)
117 # Also track creation and destruction
118 track_history :on => [:title, :body], :scope => :post, :track_create => true, :track_destroy => true
119 end
120
121 # The modifier can be specified as well
122 class User
123 include Mongoid::Document
124 include Mongoid::Timestamps
125
126 field :name
127 end
128
129 user = User.create(:name => "Aaron")
130 post = Post.create(:title => "Test", :body => "Post", :modifier => user)
131 comment = post.comments.create(:title => "test", :body => "comment", :modifier => user)
132 comment.history_tracks.count # should be 1
133
134 comment.update_attributes(:title => "Test 2")
135 comment.history_tracks.count # should be 2
136
137 track = comment.history_tracks.last
138
139 track.undo! user # comment title should be "Test"
140
141 track.redo! user # comment title should be "Test 2"
142
143 # undo last change
144 comment.undo! user
145
146 # undo versions 1 - 4
147 comment.undo! user, :from => 4, :to => 1
148
149 # undo last 3 versions
150 comment.undo! user, :last => 3
151
152 # redo versions 1 - 4
153 comment.redo! user, :from => 1, :to => 4
154
155 # redo last 3 versions
156 comment.redo! user, :last => 3
157
158 # delete post
159 post.destroy
160
161 # undelete post
162 post.undo! user
163
164 # disable tracking for comments within a block
165 Comment.disable_tracking do
166 comment.update_attributes(:title => "Test 3")
167 end
168 ```
169
170 Contributing to mongoid-history
171 -------------------------------
172
173 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
174 * Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
175 * Fork the project
176 * Start a feature/bugfix branch
177 * Commit and push until you are happy with your contribution
178 * Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
179 * 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.
180
181 Copyright
182 ---------
183
184 Copyright (c) 2011 Aaron Qian. See LICENSE.txt for
185 further details.
186
Something went wrong with that request. Please try again.