ActivityNotification
activity_notification provides integrated user activity notifications for Ruby on Rails. You can easily use it to configure multiple notification targets and make activity notifications with notifiable models, like adding comments, responding etc.
activity_notification supports Rails 5.0+ with ActiveRecord, Mongoid and Dynamoid ORM. It is tested for MySQL, PostgreSQL, SQLite3 with ActiveRecord, MongoDB with Mongoid and Amazon DynamoDB with Dynamoid. If you are using Rails 4.2, use v2.1.4 or older version of activity_notification.
About
activity_notification provides following functions:
- Notification API for your Rails application (creating and managing notifications, query for notifications)
- Notification models (stored with ActiveRecord, Mongoid or Dynamoid ORM)
- Notification controllers (managing open/unopen of notifications, providing link to notifiable activity page)
- Notification views (presentation of notifications)
- Automatic tracked notifications (generating notifications along with the lifecycle of notifiable models)
- Grouping notifications (grouping like "Kevin and 7 other users posted comments to this article")
- Email notification
- Batch email notification (event driven or periodical email notification, daily or weekly etc)
- Push notification with Action Cable
- Subscription management (subscribing and unsubscribing for each target and notification type)
- REST API backend and OpenAPI Specification
- Integration with Devise authentication
- Activity notifications stream integrated into cloud computing using Amazon DynamoDB Streams
- Optional notification targets (Configurable optional notification targets like Amazon SNS, Slack, SMS and so on)
Online Demo
You can see an actual application using this gem here:
Login as the following test users to experience user activity notifications:
Password | Admin? | |
---|---|---|
ichiro@example.com | changeit | Yes |
stephen@example.com | changeit | |
klay@example.com | changeit | |
kevin@example.com | changeit |
The deployed demo application is included in this gem's source code as a test application here: /spec/rails_app
Notification index and plugin notifications
activity_notification deeply uses PublicActivity as reference in presentation layer.
Subscription management of notifications
Amazon SNS as optional notification target
Slack as optional notification target
Public REST API reference as OpenAPI Specification
REST API reference as OpenAPI Specification is published in SwaggerHub here:
You can see sample single page application using Vue.js as a part of example Rails application here:
This sample application works with activity_notification REST API backend.
Table of Contents
- About
- Getting Started
- Setup
- Gem installation
- Database setup
- Using ActiveRecord ORM
- Using Mongoid ORM
- Using Dynamoid ORM
- Configuring models
- Configuring target models
- Configuring notifiable models
- Configuring views
- Configuring routes
- Routes with scope
- Routes as REST API backend
- Creating notifications
- Notification API
- Asynchronous notification API with ActiveJob
- Automatic tracked notifications
- Displaying notifications
- Preparing target notifications
- Rendering notifications
- Notification views
- i18n for notifications
- Customizing controllers (optional)
- Functions
- Email notification
- Mailer setup
- Sender configuration
- Email templates
- Email subject
- Other header fields
- i18n for email
- Batch email notification
- Batch mailer setup
- Batch sender configuration
- Batch email templates
- Batch email subject
- i18n for batch email
- Grouping notifications
- Subscription management
- Configuring subscriptions
- Managing subscriptions
- Customizing subscriptions
- REST API backend
- Configuring REST API backend
- API reference as OpenAPI Specification
- Integration with Devise
- Configuring integration with Devise authentication
- Using different model as target
- Configuring simple default routes
- REST API backend with Devise Token Auth
- Push notification with Action Cable
- Enabling broadcasting notifications to channels
- Subscribing notifications from channels
- Subscribing notifications with Devise authentication
- Subscribing notifications API with Devise Token Auth
- Subscription management of Action Cable channels
- Optional notification targets
- Configuring optional targets
- Customizing message format
- Action Cable channels as optional target
- Amazon SNS as optional target
- Slack as optional target
- Developing custom optional targets
- Subscription management of optional targets
- Testing
- Documentation
- Common Examples
- Contributing
- License
Getting Started
This getting started shows easy setup description of activity_notification. See Setup for more details.
Gem installation
You can install activity_notification as you would any other gem:
$ gem install activity_notification
or in your Gemfile:
gem 'activity_notification'
After you install activity_notification and add it to your Gemfile, you need to run the generator:
$ bin/rails generate activity_notification:install
The generator will install an initializer which describes all configuration options of activity_notification.
Database setup
When you use activity_notification with ActiveRecord ORM as default configuration, create migration for notifications and migrate the database in your Rails project:
$ bin/rails generate activity_notification:migration
$ bin/rake db:migrate
See Database setup for other ORMs.
Configuring models
Configure your target model (e.g. app/models/user.rb). Add acts_as_target configuration to your target model to get notifications.
class User < ActiveRecord::Base
acts_as_target
end
Then, configure your notifiable model (e.g. app/models/comment.rb). Add acts_as_notifiable configuration to your notifiable model representing activity to notify for each of your target model. You have to define notification targets for all notifications from this notifiable model by :targets option. Other configurations are optional. :notifiable_path option is a path to move when the notification is opened by the target user.
class Article < ActiveRecord::Base
belongs_to :user
has_many :comments, dependent: :destroy
has_many :commented_users, through: :comments, source: :user
end
class Comment < ActiveRecord::Base
belongs_to :article
belongs_to :user
acts_as_notifiable :users,
targets: ->(comment, key) {
([comment.article.user] + comment.article.reload.commented_users.to_a - [comment.user]).uniq
},
notifiable_path: :article_notifiable_path
def article_notifiable_path
article_path(article)
end
end
See Configuring models for more details.
Configuring views
activity_notification provides view templates to customize your notification views. See Configuring views for more details.
Configuring routes
activity_notification also provides routing helper for notifications. Add notify_to method to config/routes.rb for the target (e.g. :users):
Rails.application.routes.draw do
notify_to :users
end
See Configuring routes for more details.
You can also configure activity_notification routes as REST API backend with api_mode option like this:
Rails.application.routes.draw do
scope :api do
scope :"v2" do
notify_to :users, api_mode: true
end
end
end
See Routes as REST API backend and REST API backend for more details.
Creating notifications
You can trigger notifications by setting all your required parameters and triggering notify on the notifiable model, like this:
@comment.notify :users, key: "comment.reply"
The first argument is the plural symbol name of your target model, which is configured in notifiable model by acts_as_notifiable. The new instances of ActivityNotification::Notification model will be generated for the specified targets.
See Creating notifications for more details.
Displaying notifications
activity_notification also provides notification views. You can prepare target notifications, render them in your controller, and show them provided or custom notification views.
See Displaying notifications for more details.
Run example Rails application
Test module includes example Rails application in spec/rails_app. Pull git repository and you can run the example application as common Rails application.
$ git pull https://github.com/simukappu/activity_notification.git
$ cd activity_notification
$ bundle install —path vendor/bundle
$ cd spec/rails_app
$ bin/rake db:migrate
$ bin/rake db:seed
$ bin/rails server
Then, you can access http://localhost:3000 for the example application.
Setup
See Setup.
Functions
See Functions.
Testing
See Testing.
Documentation
See API Reference for more details.
RubyDoc.info does not support parsing methods in included and class_methods of ActiveSupport::Concern currently. To read complete documents, please generate YARD documents on your local environment:
$ git pull https://github.com/simukappu/activity_notification.git
$ cd activity_notification
$ bundle install —path vendor/bundle
$ bundle exec yard doc
$ bundle exec yard server
Then you can see the documents at http://localhost:8808/docs/index.
Common Examples
See example Rails application in /spec/rails_app.
You can also try this example Rails application as Online Demo here:
You can login as test users to experience user activity notifications. For more details, see Online Demo.
Contributing
We encourage you to contribute to activity_notification! Please check out the Contributing to activity_notification guide for guidelines about how to proceed.
Everyone interacting in activity_notification codebases, issue trackers, and pull requests is expected to follow the activity_notification Code of Conduct.
We appreciate any of your contribution!
License
activity_notification project rocks and uses MIT License.