trackable 0.2.0 → 0.3.0
Sign up to get free protection for your applications and to get access to all the features.
- data/README.textile +87 -1
- data/VERSION +1 -1
- data/lib/trackable/event.rb +1 -0
- data/test/models.rb +1 -1
- data/test/schema.rb +1 -0
- data/test/trackable_test.rb +6 -0
- metadata +3 -5
- data/README +0 -13
data/README.textile
CHANGED
@@ -1 +1,87 @@
|
|
1
|
-
|
1
|
+
trackable is an add-on to Rails that provides for user-readable, fully configurable messaging on change tracking in ActiveRecord models.
|
2
|
+
|
3
|
+
trackable is inspired by two plugins: "acts_as_eventable":http://github.com/netphase/acts_as_eventable from Netphase and "paper_trail":http://github.com/airblade/paper_trail from Air Blade Software. I wanted something that had the human-readability of acts_as_eventable, but with custom messaging that could be dictated by Ruby code and not database-bound. I also wanted the potential to track user involvement, like paper_trail does. So the trackable gem was born!
|
4
|
+
|
5
|
+
h2. Use Case
|
6
|
+
|
7
|
+
You want something that looks like this:
|
8
|
+
|
9
|
+
!http://img.skitch.com/20100224-t337bxe38pkr3e2fe92m7spipb.jpg!
|
10
|
+
|
11
|
+
You can choose what message to show when the user selects booleans. For string fields, you can pick between a sensible default, a custom message generator, or specific enumerated values. For references to other models, all you need is a <code>to_s</code> defined on them, and you'll get a similar choice to string values. You can choose what to include and what not to include, and can get up and running in no time at all.
|
12
|
+
|
13
|
+
h2. Installation
|
14
|
+
|
15
|
+
Add the following to your <code>config/environment.rb</code> file.
|
16
|
+
|
17
|
+
<pre><code> config.gem 'trackable'</code></pre>
|
18
|
+
|
19
|
+
You'll then need to install the gem using <code>rake gems:install</code> or your sudo equivalent.
|
20
|
+
|
21
|
+
After the gem is installed, create your migration with this command:
|
22
|
+
|
23
|
+
<pre><code>script/generate trackable_migration</code></pre>
|
24
|
+
|
25
|
+
And you're ready! When that command completes and you run your migrations with <code>rake db:migrate</code>, you'll have a new table named <code>events</code> that trackable will keep its event information in. Let's take a look at what we get.
|
26
|
+
|
27
|
+
h2. Integration
|
28
|
+
|
29
|
+
If you're the type to not read the instructions, and you're already getting antsy, just drop <code>trackable</code> into one of your models, and check out what you get in your <code>events</code> association. Simple as that!
|
30
|
+
|
31
|
+
For those that like a bit more detail, let's take a look at the following bit of code and see what we can get out of it.
|
32
|
+
|
33
|
+
<pre><code>
|
34
|
+
# create_table :foos, :force => true do |t|
|
35
|
+
# t.boolean :no_homers
|
36
|
+
# t.string :status
|
37
|
+
# t.string :custom_status
|
38
|
+
# t.string :do_not_track
|
39
|
+
# t.integer :bar_id
|
40
|
+
# t.integer :custom_bar_id
|
41
|
+
#
|
42
|
+
# t.timestamps
|
43
|
+
# end
|
44
|
+
|
45
|
+
class Foo < ActiveRecord::Base
|
46
|
+
trackable :events =>{
|
47
|
+
:no_homers => {true => "Homers have been barred.", false => "Homers have been allowed."},
|
48
|
+
:custom_status => {:message => Proc.new {|n| "The value of a custom string field changed to #{n}" }},
|
49
|
+
:custom_bar_id => {:message => Proc.new{|n| "Active Bar set to #{n}"}}
|
50
|
+
}, :exclude => :do_not_track
|
51
|
+
belongs_to :bar, :class_name => "Bar"
|
52
|
+
belongs_to :custom_bar, :class_name => "Bar"
|
53
|
+
end
|
54
|
+
</code></pre>
|
55
|
+
|
56
|
+
h3. Booleans
|
57
|
+
|
58
|
+
For booleans, you can indicate what messages that you'd like by setting up a hash with the true and false messages like this:
|
59
|
+
|
60
|
+
<code>{:your_boolean_field_name => {true => "True message", false => "False message"}}</code>
|
61
|
+
|
62
|
+
You can use the default message, but most of the time that won't be what you want.
|
63
|
+
|
64
|
+
h3. Strings (or integers)
|
65
|
+
|
66
|
+
You might not have to do anything. You'll have a message like "Humanized field name changed to new value" without intervention. If you do want something custom, you can do this:
|
67
|
+
|
68
|
+
<code>{:your_string_field => {:message => Proc.new {|n| "Field value set to #{n}" }}}</code>
|
69
|
+
|
70
|
+
The value of <code>n</code> will be the new string value that's been saved in your tracked object.
|
71
|
+
|
72
|
+
If you happen to have a string field with only a few values that are known ahead of time, you could use the same sort of signature as the hash in the Boolean example above to set a custom message for each value. This might be useful in state machines, for example. You could have something like this.
|
73
|
+
|
74
|
+
<pre><code>{:aasm_state_ => {"published" => "Post has been published.",
|
75
|
+
"submitted" => "Post was submitted for approval"}}</code></pre>
|
76
|
+
|
77
|
+
h3. Associations
|
78
|
+
|
79
|
+
As long as your association field ends with <code>_id</code>, trackable will call <code>to_s</code> on the new value, and then it'll be treated like the string example above.
|
80
|
+
|
81
|
+
h3. Excluding certain fields.
|
82
|
+
|
83
|
+
As in the far above example, you can pass an :exclude option with a single field name or an array of field names to ignore. These won't result events being added.
|
84
|
+
|
85
|
+
h2. Questions
|
86
|
+
|
87
|
+
I'm available at jim at jimvanfleet dot com, or you can send me a message right here on Github. You can also open issues here, I'll try to keep an eye on them.
|
data/VERSION
CHANGED
@@ -1 +1 @@
|
|
1
|
-
0.
|
1
|
+
0.3.0
|
data/lib/trackable/event.rb
CHANGED
@@ -3,6 +3,7 @@ class Event < ActiveRecord::Base
|
|
3
3
|
def self.attributes_from(model, key, old_val, new_val)
|
4
4
|
return if old_val.blank? && new_val.blank? #not something we need to track.
|
5
5
|
eventable_options = model.class.eventable_options
|
6
|
+
return if [eventable_options[:exclude]].flatten.include?(key.to_sym)
|
6
7
|
msg = if eventable_options[:events][key.to_sym] && eventable_options[:events][key.to_sym][new_val]
|
7
8
|
eventable_options[:events][key.to_sym][new_val]
|
8
9
|
elsif eventable_options[:events][key.to_sym] && eventable_options[:events][key.to_sym][:message]
|
data/test/models.rb
CHANGED
@@ -3,7 +3,7 @@ class Foo < ActiveRecord::Base
|
|
3
3
|
:no_homers => {true => "Homers have been barred.", false => "Homers have been allowed."},
|
4
4
|
:custom_status => {:message => Proc.new {|n| "The value of a custom string field changed to #{n}" }},
|
5
5
|
:custom_bar_id => {:message => Proc.new{|n| "Active Bar set to #{n}"}}
|
6
|
-
}
|
6
|
+
}, :exclude => :do_not_track
|
7
7
|
belongs_to :bar, :class_name => "Bar"
|
8
8
|
belongs_to :custom_bar, :class_name => "Bar"
|
9
9
|
end
|
data/test/schema.rb
CHANGED
data/test/trackable_test.rb
CHANGED
@@ -128,5 +128,11 @@ class TrackableTest < Test::Unit::TestCase
|
|
128
128
|
foo.custom_bar = bar; foo.save
|
129
129
|
assert_equal "Active Bar set to Baloney", foo.events.first.message
|
130
130
|
end
|
131
|
+
|
132
|
+
def test_untracked_changes
|
133
|
+
foo = Foo.create
|
134
|
+
foo.update_attribute(:do_not_track, "Untracked")
|
135
|
+
assert_equal 0, foo.events.size
|
136
|
+
end
|
131
137
|
|
132
138
|
end
|
metadata
CHANGED
@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
|
|
4
4
|
prerelease: false
|
5
5
|
segments:
|
6
6
|
- 0
|
7
|
-
-
|
7
|
+
- 3
|
8
8
|
- 0
|
9
|
-
version: 0.
|
9
|
+
version: 0.3.0
|
10
10
|
platform: ruby
|
11
11
|
authors:
|
12
12
|
- bigfleet
|
@@ -36,11 +36,10 @@ executables: []
|
|
36
36
|
extensions: []
|
37
37
|
|
38
38
|
extra_rdoc_files:
|
39
|
-
- README
|
40
39
|
- README.textile
|
41
40
|
files:
|
42
41
|
- MIT-LICENSE
|
43
|
-
- README
|
42
|
+
- README.textile
|
44
43
|
- Rakefile
|
45
44
|
- VERSION
|
46
45
|
- generators/trackable_migration/templates/migration.rb
|
@@ -60,7 +59,6 @@ files:
|
|
60
59
|
- test/trackable_controller_test.rb
|
61
60
|
- test/trackable_test.rb
|
62
61
|
- uninstall.rb
|
63
|
-
- README.textile
|
64
62
|
has_rdoc: true
|
65
63
|
homepage: http://github.com/bigfleet/trackable
|
66
64
|
licenses: []
|