dm-actionstamps¶ ↑

A DataMapper plugin that works similar to the dm-timestamps in that it ‘automagically’ adds/updates the created_?, updated_? fields of your models.

This is a completely rewritten version of the “rlivesey’s” "dm-userstamp"[http://github.com/rlivsey/dm-userstamp] gem.

It was rewritten and given a new new when I made more dynamic in nature than dm-userstamp.

$  (sudo)? gem install dm-actionstamps

NB! Depends upon the whole DataMapper suite being installed, and has ONLY been tested with DM 0.10.2.

Require dm-actionstamps in your app.

require 'dm-core'         # must be required first
require 'dm-actionstamps'

Lets say we have a User class and we want to track the user actions in our other models. Just do as follows:

class User
  include DataMapper::Resource
  property :id, Serial
  property :name, String

  provides_actionstamps

end

By declaring :provides_actionstamps in your User model, you get the following functionality free.

User.current_user = new user...

User.current_user  => retrieves the current_user

You can then use it as follows:

@user = User.create(:id => 99, :name => "Joe")

User.current_user = @user

# retrieve the current user info.
User.current_user.id   =>  returns 99

OK, so far not so exciting, but lets say we have an Article class, and we want to track the User that created the Article and the last User that updated the Article. It’s easy too:

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

  actionstamps :by, User

end

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

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

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

• a :created_by attribute with the value of User.current_user.id if set. Default value is nil.

• a :updated_by attribute with the value of User.current_user.id if set. Default value is nil.

So given this usage scenario:

@user = User.create(:id => 99, :name => "Joe")
User.current_user = @user

@article = Article.create(:title => 'Example 2')

The Article instance should have the following:

@article.created_by   => 99
@article.updated_by   => 99

dm-actionstamps plugin/gem was created because I needed to track the actions of Client, Staff and other ‘User’ models, and the "dm-userstamp"[http://github.com/rlivsey/dm-userstamp] gem was hardcoded to the User model.

To support more flexible declarations, I have separated out the functionality into two parts:

• Provider Model

• Receiver Model

The Provider Model provides the actionstamps, and can be declared like this:

class Client
  include DataMapper::Resource
  property :id, Serial
  property :name, String

  provides_actionstamps

end

In difference to the examples above, the current_? methods takes the name of the Model that was given the provider status (via the :provides_actionstamps method):

Client.current_client =  Client.create(:id => 88, :name => "Happy")

Client.current_client   => returns the Client

The Receiver Model receives the actionstamps and can be declared like this:

class Bill
  include DataMapper::Resource
  property :id,     Serial
  property :amount, Integer
  ...<snip>

  actionstamps :by, Client

end

So when we create a new instance of Bill, we get the values from the Client.current_client method:

@bill = Bill.create(:amount => "100")

@bill.created_by   =>  88

• Contemplate if there is ever a scenario where you need to track two different models updating the same record? (Seller vs Buyers ?)

• Think of some clever way to automagically set “User.current_user = @user” when you load or create a new User in your enclosing application.

• Any other improvements that you can think of?

For a better understanding of this gem/plugin, make sure you study the ‘dm-actionstamps/spec/integration/actionstamps_spec.rb’ file.

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

• Fork the project.

• Make your feature addition or bug fix.

• Add tests for it. This is important so I don’t break it in a future version unintentionally.

• Commit, do not mess with rakefile, version, or history.

  • (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

• Send me a pull request. Bonus points for topic branches.

Copyright © 2010 kematzy. Released under the MIT license.