notification-renderer 1.0.0.beta6 → 1.0.0.beta7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1d9ee72295fa4ef67073e39179419f4e29146d7955928d9a577e08b5a8c0e41
-  data.tar.gz: a8ab724ed8b15b547e2d54ba6291ccc9d49fa3c62efc86588688c391b15c5c5e
+  metadata.gz: b85c93e55a50084e3e1d1f31af5d942a21455285303ef5aae231c9c7deae3a52
+  data.tar.gz: 80e6f088d3631eb327715a5318d46bf62e23d6ed728b5bb6b779e27a5af1c481
 SHA512:
-  metadata.gz: 5b588ad303c2fd11d7c6ed436c176bdae38a14bd72b428ca6e1dc0654fe93e9c962d658a71f7166c4fedc768a5e466d11b62535eab4eb2de8b7bc2af34e9ad79
-  data.tar.gz: 44b03932d0eaec4d98815d6d230376f8acd3ea20f19b9f8d29b6b63e4177e081b9a094474976508512fd9268b6ba62a0e6578598372b94c72d39890cae3e1eef
+  metadata.gz: f87e98fba149abd4b3f7b18c1e67ee29d0f4d2c18b9f094c88f905b73f3acaad708d85108aa245ef33ad003ef7b91ecb539fedeeaf807f53e844a794e1c09478
+  data.tar.gz: de08d08a118aef28227ef0cbd01cdea5244b01ce52bdcea4e98098d59769b599e2931c409924f56a83ba7852477a0b48fab43ccd40894d9d0253eb14ed952088

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# 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 helpers
+    * add `default_renderer` and `auto_read` configuration options
+    * add grouping functionality
+* enhancements
+    * allow defining renderers for `type` generator
+
+### 1.0.0.beta3 - 2017-12-25
+
+* features
+    * introduce `type` generator
+
+### 1.0.0.beta2 - 2017-12-23
+
+* initial release

data/README.md

@@ -1,17 +1,24 @@
-# NotificationsRails
+# NotificationRenderer
 
