ActivityNotification

Build Status Coverage Status Dependency Inline docs Gem Version Gem Downloads MIT License

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: * https://activity-notification-example.herokuapp.com/

Login as the following test users to experience user activity notifications:

Email Password Admin?
[email protected] changeit Yes
[email protected] changeit  
[email protected] changeit  
[email protected] 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

![plugin-notifications-image](https://raw.githubusercontent.com/simukappu/activity_notification/images/activity_notification_plugin_focus_with_subscription.png)

activity_notification deeply uses PublicActivity as reference in presentation layer.

Subscription management of notifications

![subscription-management-image](https://raw.githubusercontent.com/simukappu/activity_notification/images/activity_notification_subscription_management_with_optional_targets.png)

Amazon SNS as optional notification target

![optional-target-amazon-sns-email-image](https://raw.githubusercontent.com/simukappu/activity_notification/images/activity_notification_optional_target_amazon_sns.png)

Slack as optional notification target

![optional-target-slack-image](https://raw.githubusercontent.com/simukappu/activity_notification/images/activity_notification_optional_target_slack.png)

Public REST API reference as OpenAPI Specification

REST API reference as OpenAPI Specification is published in SwaggerHub here: * https://app.swaggerhub.com/apis-docs/simukappu/activity-notification/

You can see sample single page application using Vue.js as a part of example Rails application here: * https://activity-notification-example.herokuapp.com/spa/

This sample application works with activity_notification REST API backend.

Table of Contents

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:

console $ gem install activity_notification or in your Gemfile:

ruby gem 'activity_notification'

After you install activity_notification and add it to your Gemfile, you need to run the generator:

console $ 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:

console $ 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.

ruby 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.

```ruby 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):

ruby 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:

ruby 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:

ruby @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.

console $ 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: console $ 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: * https://activity-notification-example.herokuapp.com/

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.