notification-handler 1.0.0.beta6 → 1.0.0.beta7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f39ea79cb44c6242c64d15816329a2c505a5b2421686c4efe106ff286e027d15
-  data.tar.gz: 760d3aec4e2b75787db310fbf7cfd430213997d94f66403411b1ace527e0ddf1
+  metadata.gz: 9547328112aaa356ee69213fd899699b8b3637eacae843b554f797e40a42b01b
+  data.tar.gz: 81e7724af9478908387dffe2d4f73779302bbe739e3eb6bca1dd3f2474983954
 SHA512:
-  metadata.gz: bdd9699f6be18a889bc4c3a1b1c0418b608d14dba21fbf4ecddab4098c8e99bd630cc0ea7341564a492fc541f6a9dcb372ce45e7f8a0fc962c63b308652a36cc
-  data.tar.gz: 421ee72029f64b8f04eb1b3d747a2b59c969622c098a37edaa97c4c996695bc7ec575ca270159e66dbee9a0b2d5a192672c2e0f31013311cd84319da5f985f70
+  metadata.gz: 6de83feb349ba94456ad089694621944cd48533a11ba76b2c7d2d65b9c0a824b2df770a75ad42a505afac679a20b0e51f54e22ec1343040fdf236a7fbac1f65b
+  data.tar.gz: ced24de953f5b28e256a2ecfb558bdb9751a15388cbf0b8f666b193a79a1baa550fe496224fc1e129dcef1671ca6ab38090a2956cc3564e81348f9a439047490

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+### master
+
+* nothing yet
+
+### 1.0.0.beta6 - 2017-12-28
+
+* bugfixes
+    * fix lib loading problems
+
+### 1.0.0.beta5 - 2017-12-28
+
+* bugfixes
+    * fix generators
+    * fix lib loading problems
+    * fix syntax errors
+
+### 1.0.0.beta4 - 2017-12-27
+
+* features
+    * add caching functionality
+    * add `read` attribute to `Notification` instances
+    * add `notify` method to notification targets
+
+### 1.0.0.beta3 - 2017-12-25
+
+* features
+    * allow `Group` object definition in configuration
+
+### 1.0.0.beta2 - 2017-12-23
+
+* features
+    * add `NotificationHandler::Group` class for target grouping notifications
+    * add `metadata` hash to `Notification` objects
+* enhancements
+    * add custom `NotificationHandler::Notification` class
+    * drop Rails dependency
+
+### 1.0.0.beta1 - 2017-12-22
+
+* initial release

data/README.md

@@ -1,17 +1,23 @@
-# NotificationsRails
+# NotificationHandler
 
