public_activity
provides easy activity tracking for your ActiveRecord, Mongoid 3 and MongoMapper models
in Rails 6.1+. Simply put: it records what has been changed or created and gives you the ability to present those
recorded activities to users - similarly to how GitHub does it.
- Ruby/Rails version support
- Table of contents
- Example
- Screencast
- Setup
- Testing
- Documentation
- Common examples
- Help
- License
Version ~> 3.0`` supports Ruby 3.0+ and Rails 6.1+. For older Ruby versions (≤2.7) and Rails 5.0+ you can use version
~> 2.0` until you can upgrade to
newer versions of Ruby + Rails.
Issues related to those unsupported versions of Ruby/Rails will be closed without resolution and PRs will not be accepted.
Here is a simple example showing what this gem is about:
The source code of the demo is hosted here: https://github.com/pokonski/activity_blog
Ryan Bates made a great screencast describing how to integrate Public Activity in your Rails Application.
You can install public_activity
as you would any other gem:
gem install public_activity
or in your Gemfile:
gem 'public_activity'
By default public_activity uses Active Record. If you want to use Mongoid or MongoMapper as your backend, create an initializer file in your Rails application with the corresponding code inside:
For Mongoid:
# config/initializers/public_activity.rb
PublicActivity::Config.set do
orm :mongoid
end
For MongoMapper:
# config/initializers/public_activity.rb
PublicActivity::Config.set do
orm :mongo_mapper
end
(ActiveRecord only) Create migration for activities and migrate the database (in your Rails project):
rails g public_activity:migration
rake db:migrate
Include PublicActivity::Model
and add tracked
to the model you want to keep track of:
For ActiveRecord:
class Article < ActiveRecord::Base
include PublicActivity::Model
tracked
end
For Mongoid:
class Article
include Mongoid::Document
include PublicActivity::Model
tracked
end
For MongoMapper:
class Article
include MongoMapper::Document
include PublicActivity::Model
tracked
end
And now, by default create/update/destroy activities are recorded in activities table. This is all you need to start recording activities for basic CRUD actions.
Optional: If you don't need #tracked
but still want the comfort of #create_activity
,
you can include only the lightweight Common
module instead of Model
.
You can trigger custom activities by setting all your required parameters and triggering create_activity
on the tracked model, like this:
@article.create_activity key: 'article.commented_on', owner: current_user
See this entry http://rubydoc.info/gems/public_activity/PublicActivity/Common:create_activity for more details.
To display them you simply query the PublicActivity::Activity
model:
# notifications_controller.rb
def index
@activities = PublicActivity::Activity.all
end
And in your views:
<%= render_activities(@activities) %>
Note: render_activity
is a helper for use in view templates. render_activity(activity)
can be written as activity.render(self)
and it will have the same meaning.
Note: render_activities
is an alias for render_activity
and does the same.
You can also pass options to both activity#render
and #render_activity
methods, which are passed deeper
to the internally used render_partial
method.
A useful example would be to render activities wrapped in layout, which shares common elements of an activity,
like a timestamp, owner's avatar etc:
<%= render_activities(@activities, layout: :activity) %>
The activity will be wrapped with the app/views/layouts/_activity.erb
layout, in the above example.
Important: please note that layouts for activities are also partials. Hence the _
prefix.
Sometimes, it's desirable to pass additional local variables to partials. It can be done this way:
<%= render_activity(@activity, locals: {friends: current_user.friends}) %>
Note: Before 1.4.0, one could pass variables directly to the options hash for #render_activity
and access it from activity parameters. This functionality is retained in 1.4.0 and later, but the :locals
method is preferred, since it prevents bugs from shadowing variables from activity parameters in the database.
public_activity
looks for views in app/views/public_activity
.
For example, if you have an activity with :key
set to "activity.user.changed_avatar"
, the gem will look for a partial in app/views/public_activity/user/_changed_avatar.(erb|haml|slim|something_else)
.
Hint: the "activity."
prefix in :key
is completely optional and kept for backwards compatibility, you can skip it in new projects.
If a view file does not exist, then p_a falls back to the old behaviour and tries to translate the activity :key
using I18n#translate
method (see the section below).
Translations are used by the #text
method, to which you can pass additional options in form of a hash. #render
method uses translations when view templates have not been provided. You can render pure i18n strings by passing {display: :i18n}
to #render_activity
or #render
.
Translations should be put in your locale .yml
files. To render pure strings from I18n Example structure:
activity:
article:
create: 'Article has been created'
update: 'Someone has edited the article'
destroy: 'Some user removed an article!'
This structure is valid for activities with keys "activity.article.create"
or "article.create"
. As mentioned before, "activity."
part of the key is optional.
For RSpec you can first disable public_activity
and add the test_helper
in rails_helper.rb
with:
#rails_helper.rb
require 'public_activity/testing'
PublicActivity.enabled = false
In your specs you can then blockwise decide whether to turn public_activity
on
or off.
# file_spec.rb
PublicActivity.with_tracking do
# your test code goes here
end
PublicActivity.without_tracking do
# your test code goes here
end
For more documentation go here
- [How to] Set the Activity's owner to current_user by default
- [How to] Disable tracking for a class or globally
- [How to] Create custom activities
- [How to] Use custom fields on Activity
If you need help with using public_activity please visit our discussion group and ask a question there:
https://groups.google.com/forum/?fromgroups#!forum/public-activity
Please do not ask general questions in the Github Issues.
Copyright (c) 2011-2013 Piotrek Okoński, released under the MIT license