-[![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-renderer.svg)](https://badge.fury.io/rb/notification-renderer) <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.
+Render your notifications on multiple platforms by specifying notification types.
 
 ---
 
 ## Table of Contents
 
-* [Philosophy](#philosophy)
 * [Installation](#installation)
+* [Usage](#usage)
+    * [Types](#types)
+        * [Generating a new type](#generating-a-new-type)
+        * [Using a type](#using-a-type)
+    * [Renderers](#renderers)
+    * [View helpers](#view-helpers)
+        * [`render_notification`](#render_notification)
+        * [`render_notifications`](#render_notifications)
+    * [Grouping](#grouping)
+* [Configuration](#configuration)
 * [To Do](#to-do)
 * [Contributing](#contributing)
     * [Contributors](#contributors)
@@ -20,49 +27,217 @@ It integrates with the [Native](https://github.com/NativeGap/native-rails) gem t
 
 ---
 
-## Philosophy
+## Installation
+
+NotificationRenderer works with Rails 5 onwards. You can add it to your `Gemfile` with:
+
+```ruby
+gem 'notification-renderer'
+```
 
-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-renderer
 
-**[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-renderer', github: 'jonhue/notifications-rails'
+```
+
+Now run the generator:
+
+    $ rails g notification_renderer:install
+
+To wrap things up, migrate the changes to your database:
+
+    $ rails db:migrate
 
 ---
 
-## Installation
+## Usage
+
+### Types
+
+NotificationRenderer uses templates to render your notifications.
+
+The `type` of a notification determines which template gets utilized for rendering. Each notification type has multiple templates each of which responsible for rendering a notification in another scenario. The default template for a given type is `index`.
+
+#### Generating a new type
+
+This gem comes with a generator to make adding new types a whole lot easier. Run in your terminal:
+
+    $ rails g notification_renderer:type -t notification
 
-NotificationsRails works with Rails 5 onwards. You can add it to your `Gemfile` with:
+This will create the following structure in your application:
+
+* `views`
+    * `notifications`
+        * `notification`
+            * `_index.html.erb`
+
+You can also customize the generated templates (renderers):
+
+    $ rails g notification_renderer:type -t notification -r index feed
+
+This command will also create a custom renderer called `feed` for the notification type `notification`:
+
+* `views`
+    * `notifications`
+        * `notification`
+            * `_feed.html.erb`
+            * `_index.html.erb`
+
+#### Using a type
+
+You are able to specify the `type` of a `Notification` record:
 
 ```ruby
-gem 'notifications-rails'
+notification = Notification.create target: User.first, object: Recipe.first, type: 'notification'
 ```
 
-And then execute:
+**Note:** The `type` attribute of any new `Notification` record will default to the [`default_type` configuration](#configuration).
 
-    $ bundle
+You can also scope records by their type:
 
-Or install it yourself as:
+```ruby
+# Return records with `'notification'` as type
+Notification.notification_type
 
-    $ gem install notifications-rails
+# Return records with `'follow'` as type
+Notification.follow_type
+```
 
-If you always want to be up to date fetch the latest from GitHub in your `Gemfile`:
+### Renderers
+
+In your renderers you can access the `Notification` record through the `notification` variable. This is how a renderer could look like:
+
+```erb
+<%= notification.target.name %> commented on <%= notification.object.article.title %>.
+```
+
+### View helpers
+
+NotificationRenderer introduces some view helpers to assist you in embedding notifications.
+
+#### `render_notification`
+
+`render_notification` renders a single `Notification` record:
+
+```erb
+<%= render_notification Notification.first %>
+```
+
+Rendering a notification will set its `read` attribute to `true`. This behavior can be [configured](#configuration).
+
+You can also specify a renderer. It defaults to `'index'`.
+
+```erb
+<%= render_notification Notification.first, 'feed' %>
+```
+
+#### `render_notifications`
+
+`render_notifications` takes an ActiveRecord array of `Notification` records and renders each of them in order:
+
+```erb
+<%= render_notifications Notification.all %>
+```
+
+You can also specify a renderer. It defaults to `'index'`.
+
+```erb
+<%= render_notifications Notification.all, 'feed' %>
+```
+
+It wraps the rendered notifications in a `div`:
+
+```html
+<div class="notification-renderer notifications">
+    <!-- ... -->
+</div>
+```
+
+### Grouping
+
+You can group any ActiveRecord array of `Notification` records by an attribute value:
 
 ```ruby
-gem 'notifications-rails', github: 'jonhue/notifications-rails'
+Notification.grouping('object.article')
+Notification.grouping('metadata[:title]')
+```
+
+When rendering notifications you often want to group them by the object they belong to. This is how to group notifications by the associated object:
+
+```erb
+<%= render_notifications_grouped Notification.all, 'object', 'feed' %>
 ```
 
+You can also group notifications by nested attributes:
+
+```erb
+<%= render_notifications_grouped Notification.all, 'object.article' %>
+<%= render_notifications_grouped Notification.all, 'metadata[:title]' %>
+```
+
+It is also possible to group notifications for just one object:
+
+```erb
+<%= render_notifications_grouped Notification.where(object_id: 1, object_type: 'Comment'), 'object' %>
+```
+
+This will render the last notification for every group and pass the attributes value grouped by to your renderer:
+
+```erb
+<!-- View -->
+
+<%= render_notifications_grouped Notification.all, 'object.article' %>
+
+
+<!-- Renderer -->
+
+<% if notification_grouped? %>
+    <%= notification.target.name %> and <%= (notification_count - 1).to_s %> others commented on <%= attribute.title %>.
+<% else %>
+    <%= notification.target.name %> commented on <%= notification.object.article.title %>.
+<% end %>
+```
+
+Grouping makes the following two methods available in your renderer:
+
+**`attribute`** The value of the attribute used for grouping.
+
+**`notification_count`** The notification count for the group of the current notification.
+
+You may check whether a template is being used for grouping by using the `notification_grouped?` helper method.
+
+---
+
+## Configuration
+
+You can configure NotificationRenderer by passing a block to `configure`. This can be done in `config/initializers/notification-renderer.rb`:
+
+```ruby
+NotificationRenderer.configure do |config|
+    config.default_type = 'notification'
+end
+```
+
+**`default_type`** Choose your default notification type. Takes a string. Defaults to `'notification'`.
+
+**`default_renderer`** Choose your default renderer. Takes a string. Defaults to `'index'`.
+
+**`auto_read`** Automatically mark rendered notifications as read. Takes a boolean. Defaults to `true`.
+
 ---
 
 ## 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/7) 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 +245,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 NotificationRenderer. 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 +257,7 @@ https://github.com/jonhue/notifications-rails/graphs/contributors
 
 ### Semantic Versioning
 
-NotificationsRails follows Semantic Versioning 2.0 as defined at http://semver.org.
+NotificationRenderer follows Semantic Versioning 2.0 as defined at http://semver.org.
 
 ## License
 

data/lib/generators/notification_renderer/install_generator.rb

@@ -0,0 +1,47 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module NotificationRenderer
+
+    class InstallGenerator < Rails::Generators::Base
+
+        include Rails::Generators::Migration
+
+        source_root File.join File.dirname(__FILE__), '../templates/install'
+        desc 'Install NotificationRenderer'
+
+        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-renderer.rb'
+        end
+
+        def create_notifications_migration_file
+            migration_template 'notifications_migration.rb.erb', 'db/migrate/notification_renderer_migration.rb', migration_version: migration_version
+        end
+
+        def create_templates
+            system 'rails g notification_renderer:type -t notification'
+        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/notification_renderer/type_generator.rb

@@ -0,0 +1,21 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+
+module NotificationRenderer
+
+    class TypeGenerator < Rails::Generators::Base
+
+        source_root File.join File.dirname(__FILE__), '../templates/type'
+        desc 'Create a new notification type'
+        class_option :type, desc: 'Specify the notification type', type: :string, default: NotificationRenderer.configuration.default_type, aliases: '-t'
+        class_option :renderers, desc: 'Specify the renderer templates', type: :string, default: NotificationRenderer.configuration.default_renderer, aliases: '-r'
+
+        def create_templates
+            options[:renderers].split(' ')&.each do |template|
+                template '_template.html', "app/views/notifications/#{options[:type]}/_#{template}.html.erb"
+            end
+        end
+
+    end
+
+end

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

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

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

@@ -0,0 +1,12 @@
+NotificationRenderer.configure do |config|
+
+    # Choose your default notification type. Takes a string.
+    # config.default_type = 'notification'
+
+    # Choose your default renderer. Takes a string.
+    # config.default_renderer = 'index'
+
+    # Automatically mark rendered notifications as read. Takes a boolean.
+    # config.auto_read = true
+
+end

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

@@ -0,0 +1,5 @@
+class NotificationRendererMigration < ActiveRecord::Migration<%= migration_version %>
+    def change
+        add_column :notifications, :type, :string, index: true
+    end
+end

data/lib/generators/templates/type/_template.html

@@ -0,0 +1,7 @@
+<!--
+In your renderers you can access the `Notification` record through the `notification` variable. This is how a renderer could look like:
+
+<%#= notification.target.name %> commented on <%#= notification.object.article.title %>
+
+Learn more: https://github.com/jonhue/notifications-rails/tree/master/notification-renderer#renderers
+-->

data/lib/notification_renderer/configuration.rb

@@ -0,0 +1,26 @@
+module NotificationRenderer
+
+    class << self
+        attr_accessor :configuration
+    end
+
+    def self.configure
+        self.configuration ||= Configuration.new
+        yield configuration
+    end
+
+    class Configuration
+
+        attr_accessor :default_type
+        attr_accessor :default_renderer
+        attr_accessor :auto_read
+
+        def initialize
+            @default_type = 'notification'
+            @default_renderer = 'index'
+            @auto_read = true
+        end
+
+    end
+
+end

data/lib/notification_renderer/engine.rb

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

data/lib/notification_renderer/notification_library.rb

@@ -0,0 +1,13 @@
+module NotificationRenderer
+    module NotificationLibrary
+
+        def self.grouping group_by
+            group_by{ |notification| notification.send(group_by) }
+        end
+
+        def type
+            self[:type] || NotificationRenderer.configuration.default_type
+        end
+
+    end
+end

data/lib/notification_renderer/notification_scopes.rb

@@ -0,0 +1,17 @@
+module NotificationRenderer
+    module NotificationScopes
+        
+        def method_missing m, *args
+            if m.to_s[/(.+)_type/]
+                where type: $1.singularize.classify
+            else
+                super
+            end
+        end
+
+        def respond_to? m, include_private = false
+            super || m.to_s[/(.+)_type/]
+        end
+        
+    end
+end

data/lib/notification_renderer.rb

@@ -0,0 +1,10 @@
+module NotificationRenderer
+
+    require 'notification_renderer/configuration'
+
+    require 'notification_renderer/engine'
+
+    autoload :NotificationLibrary, 'notification_renderer/notification_library'
+    autoload :NotificationScopes, 'notification_renderer/notification_scopes'
+
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: notification-renderer
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta6
+  version: 1.0.0.beta7
 platform: ruby
 authors:
 - Jonas Hübotter
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.0.0.beta6
+        version: 1.0.0.beta7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.0.0.beta6
+        version: 1.0.0.beta7
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -87,8 +87,20 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
+- lib/generators/notification_renderer/install_generator.rb
+- lib/generators/notification_renderer/type_generator.rb
+- lib/generators/templates/install/README.md
+- lib/generators/templates/install/initializer.rb
+- lib/generators/templates/install/notifications_migration.rb.erb
+- lib/generators/templates/type/_template.html
+- lib/notification_renderer.rb
+- lib/notification_renderer/configuration.rb
+- lib/notification_renderer/engine.rb
+- lib/notification_renderer/notification_library.rb
+- lib/notification_renderer/notification_scopes.rb
 homepage: https://github.com/jonhue/notifications-rails/tree/master/notification-renderer
 licenses:
 - MIT
@@ -96,7 +108,7 @@ metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
-- lib/notification_renderer.rb
+- lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="