mention_system 0.0.6

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a9832b3de5374b194dbe23671741890a0be2c9e6
+  data.tar.gz: 63d03b4497243bf782891a3f12afd7e9b0fe6be4
+SHA512:
+  metadata.gz: 3c7bc689c331e4a13baa3f8b2cb15a745d6c4e5835980869c5fd0d4a0b6419feee28500068f7cd313e09124f59af1de3191f8258a6cc53a6e016934e7d45de08
+  data.tar.gz: 776a9a2276c94eda158771b95de5d601851e9101132d66ea137ca200604949b3c578378202b3845c5fd4665ef92205b1c68350d3563d91a8d1279c687eb5792c

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/gemfiles/*.lock
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/.ruby-gemset

@@ -0,0 +1 @@
+mention_system

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.2.1

data/.travis.yml

@@ -0,0 +1,23 @@
+language:
+  - ruby
+
+rvm:
+  - 2.0.0
+  - 2.1.3
+  - 2.2.1
+
+gemfile:
+  - gemfiles/rails4.1.gemfile
+  - gemfiles/rails4.2.gemfile
+
+install:
+  - "travis_retry bundle install"
+
+before_script:
+
+script:
+  - "bundle exec rake"
+
+branches:
+  only:
+    - master

data/Appraisals

@@ -0,0 +1,7 @@
+appraise "rails4.1" do
+  gem "rails", "4.1.10"
+end
+
+appraise "rails4.2" do
+  gem "rails", "4.2.1"
+end

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mention_system.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Pablo Martin Viva
+
+MIT License
+
+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,170 @@
+# MentionSystem
+
+[![Build Status](https://travis-ci.org/pmviva/mention_system.png?branch=master)](https://travis-ci.org/pmviva/mention_system)
+[![Gem Version](https://badge.fury.io/rb/mention_system.svg)](http://badge.fury.io/rb/mention_system)
+
+An active record mention system developed using ruby on rails 4.1 applying domain driven design and test driven development principles.
+
+This gem is heavily influenced by cmer/socialization.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mention_system'
+```
+
+And then execute:
+
+```ruby
+$ bundle
+```
+
+Or install it yourself as:
+
+```ruby
+$ gem install mention_system
+```
+
+## Usage
+
+### Run the generator
+
+```ruby
+$ rails g mention_system
+```
+
+Let's suppose for a moment that you have a blog application and a Post can mention a User or several User models.
+The post model becomes the mentioner and the user model becomes the mentionee.
+
+### User object
+```ruby
+class User < ActiveRecord::Base
+  act_as_mentionee
+
+  validates :username, { presence: true, uniqueness: true }
+end
+```
+
+### Post object
+```ruby
+class Post < ActiveRecord::Base
+  act_as_mentioner
+
+  validates :content, presence: true
+end
+```
+
+### Mentionee object methods
+```ruby
+user.is_mentionee? # returns true
+
+user.mentioned_by?(post) # returns true if post mentions the user object, false otherwise
+
+user.mentioners_by(Post) # returns a scope of MentionSystem::Mention join model that belongs to the user object and belongs to mentioner objects of type Post
+```
+
+
+### Mentioner object methods
+```ruby
+post.is_mentioner? # returns true
+
+post.mention(user) # Creates an instance of MentionSystem::Mention join model associating the post object and the user object, returns true if succeded, false otherwise
+
+post.unmention(user) # Destroys an instance of MentionSystem::Mention join model that associates the post object and the user object, returns true if succeded, false otherwise
+
+post.toggle_mention(user) # Mentions / unmentions the user
+
+post.mentions?(user) # returns true if the post object mentions the user object, false otherwise
+
+post.mentionees_by(User) # returns a scope of MentionSystem::Mention join model that belongs to the post object and belongs to mentionee objects of type User
+```
+
+### Mention processors
+Mention processors are objects in charge of computing mentions between mentioner objects and mentionee objects.
+The framework provides a base mention processor class that the developer should subclass.
+Mention processors provide after / before callbacks to hook custom behavior before and after a mention is computed.
+
+Let's suppose we want to parse a post content and process mentions in the form of "@username". We first define a custom mention processor instructing how to compute a post content and how to retrieve a collection of users by the handles mentioned in the post content.
+
+### CustomMentionProcessor object
+```ruby
+class CustomMentionProcessor < MentionSystem::MentionProcessor
+  ###
+  # This method returns the content used to parse mentions from the mentioner object, in this case is post's content
+  ###
+  def extract_mentioner_content(post)
+    post.content
+  end
+
+  ###
+  # This method should return a collection (must respond to each) of mentionee objects for a given set of handles
+  # In our case will be a collection of user objects
+  ###
+  def find_mentionees_by_handles(*handles)
+    User.where(username: handles)
+  end
+end
+```
+
+When we call
+```ruby
+user1 = User.create(username: "test1")
+user2 = User.create(username: "test2")
+post = Post.create(content: "Post content mentioning @test1 and @test2")
+
+m = CustomMentionProcessor.new
+m.process_mentions(post)
+```
+
+It will process a mention between "post" and "user1" and also a mention between "post" and "user2".
+
+### Mention processor callbacks
+Suppose we want to validate if a user can be mentioned before a mention is processed, we can register a before callback in the mention processor.
+Now lets suppose we want to send a notification email when a mention is given to a user, we can register an after callback in the mention processor.
+
+Lets see an example of both:
+
+```ruby
+m = CustomMentionProcessor.new
+
+m.add_before_callback Proc.new { |post, user| user.mentions_allowed? }
+m.add_after_callback Proc.new { |post, user| UserMailer.notify_mention(post, user) }
+
+m.process_mentions(post)
+```
+
+Now when the mention processor process the mentions in the post content, it should validate first if the user is allowed to mention and after the mention is processed an email sent notifying the mention.
+
+You can register several callbacks and they will be called in order.
+* When a before callback return false it will not call any further before callback, nor process the mention nor will call any after callbacks.
+* When a mention could not be processed none of the after callbacks will be called.
+* When an after callback returns false it will not call any further after callback.
+
+You can override the prefix used to parse mentions, it defaults to "@" but you can change to any prefix you like, for example "#", so that mention processors can recognize #test1 and #test2 instead of @user1 and @user2.
+
+To do that you need to override the mention_prefix method in the mention processor.
+
+```ruby
+class CustomMentionProcessor < MentionSystem::MentionProcessor
+  private:
+    ###
+    # Defines the mention prefix used to parse mentions, defaults "@"
+    ###
+    def mention_prefix
+      "#"
+    end
+end
+```
+
+For more information read the [api documentation](http://rubydoc.info/gems/mention_system).
+
+## Contributing
+
+1. Fork it ( https://github.com/pmviva/mention_system/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+
+task :default => [:spec]
+desc 'run Rspec specs'
+task :spec do
+  sh 'rspec spec'
+end
+

data/gemfiles/rails4.1.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "4.1.10"
+
+gemspec :path => "../"

data/gemfiles/rails4.2.gemfile

@@ -0,0 +1,7 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "rails", "4.2.1"
+
+gemspec :path => "../"

data/lib/generators/mention_system/mention_system_generator.rb

@@ -0,0 +1,46 @@
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+###
+# MentionSystemGenerator class
+#
+# This class generates the mention model migration in mention system
+###
+class MentionSystemGenerator < Rails::Generators::Base
+  ###
+  # Includes Rails::Generators::Migration
+  ###
+  include Rails::Generators::Migration
+
+  ###
+  # Generator description definition
+  ###
+  desc "Generates a migration for the Mention model"
+
+  ###
+  # Retrieves the source root
+  #
+  # @return [String]
+  ###
+  def self.source_root
+    @source_root ||= File.dirname(__FILE__) + '/templates'
+  end
+
+  ###
+  # Retrieves the next migration number
+  #
+  # @path [String] path - the path to calculate the next migration number
+  # @return [String]
+  ###
+  def self.next_migration_number(path)
+    ActiveRecord::Generators::Base.next_migration_number(path)
+  end
+
+  ###
+  # Generates the migration
+  ###
+  def generate_migration
+    migration_template 'migration.rb', 'db/migrate/create_mentions.rb'
+  end
+end
+

data/lib/generators/mention_system/templates/migration.rb

@@ -0,0 +1,47 @@
+###
+# CreateMentions class
+#
+# This class defines the create mentions migration in mention system
+###
+class CreateMentions < ActiveRecord::Migration
+  ###
+  # Changes the database
+  ###
+  def change
+    ###
+    # Mentions table creation
+    ###
+    create_table :mentions do |t|
+      ###
+      # Mentionee id field and mentionee type field definition
+      ###
+      t.references :mentionee, polymorphic: true
+
+      ###
+      # Mentioner id fiel and mentioner type field definition
+      ###
+      t.references :mentioner, polymorphic: true
+
+      ###
+      # Timestamps fields definition
+      ###
+      t.timestamps null: false
+    end
+
+    ###
+    # Mentions table mentionee id field and mentionee type field index addition
+    ###
+    add_index :mentions, [:mentionee_id, :mentionee_type], name: "mentions_mentionee_idx"
+
+    ###
+    # Mentions table mentioner id field and mentioner type field index addition
+    ###
+    add_index :mentions, [:mentioner_id, :mentioner_type], name: "mentions_mentioner_idx"
+
+    ###
+    # Mentions table mentionee id field and mentionee type field and mentioner id field and mentioner type field unique index addition
+    ###
+    add_index :mentions, [:mentionee_id, :mentionee_type, :mentioner_id, :mentioner_type], name: "mentions_mentionee_mentioner_idx", unique: true
+  end
+end
+

data/lib/mention_system.rb

@@ -0,0 +1,46 @@
+require 'mention_system/mention'
+require 'mention_system/mention_processor'
+require 'mention_system/mentionee'
+require 'mention_system/mentioner'
+
+###
+# MentionSystem module
+#
+# This module defines common behavior in mention system
+###
+module MentionSystem
+  ###
+  # Specifies if self can be mentioned by {Mentioner} objects
+  #
+  # @return [Boolean]
+  ###
+  def is_mentionee?
+    false
+  end
+
+  ###
+  # Specifies if self can mention {Mentionee} objects
+  #
+  # @return [Boolean]
+  ###
+  def is_mentioner?
+    false
+  end
+
+  ###
+  # Instructs self to act as mentionee
+  ###
+  def act_as_mentionee
+    include Mentionee
+  end
+
+  ###
+  # Instructs self to act as mentioner
+  ###
+  def act_as_mentioner
+    include Mentioner
+  end
+end
+
+ActiveRecord::Base.extend MentionSystem
+