towncrier 1.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YTlhZGUxNzU0NDBiYjkxYTMzYjA5ZDAwNjdlMmFiMDU5YmFlMTYwYw==
+  data.tar.gz: !binary |-
+    NmUzY2E2MDJlOTFmOTRkOGU1ZTVlN2JjYjJkMGNiYWQ3MzZjMTJiMg==
+SHA512:
+  metadata.gz: !binary |-
+    ZGUwNDU0MmQ0MWI5Y2Q4NTE1OWFjOTViMTZmMDU5MWI1YzU3NGNmZDlhNjVi
+    NzEyZmM1ZDU5MWU2MDkzN2MzY2ZlYTdhNDQ2M2M2ZjBhMjkwNDc2NDQxNzlk
+    YmJhNDJmMGM5YzY4YzQ4MWRjMDA3M2VhMDdhOTk0MzAwMjg2ZjI=
+  data.tar.gz: !binary |-
+    NzQ2NzljOWViMTk1YTUzZmJkOWRlOTk0YWU4MWI2OTRlNjJjNmRhZjU2YzQw
+    NDBkMTk0OGNhOWNmNTU2ZTA5MmQ2ZjlkMmUzZWZlMzQwNjU1NGE0MWUwY2M1
+    ZjFiNGM3ZTEzMWYyMTM5Y2JlNzRhZGVmYjlmMGU0ZjU5NTFiNTY=

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 YOURNAME
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,281 @@
+[![Code Climate](https://codeclimate.com/github/davidlesches/towncrier.png)](https://codeclimate.com/github/davidlesches/towncrier)
+
+# Towncrier
+
+Consider Facebook. When a friend posts an update a growl notifications pops up on your screen. When someone send you a message your "messages" icon becomes highlighted. A friend uploads a new profile photo and that triggers your notifications counter being incremented.
+
+Towncrier provides a handy DSL for replicating that kind of UX experience.
+
+Towncrier is a Ruby on Rails gem that allows you to speedily create Javascript notifications for your app. It watches your models, and as records are created or updated it pushes a Javascript data payload to the users you specify. In your assets/javascripts files you can intercept these payloads and react to them, using the data within them to tweak the page in any way you desire.
+
+## Cheat Sheet
+
+If you've used Towncrier before, here is a refresher. If you haven't, please read the more detailed instructions below.
+
+Step 1: In the app/criers directory, add a new crier, using the same name as the model you are observing.
+
+```ruby
+class AnswerCrier < Towncrier::Base
+
+  on :create do
+    target answer.question.author
+    payload answer
+  end
+
+end
+```
+
+Step 2: In the assets/javascripts directory, add a listener for the cry and use the payload as you wish.
+
+```javascript
+towncrier.hearAnswer = function(action, payload) {
+  console.log(payload);
+}
+```
+
+## Opinion
+
+Like many gems, Towncrier is opinionated software. Towncrier believes that Javascript notifications are UX-sugar only and are not a central part of any app. As a result, Towncrier intentionally has a DSL that forces you to define the notifications outside of your ActiveRecord models, so that your ActiveRecord models do not become cluttered with notification code.
+
+Similarly, when deployed to production, Towncrier will swallow any errors or glitches caused by these notifications so that a syntax error within a notification doesn't trip up your application or trigger a database transaction rollback.
+
+In short, the idea is to provide a great DSL for these Javascript notifications while keeping them firmly out of the way of the important code.
+
+## App Setup
+
+Towncrier relies on Ryan Bates' excellent [Private Pub gem](https://github.com/ryanb/private_pub) to handle the Javascript pub/sub system under the hood. Towncrier also requires a background process queue. You can use [Sidekiq](https://github.com/mperham/sidekiq) or [Resque](https://github.com/resque/resque), though Sidekiq is recommended.
+
+**Step 1:** Install Private Pub and Sidekiq (or Resque). Both Private Pub and Sidekiq (or Resque) are somewhat involved to set up. Please see their homepages respectively and ensure they are set up and operating correctly before proceeding with installing Towncrier. (By default, Sidekiq/Resque is used in production mode only. See [Configuration](#configuration) for more.)
+
+**Step 2:** Add Towncrier to your gemfile.
+
+```
+gem 'towncrier'
+```
+
+**Step 3:** Run the generator.
+
+```
+rails generate towncrier
+rake db:migrate
+```
+
+**Step 4:** Add the JavaScript file to your application.js file manifest.
+
+```
+//= require towncrier
+```
+
+Remember to start up the Private Pub and Sidekiq (or Resque) processes as explained in their respective documentation.
+
+## Setting Up the Targets
+
+You need to define which model in your app represents the users ("targets") who will be receiving the notifications. In 95% of apps, this will be a User model.
+
+```ruby
+class User < ActiveRecord::Base
+  acts_as_towncrier_targets
+end
+```
+
+Next, add a string column named "towncrier_token" to that model.
+
+```
+rails generate migration add_towncrier_token_to_users towncrier_token
+rake db:migrate
+```
+
+From this point on, each user's towncrier_token will be populated on create. If you already have users in your app, simply re-save them to populate their tokens.
+
+```
+User.find_each(&:save)
+```
+
+Finally, in your application **layout**, add a Javascript listener *before the closing /body tag*. This listens for the notifications coming in for the target.
+
+```
+<%= subscribe_to(current_user.towncrier_channel) if current_user %>
+```
+
+## Usage
+
+Now it's time to go notification crazy :)
+
+For the purposes of this demo, we'll use a fictional StackOverflow app, where users post questions and answers.
+
+Let's say that every time a question is answered a notification should be pushed to the author of the original question. Create a new file called 'answer_crier.rb' in the 'app/criers' directory.
+
+```ruby
+class AnswerCrier < Towncrier::Base
+
+  on :create do
+    target answer.question.author
+    payload answer # => auto-converted to answer.to_json
+  end
+
+end
+```
+
+Notice the pattern. Naming conventions are everything. Because we are creating notifications when users submit answers, we create a crier class named AnswerCrier. This class inherits from Towncrier::Base, and because it is named AnswerCrier, Towncrier will watch for Answer resources being created or updated and will send out the appropriate notifications.
+
+Notifications can be sent on creates, updates, or both, and you can send multiple notifications each time an answer is submitted.
+
+```ruby
+class AnswerCrier < Towncrier::Base
+
+  on :create do
+    target answer.question.author
+    payload :foo => :bar
+  end
+
+  on :update do
+    target answer.question.author
+    payload :abc => :xyz
+  end
+
+  on :create, :update do
+    target answer.author.followers
+    payload :foo => :bar
+  end
+
+end
+```
+
+For every notification you must define two things, the target and the payload. The target (see section [Setting Up the Targets above](#setting-up-the-targets)) can be one user, or multiple.
+
+```ruby
+class AnswerCrier < Towncrier::Base
+
+  # one target
+  on :create do
+    target answer.question.author
+    payload :foo => :bar
+  end
+
+  # lots and lots of targets
+  on :create do
+    target (answer.question.author + answer.followers + answer.author.followers)
+    payload :foo => :bar
+  end
+
+end
+```
+
+The payload can be anything that `.to_json` can be called on.
+
+```ruby
+class AnswerCrier < Towncrier::Base
+
+  # a hash payload
+  on :create do
+    target answer.question.author
+    payload :foo => :bar
+  end
+
+  # a resource payload
+  on :create do
+    target answer.question.author
+    payload answer # => will be converted to answer.to_json
+  end
+
+  # a complex hash payload
+  on :create do
+    target answer.question.author
+    payload({
+      :answer => answer,
+      :answer_count => answer.author.answers.count,
+      :complex_stuff => {
+        :foo => :bar,
+        :bar => :foo
+      }
+    })
+  end
+
+end
+```
+
+Notice that in all the examples above, we were able to call 'answer' within the target (eg answer.author) and within the payload. Towncrier does some magic behind the scenes to enable this. Because this crier is the AnswerCrier, Towncrier sets up an 'answer' method that returns the newly created/updated answer resource, allowing you to call 'answer' within the target and payload declarations.
+
+Now all this is for sending out the notifications. On the Javascript side, you listen for these notifications by following the same naming convention.
+
+```javascript
+towncrier.hearAnswer = function(action, payload) {
+  // action will be a string, either 'create' or 'update'
+  // payload will be the payload in JSON format
+  // for example:
+  console.log("A new answer was just " + action + "d.")
+  console.log(payload);
+}
+```
+
+## Advanced Usage
+
+#### Custom Naming
+
+For each notification, you can use the `as` option to give the notification a more specific name. This is imperative when you have multiple notifications for a single resource.
+
+```ruby
+class AnswerCrier < Towncrier::Base
+
+  on :create, :update, as: :answer_for_question_author do
+    target answer.question.author
+    payload :foo => :bar
+  end
+
+  on :create, :update, as: :answer_for_followers do
+    target answer.author.followers
+    payload :foo => :bar
+  end
+
+end
+```
+
+```javascript
+towncrier.hearAnswerForQuestionAuthor = function(action, payload) {
+  // do something
+}
+
+towncrier.hearAnswerForFollowers = function(action, payload) {
+  // do something
+}
+```
+
+#### Persistence
+
+By default, every time a notification is sent a copy of it is stored in the Towncry ActiveRecord table. This allows you to reference those notifications later. An obvious use case for this is to populate a Past Notification Feed. If you do not want to save copies to the database, set the `record` option to false.
+
+```ruby
+class AnswerCrier < Towncrier::Base
+
+  on :create, :update, record: false do
+    target answer.question.author
+    payload :foo => :bar
+  end
+
+end
+```
+
+## Configuration
+
+A configuration file located at 'config/towncrier.yml' can be edited to tweak the settings.
+
+- **enabled:** whether or not Towncrier runs at all
+- **raise_errors:** whether to throw or swallow errors that occur when Towncrier is queueing a notification to the background process
+- **background_worker:** the type of background process to use. Valid values are `:sidekiq` and `:resque`. This can also be set to `false` to run everything in the main process. In development mode, `false` is the default, as not using a background process allows you to rely on Rails autoloading to pick up changes you are making in your codebase as you make them. In production mode however, leaving this setting as `false` is a catastrophically terrible idea.
+
+## TODO
+
+Add test suite.
+
+## License and Copyright
+
+Copyright (C) 2014 David Lesches
+[@davidlesches](http://twitter.com/davidlesches)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+
+

data/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Towncrier'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/app/assets/javascripts/towncrier.js

@@ -0,0 +1,12 @@
+(function() {
+  window.towncrier = {};
+
+  towncrier.hear = function(name, action, payload) {
+    var json;
+    json = $.parseJSON(payload);
+    if (("hear" + name) in towncrier) {
+      return towncrier["hear" + name](action, json);
+    }
+  };
+
+}).call(this);

data/lib/generators/templates/create_towncries_table.rb

@@ -0,0 +1,15 @@
+class CreateTowncriesTable < ActiveRecord::Migration
+  def change
+    create_table :towncries do |t|
+      t.string :name
+      t.integer :target_id
+      t.string :target_type
+      t.integer :crier_id
+      t.string :crier_type
+      t.string :action
+      t.string :payload
+
+      t.timestamps
+    end
+  end
+end

data/lib/generators/templates/towncrier.yml

@@ -0,0 +1,15 @@
+development:
+  enabled: true
+  raise_errors: true
+  background_worker: false
+
+test:
+  enabled: false
+  raise_errors: false
+  background_worker: false
+
+production:
+  enabled: true
+  raise_errors: false
+  background_worker: :sidekiq
+

data/lib/generators/templates/towncry.rb

@@ -0,0 +1,10 @@
+class Towncry < ActiveRecord::Base
+
+  # Associations
+  belongs_to :target, polymorphic: true
+  belongs_to :crier, polymorphic: true
+
+  # Serializers
+  serialize :payload, JSON
+
+end

data/lib/generators/towncrier_generator.rb

@@ -0,0 +1,19 @@
+class TowncrierGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+
+  def self.next_migration_number(dirname)
+    next_migration_number = current_migration_number(dirname) + 1
+    ActiveRecord::Migration.next_migration_number(next_migration_number)
+  end
+
+  desc "This generator sets up the Towncrier gem"
+  source_root File.expand_path("../templates", __FILE__)
+
+  def copy_files
+    copy_file "towncrier.yml", "config/towncrier.yml"
+    copy_file "towncry.rb", "app/models/towncry.rb"
+    empty_directory "app/criers"
+    migration_template "create_towncries_table.rb", "db/migrate/create_towncries_table.rb"
+  end
+
+end

data/lib/towncrier/active_record_extensions.rb

@@ -0,0 +1,19 @@
+class ActiveRecord::Base
+
+  after_create :broadcast_create_towncry
+  after_update :broadcase_update_towncry
+
+  def broadcast_create_towncry
+    broadcast_towncry(:create)
+  end
+
+  def broadcase_update_towncry
+    broadcast_towncry(:update)
+  end
+
+  def broadcast_towncry action
+    info = { :class => self.class.name, :id => self.id, :action => action }
+    ActiveSupport::Notifications.instrument('towncry', info)
+  end
+
+end

data/lib/towncrier/base.rb

@@ -0,0 +1,45 @@
+module Towncrier
+  class Base
+
+    CRIERS = []
+    RESERVED_NAMES = %w( Towncry TownCry )
+
+    def self.inherited klass
+      model_name = klass.name.gsub('Crier', '')
+      if RESERVED_NAMES.include?(model_name)
+        warn "#{klass} is a reserved name and cannot be used to define a Crier."
+      else
+        CRIERS << model_name
+        model_name.constantize.class_eval 'has_many :towncries, as: :crier, dependent: :destroy'
+      end
+    end
+
+    def self.emitters
+      @emitters
+    end
+
+    def self.on *args, &block
+      options = args.extract_options!
+      @emitters ||= []
+      @emitters << { on: args, options: options, block: block }
+    end
+
+    def self.create_cries(id, action)
+      emitters.each do |emitter|
+        next unless emitter[:on].include?(action.to_sym)
+        object = model_class.constantize.find(id)
+        cry = Towncrier::Cry.new(action: action, name: model_class, options: emitter[:options], _object: object)
+        cry.define_singleton_method(model_class.underscore) do
+          object
+        end
+        cry.instance_eval(&emitter[:block])
+        cry.cry
+      end
+    end
+
+    def self.model_class
+      self.name.gsub('Crier', '')
+    end
+
+  end
+end

data/lib/towncrier/config.rb

@@ -0,0 +1,44 @@
+module Towncrier
+  class Config < ::Rails::Engine
+
+    class_attribute :enabled, :raise_errors, :background_worker
+    self.enabled = true
+    self.raise_errors = false
+    self.background_worker = :sidekiq
+
+    def self.load_config
+      YAML.load_file(config_file_path)[Rails.env].each do |key, value|
+        if valid_config_values[ key.to_sym ] && valid_config_values[ key.to_sym ].include?(value)
+          self.send("#{key}=", value)
+        else
+          warn "Towncrier WARNING: The key/value specified in towncrier.yml for '#{key}' is an invalid option and is being ignored."
+        end
+      end
+    end
+
+    def self.config_file_path
+      File.join(Rails.root, '/config/towncrier.yml')
+    end
+
+    def self.config_file_exists?
+      File.exist?(config_file_path) &&
+      YAML.load_file(config_file_path) &&
+      !YAML.load_file(config_file_path)[Rails.env].nil?
+    end
+
+    def self.valid_config_values
+      {
+        :enabled           => [ true, false ],
+        :raise_errors      => [ true, false ],
+        :background_worker => [ false, :sidekiq, :resque ]
+      }
+    end
+
+    if config_file_exists?
+      load_config
+    else
+      warn 'Towncrier WARNING: towncrier.yml config file could not be found, or is missing values. Please see wiki to generate config file.'
+    end
+
+  end
+end

data/lib/towncrier/cry.rb

@@ -0,0 +1,65 @@
+module Towncrier
+  class Cry
+
+    attr_accessor :action, :name, :options, :_object
+
+    def initialize args
+      args.each do |key, value|
+        send("#{key}=", value)
+      end
+    end
+
+    def target target
+      @target = Array(target).flatten.compact.uniq
+    end
+
+    def payload payload
+      @payload = payload
+    end
+
+    def record?
+      !options[:record].nil? ? options[:record] : true
+    end
+
+    def official_name
+      (options[:as] || name).to_s.classify
+    end
+
+    def validate
+      if @target.nil?
+        raise NotImplementedError, "You forgot to define 'target' in your #{name} crier."
+      end
+
+      if @payload.nil?
+        raise NotImplementedError, "You forgot to define 'payload' in the #{name} crier."
+      end
+    end
+
+    def cry
+      validate
+      @target.each do |t|
+        push_notification(t)
+        save_notification(t)
+      end
+    end
+
+    def push_notification target
+      PrivatePub.publish_to(target.towncrier_channel, "towncrier.hear('#{official_name}', '#{action}', '#{@payload.to_json}')")
+    end
+
+    def save_notification target
+      Towncry.create!(
+        :name    => official_name,
+        :target  => target,
+        :crier   => _object,
+        :action  => action,
+        :payload => @payload
+      ) if record?
+    end
+
+    def crier_class
+      "#{name}_crier".classify.constantize
+    end
+
+  end
+end

data/lib/towncrier/eagerloader.rb

@@ -0,0 +1,17 @@
+module Towncrier
+  class Eagerloader
+
+    def self.load_criers
+      if Towncrier::Base.descendants.empty? && criers_directory_exists?
+        Dir[Rails.root.join("app/criers/*.rb")].each do |file|
+          require_dependency file
+        end
+      end
+    end
+
+    def self.criers_directory_exists?
+      File.directory?(Rails.root.join("app/criers"))
+    end
+
+  end
+end

data/lib/towncrier/engine.rb

@@ -0,0 +1,21 @@
+module Towncrier
+  class Engine < Rails::Engine
+
+    initializer "Include Towncrier gem only after Rails boot" do |app|
+      require 'towncrier/config'
+      require 'towncrier/base'
+      require 'towncrier/observer'
+      require 'towncrier/targets'
+      require 'towncrier/cry'
+      require 'towncrier/eagerloader'
+      require 'towncrier/active_record_extensions'
+      require 'towncrier/workers/resque'
+      require 'towncrier/workers/sidekiq'
+
+      ActionDispatch::Callbacks.to_prepare do
+        Towncrier::Eagerloader.load_criers
+      end
+    end
+
+  end
+end

data/lib/towncrier/observer.rb

@@ -0,0 +1,42 @@
+module Towncrier
+  class Observer
+
+    attr_reader :payload
+
+    ActiveSupport::Notifications.subscribe('towncry') do |_, _, _, _, payload|
+      new(payload)
+    end
+
+    def initialize payload
+      @payload = payload
+      setup_cries if create_cries?
+    end
+
+    def create_cries?
+      Towncrier::Config.enabled && Towncrier::Base::CRIERS.include?(payload[:class])
+    end
+
+    def setup_cries
+      send("setup_#{async_type}_cries")
+    rescue
+      raise if Towncrier::Config.raise_errors
+    end
+
+    def async_type
+      Towncrier::Config.background_worker
+    end
+
+    def setup_sidekiq_cries
+      Towncrier::Workers::Sidekiq.perform_async(payload[:class], payload[:id], payload[:action])
+    end
+
+    def setup_resque_cries
+      Resque.enqueue(Towncrier::Workers::Resque, payload[:class], payload[:id], payload[:action])
+    end
+
+    def setup_false_cries
+      "#{payload[:class]}_crier".classify.constantize.create_cries(payload[:id], payload[:action])
+    end
+
+  end
+end