-[![Gem Version](https://badge.fury.io/rb/notifications-rails.svg)](https://badge.fury.io/rb/notifications-rails) <img src="https://travis-ci.org/jonhue/notifications-rails.svg?branch=master" />
+[![Gem Version](https://badge.fury.io/rb/notification-handler.svg)](https://badge.fury.io/rb/notification-handler) <img src="https://travis-ci.org/jonhue/notifications-rails.svg?branch=master" />
 
-The most powerful notification solution for Rails. NotificationsRails simplifies the handling, rendering, user-integration and cross-platform pushing of notifications through its simple API.
-
-It integrates with the [Native](https://github.com/NativeGap/native-rails) gem to allow you to create a cross platform Rails app.
+Create and modify your notifications through a simple API.
 
 ---
 
 ## Table of Contents
 
-* [Philosophy](#philosophy)
 * [Installation](#installation)
+* [Usage](#usage)
+    * [`Notification` API](#notification-api)
+    * [`notification_target`](#notification_target)
+    * [`notification_object`](#notification_object)
+    * [Groups](#groups)
+        * [Defining a group](#defining-a-group)
+        * [Using a group](#using-a-group)
+    * [Caching](#caching)
+* [Configuration](#configuration)
 * [To Do](#to-do)
 * [Contributing](#contributing)
     * [Contributors](#contributors)
@@ -20,49 +26,194 @@ It integrates with the [Native](https://github.com/NativeGap/native-rails) gem t
 
 ---
 
-## Philosophy
+## Installation
+
+NotificationHandler works with Rails 5 onwards. You can add it to your `Gemfile` with:
+
+```ruby
+gem 'notification-handler'
+```
 
-NotificationsRails has been built with modularity in mind. It currently consists of four components each of which bringing one essential functionality to the notification-integration in your Rails app.
+And then execute:
 
-**[NotificationHandler](notification-handler):** Create and modify your notifications through a simple API.
+    $ bundle
 
-**[NotificationRenderer](notification-renderer):** Render your notifications on multiple platforms by specifying notification types.
+Or install it yourself as:
 
-**[NotificationPusher](notification-pusher):** Push your notifications to various services. Including [Email](notification-pusher-actionmailer), [ActionCable](notification-pusher-actioncable), [OneSignal](notification-pusher-onesignal).
+    $ gem install notification-handler
 
-**[NotificationSettings](notification-settings):** Integrates with your authentication solution to craft a personalized user notification platform.
+If you always want to be up to date fetch the latest from GitHub in your `Gemfile`:
 
-You may just add the components you actually need, or instead use this gem to bundle everything for a complete notification solution.
+```ruby
+gem 'notification-handler', github: 'jonhue/notifications-rails'
+```
+
+Now run the generator:
+
+    $ rails g notification_handler:install
+
+To wrap things up, migrate the changes to your database:
+
+    $ rails db:migrate
 
 ---
 
-## Installation
+## Usage
+
+### `Notification` API
 
-NotificationsRails works with Rails 5 onwards. You can add it to your `Gemfile` with:
+You can use all the ActiveRecord methods you know and love on your `Notification` class. So creating a new notification is dead simple:
 
 ```ruby
-gem 'notifications-rails'
+notification = Notification.new
 ```
 
-And then execute:
+Every `Notification` object has a `target` record. This target record is the object, that this notification belongs to (or targets). Usually it's a user, but it can be a record of any class:
 
-    $ bundle
+```ruby
+notification.target = User.first
+```
 
-Or install it yourself as:
+To store information in your `Notification` record you can use the `metadata` attribute that gets serialized as a `Hash`:
 
-    $ gem install notifications-rails
+```ruby
+notification.metadata = {
+    title: 'My first notification',
+    content: "It looks great, doesn't it?"
+}
+```
 
-If you always want to be up to date fetch the latest from GitHub in your `Gemfile`:
+Another form of adding information is by associating an object to the notification. This can be a record of any class you like:
+
+```ruby
+notification.object = Recipe.first
+```
+
+The `read` attribute determines whether a notification has been seen or not:
 
 ```ruby
-gem 'notifications-rails', github: 'jonhue/notifications-rails'
+notification.read = true
+notification.read? # true
+notification.unread? # false
 ```
 
+You can use scopes to filter for read or unread notifications:
+
+```ruby
+# Return all read notifications
+Notification.read
+
+# Return all unread notifications
+Notification.unread
+
+# Number of unread notifications
+Notification.unread.count
+```
+
+### `notification_target`
+
+To use records of an ActiveRecord class as notification targets, add the following to your class:
+
+```ruby
+class User < ApplicationRecord
+    notification_target
+end
+```
+
+Now belonging notifications are easy to access:
+
+```ruby
+notifications = User.first.notifications
+```
+
+You can create a notification from a `target`:
+
+```ruby
+User.first.notify object: Recipe.first
+```
+
+...
+
+### `notification_object`
+
+When using records of an ActiveRecord class as notification objects, add this to your class:
+
+```ruby
+class Recipe < ApplicationRecord
+    notification_object
+end
+```
+
+Now associated notifications are easy to access:
+
+```ruby
+notifications = Recipe.first.belonging_notifications
+```
+
+...
+
+### Groups
+
+Groups are a powerful way to bulk-create notifications for multiple objects that don't necessarily have a common class.
+
+#### Defining a group
+
+You define groups in your `NotificationHandler` configuration:
+
+```ruby
+NotificationHandler.configure do |config|
+    config.define_group :subscribers, User.where(subscriber: true)
+end
+```
+
+When creating a notification for the group `:subscribers`, one notification will be added for every target that fulfills this scope: `User.where(subscriber: true)`. You can also target objects from different classes:
+
+```ruby
+NotificationHandler.configure do |config|
+    config.define_group :subscribers, User.where(subscriber: true) + Admin.all
+end
+```
+
+#### Using a group
+
+Bulk-creation of notifications for a certain group is fairly simple:
+
+```ruby
+notification = Notification.create object: Recipe.first, group: :subscribers
+```
+
+**Note:** You are not able to set the `target` attribute when a `group` has been specified.
+
+### Caching
+
+You can cache the amount of unread and read notifications for notification targets by settings the [`cache`](#configuration) configuration option to `true`.
+
+Then add the following columns to the database tables of ActiveRecord classes acting as notification targets:
+
+```ruby
+add_column :user, :read_notification_count, :integer
+add_column :user, :unread_notification_count, :integer
+```
+
+---
+
+## Configuration
+
+You can configure NotificationHandler by passing a block to `configure`. This can be done in `config/initializers/notification-handler.rb`:
+
+```ruby
+NotificationHandler.configure do |config|
+    config.cache = true
+end
+```
+
+**`cache`** Cache amount of unread and read notifications for notification targets. Takes a boolean. Defaults to `false`.
+
 ---
 
 ## To Do
 
-[Here](https://github.com/jonhue/notifications-rails/projects) is the full list of current projects.
+[Here](https://github.com/jonhue/notifications-rails/projects/2) is the full list of current projects.
 
 To propose your ideas, initiate the discussion by adding a [new issue](https://github.com/jonhue/notifications-rails/issues/new).
 
@@ -70,9 +221,9 @@ To propose your ideas, initiate the discussion by adding a [new issue](https://g
 
 ## Contributing
 
-We hope that you will consider contributing to NotificationsRails. Please read this short overview for some information about how to get started:
+We hope that you will consider contributing to NotificationHandler. Please read this short overview for some information about how to get started:
 
-[Learn more about contributing to this repository](CONTRIBUTING.md), [Code of Conduct](CODE_OF_CONDUCT.md)
+[Learn more about contributing to this repository](https://github.com/jonhue/notifications-rails/blob/master/CONTRIBUTING.md), [Code of Conduct](https://github.com/jonhue/notifications-rails/blob/master/CODE_OF_CONDUCT.md)
 
 ### Contributors
 
@@ -82,7 +233,7 @@ https://github.com/jonhue/notifications-rails/graphs/contributors
 
 ### Semantic Versioning
 
-NotificationsRails follows Semantic Versioning 2.0 as defined at http://semver.org.
+NotificationHandler follows Semantic Versioning 2.0 as defined at http://semver.org.
 
 ## License
 

data/lib/generators/notification_handler/install_generator.rb

@@ -0,0 +1,46 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module NotificationHandler
+
+    class InstallGenerator < Rails::Generators::Base
+
+        include Rails::Generators::Migration
+
+        source_root File.join File.dirname(__FILE__), '../templates/install'
+        desc 'Install NotificationHandler'
+
+        def self.next_migration_number dirname
+            if ActiveRecord::Base.timestamped_migrations
+                Time.now.utc.strftime '%Y%m%d%H%M%S'
+            else
+                "%.3d" % ( current_migration_number(dirname) + 1 )
+            end
+        end
+
+        def create_initializer
+            template 'initializer.rb', 'config/initializers/notification-handler.rb'
+        end
+
+        def create_notifications_migration_file
+            migration_template 'notifications_migration.rb.erb', 'db/migrate/notification_handler_migration.rb', migration_version: migration_version
+        end
+        def create_notification_model
+            template 'notification_model.rb', 'app/models/notification.rb'
+        end
+
+        def show_readme
+            readme 'README.md'
+        end
+
+        private
+
+        def migration_version
+            if Rails.version >= '5.0.0'
+                "[#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}]"
+            end
+        end
+
+    end
+
+end

data/lib/generators/templates/install/README.md

@@ -0,0 +1 @@
+Now run `rails db:migrate` to add NotificationHandler to your database.

data/lib/generators/templates/install/initializer.rb

@@ -0,0 +1,11 @@
+NotificationHandler.configure do |config|
+
+    # Cache amount of unread and read notifications for notification targets
+    # Learn more: https://github.com/jonhue/notifications-rails/tree/master/notification-handler#caching
+    # config.cache = false
+
+    # Groups are a powerful way to bulk-create notifications for multiple objects that don't necessarily have a common class.
+    # Learn more: https://github.com/jonhue/notifications-rails/tree/master/notification-handler#groups
+    # config.define_group :subscribers, User.where(subscriber: true)
+
+end

data/lib/generators/templates/install/notification_model.rb

@@ -0,0 +1,2 @@
+class Notification < NotificationHandler::Notification
+end

data/lib/generators/templates/install/notifications_migration.rb.erb

@@ -0,0 +1,16 @@
+class NotificationHandlerMigration < ActiveRecord::Migration<%= migration_version %>
+    def change
+        create_table :notifications do |t|
+
+            t.references :target, polymorphic: true, index: true
+            t.references :object, polymorphic: true, index: true
+
+            t.boolean :read, default: false, null: false, index: true
+
+            t.text :metadata
+
+            t.timestamps
+
+        end
+    end
+end

data/lib/notification_handler/configuration.rb

@@ -0,0 +1,26 @@
+module NotificationHandler
+
+    class << self
+        attr_accessor :configuration
+    end
+
+    def self.configure
+        self.configuration ||= Configuration.new
+        yield configuration
+    end
+
+    class Configuration
+
+        attr_accessor :cache
+
+        def initialize
+            @cache = false
+        end
+
+        def define_group name, target_scope
+            ::NotificationHandler::Group.new name: name.to_sym, target_scope: target_scope
+        end
+
+    end
+
+end

data/lib/notification_handler/engine.rb

@@ -0,0 +1,6 @@
+require 'rails/railtie'
+
+module NotificationHandler
+    class Engine < ::Rails::Engine
+    end
+end

data/lib/notification_handler/group.rb

@@ -0,0 +1,17 @@
+module NotificationHandler
+    class Group
+
+        attr_accessor :name
+        attr_accessor :target_scope
+
+        def initialize name, target_scope
+            @name = name
+            @target_scope = target_scope
+        end
+
+        def find_by_name name
+            ObjectSpace.each_object(NotificationHandler::Group).select { |group| group.name == name.to_sym }
+        end
+
+    end
+end

data/lib/notification_handler/notification_library.rb

@@ -0,0 +1,40 @@
+module NotificationHandler
+    module NotificationLibrary
+
+        attr_accessor :group
+
+        before_validation :create_for_group
+        after_commit :cache
+
+        def read?
+            self.read
+        end
+        def unread?
+            !self.read
+        end
+
+        private
+
+        def create_for_group
+            unless self.group.nil?
+                target_scope = NotificationHandler::Group.find_by_name(self.group).last.target_scope
+                target_scope&.each do |target|
+                    notification = self.dup
+                    notification.target = target
+                    notification.group = nil
+                    notification.save
+                end
+                return false
+            end
+        end
+
+        def cache
+            if self.read_changed?
+                self.target.read_notification_count = self.target.notifications.read.count
+                self.target.unread_notification_count = self.target.notifications.unread.count
+                self.target.save!
+            end
+        end
+
+    end
+end

data/lib/notification_handler/notification_scopes.rb

@@ -0,0 +1,8 @@
+module NotificationHandler
+    module NotificationScopes
+
+        scope :read, -> { where(read: true) }
+        scope :unread, -> { where(read: false) }
+
+    end
+end

data/lib/notification_handler/object.rb

@@ -0,0 +1,25 @@
+module NotificationHandler
+    module Object
+
+        def self.included base
+            base.extend ClassMethods
+        end
+
+        module ClassMethods
+            def notification_object
+                has_many :belonging_notifications, as: :object, class_name: 'Notification', dependent: :destroy
+                include NotificationHandler::Object::InstanceMethods
+                
+                extend NotificationSettings::Object if defined?(NotificationSettings)
+                extend NotificationSettings::Subscribable if defined?(NotificationSettings)
+            end
+        end
+
+        module InstanceMethods
+
+            # ...
+
+        end
+
+    end
+end

data/lib/notification_handler/railtie.rb

@@ -0,0 +1,15 @@
+require 'rails/railtie'
+require 'active_record'
+
+module NotificationHandler
+    class Railtie < Rails::Railtie
+
+        initializer 'notification-handler.active_record' do
+            ActiveSupport.on_load :active_record do
+                include NotificationHandler::Target
+                include NotificationHandler::Object
+            end
+        end
+
+    end
+end

data/lib/notification_handler/target.rb

@@ -0,0 +1,28 @@
+module NotificationHandler
+    module Target
+
+        def self.included base
+            base.extend ClassMethods
+        end
+
+        module ClassMethods
+            def notification_target
+                has_many :notifications, as: :target, dependent: :destroy
+                include NotificationHandler::Target::InstanceMethods
+
+                extend NotificationSettings::Target if defined?(NotificationSettings)
+                extend NotificationSettings::Subscriber if defined?(NotificationSettings)
+            end
+        end
+
+        module InstanceMethods
+
+            def notify options = {}
+                options[:target] = self
+                Notification.create options
+            end
+
+        end
+
+    end
+end

data/lib/notification_handler.rb

@@ -0,0 +1,16 @@
+module NotificationHandler
+
+    require 'notification_handler/configuration'
+
+    require 'notification_handler/engine'
+
+    autoload :Group, 'notification_handler/group'
+
+    autoload :Target, 'notification_handler/target'
+    autoload :Object, 'notification_handler/object'
+    autoload :NotificationLibrary, 'notification_handler/notification_library'
+    autoload :NotificationScopes, 'notification_handler/notification_scopes'
+
+    require 'notification_handler/railtie'
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: notification-handler
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta6
+  version: 1.0.0.beta7
 platform: ruby
 authors:
 - Jonas Hübotter
@@ -72,8 +72,23 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
+- lib/generators/notification_handler/install_generator.rb
+- lib/generators/templates/install/README.md
+- lib/generators/templates/install/initializer.rb
+- lib/generators/templates/install/notification_model.rb
+- lib/generators/templates/install/notifications_migration.rb.erb
+- lib/notification_handler.rb
+- lib/notification_handler/configuration.rb
+- lib/notification_handler/engine.rb
+- lib/notification_handler/group.rb
+- lib/notification_handler/notification_library.rb
+- lib/notification_handler/notification_scopes.rb
+- lib/notification_handler/object.rb
+- lib/notification_handler/railtie.rb
+- lib/notification_handler/target.rb
 homepage: https://github.com/jonhue/notifications-rails/tree/master/notification-handler
 licenses:
 - MIT
@@ -81,7 +96,7 @@ metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
-- lib/notification_handler.rb
+- lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="