social_engine 0.0.1

data/Gemfile

@@ -0,0 +1,13 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "shoulda", ">= 0"
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.1"
+  gem "rcov", ">= 0"
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 John McAliley
+
+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,340 @@
+# social_engine
+
+social_engine is a rails engine that provides very basic social functionality that you can attach to any model, including comments, ratings, voting, favorites, user reputation, and friend relations.  This plugin is intended to provide you with building blocks, as opposed to a full blown social networking site.  Each building block is customizable and social_engine provides the controllers, helpers, models and css friendly views.  You just include the helpers in your view, provide any non-default options and customize the look using CSS.  This is only compatible with Rails 3 and Ruby 1.9.2.
+
+## Installation
+
+Add this to your Gemfile and run "bundle install"
+  
+    gem "social_engine"
+
+Run the social_engine generator to add the needed migrations and static assets
+  
+    rails g social_engine:install
+    
+If you plan on using the user reputation module, then you will also need to run that generator, which will alter your 'users' table and add a field named "reputation"
+
+    rails g social_engine:user_reputation
+
+Run the migrations
+
+    rake db:migrate
+
+This will add the following tables to your database:
+
+    comments
+    ratings
+    votes
+    favorites
+    reputations
+    reputation_actions
+    friendings
+
+## Usage
+
+Here is an example of how you would add functionality this on an 'Article' model:
+
+    class Article < ActiveRecord::Base
+      is_sociable
+    end
+    
+When you add this line to your model, it makes it rateable, voteable and commentable, and favoriteable.  You can also add the functionality individually if you do not want all 4 social aspects in your model.
+
+    class Article < ActiveRecord::Base
+      is_commentable
+      is_voteable
+      is_rateable
+      is_favoriteable
+    end
+    
+You will also need to add nested resources to the Article route.  In config/routes.rb:
+
+    resources :articles do
+      resources :comments,:votes,:ratings,:favorites
+    end
+
+Make your user model social and make it have reputation
+
+    class User < ActiveRecord::Base
+      has_reputation
+      is_social
+    end
+
+If you want users to also be able to 'friend' each other, just add this
+
+    class User < ActiveRecord::Base
+      has_reputation
+      is_social
+      is_friendable
+    end
+
+
+## View helpers
+
+For most situations, these helpers will suffice.  The view helpers will give you forms, widgets or lists and social_engine provides controllers that will redirect to :back when you submit the forms.  Using HAML for examples, but you can use the same inside <% %> for erb
+    
+create up/down/count vote widget (similar to Stack Overflow)
+
+    = vote_widget(@article)
+
+adds 5 radio buttons (by default) and a submit to rate something 1-5
+
+    = rating_form(@article)
+    
+add a rating form with custom number of radio buttons
+
+    = rating_form(@article, 3)
+
+Create a default comment form
+
+    = comment_form(@article)
+    
+Create a comment form using options.  By default, the form will ask for name, email and website.  You can specify which fields you want and the text that should be displayed as the label for each.
+
+    # pass symbols to use the default name and email labels
+    = comment_form(@article, :name , :email)
+    # customize the name label by passing a value
+    = comment_form(@article, :name=>{:label=>"My Name"} , :email)
+
+List the comments using defaults
+
+    = comments_list(@article)
+    
+List the comments with options.  Defaults shown, all options are optional.  For the date format, you should use the formats show here: http://snippets.dzone.com/posts/show/2255
+
+    = comments_list(@article, {:display_posted_by => true, 
+                               :display_date => true, 
+                               :date_format => "%m/%d/%Y at %H:%M"})
+
+Button so user can add it to their favorites list.  This button will toggle b/w Add & Remove
+
+    = favorites_widget(@article)
+
+Default Tweetme button
+
+    = tweetme
+
+Tweetme button with options (all are optional with defaults shown as the values in this example)
+
+    = tweetme(:url => "http://mysaweetsite.com", 
+              :text => "This website is saweet!", 
+              :via => "@cowboycoded", # appends via to end of tweet
+              :count => "horizontal")  # this will show the tweet count:  horizontal, vertical or none
+
+Default Facebook Like button
+
+    = fb_like
+
+Facebook Like button with options (all are optional with defaults shown as the values in this example)
+
+    = fb_like(:url => request.url, 
+              :layout => "standard", # standard, button_count or box_count
+              :faces => true, # true or false
+              :width => 450, # your choice
+              :action => "like", # like or recommend
+              :font => "lucida grande", # arial, lucida grande, segoi ui, tahoma, trebuchet ms, or verdana
+              :colorscheme => "light",  #light or dark
+              :div_id: "fblike")  #your choice
+        
+Default Facebook Friend box
+
+    = fb_friend_box
+    
+Facebook Friend box with options (all are optional)
+
+    = fb_friend_box( :width => 250, 
+                     :stream => false, 
+                     :header => true, 
+                     :faces => true, 
+                     :fb_page_url => "http://www.facebook.com/couponshack" )
+                     
+                     
+                     
+The views are meant to be CSS friendly and allow you to adjust the look of every part of the view by overriding the default styles.  You can make changes to public/stylesheets/social_engine.css.
+    
+## Models
+
+You are not tied to using the provided views and controllers to manage comments, votes, favorites and reputation.  If you prefer your own implementation of controllers & views, you can still use the functionality of the models.
+
+Again, you need to make your model sociable first and make your user model have rep and be social
+
+    class Post < ActiveRecord::Base
+      is_sociable
+    end
+    
+    class User < ActiveRecord::Base
+      is_social
+      has_reputation
+    end
+
+Once your model is sociable, you can add comments, ratings, votes, and favorites in the following ways.  
+
+First create an instance of Post, so we can use the social methods that are included when you specify the post is_sociable:
+
+    post = Post.create(:name => "post")
+
+###Voting:
+
+Upvote a post:
+
+    post.upvote
+    post.vote_count #=> 1
+    
+Downvote a post:
+
+    post.downvote
+    post.vote_count #=> -1
+
+Create a vote and vote value manually:
+ 
+    post.votes.create(:value => 99)
+    post.vote_sum #=> 99
+
+Delete all votes for a post:
+
+    post.upvote
+    post.votes.first.destroy
+    post.votes.size #=> 1  Why?? The set is cached
+    post.votes(true) # you have to reload the set by passing true
+    post.votes.size #=> 0
+    
+NOTE: By default, voting is restricted to one per ip_address per object.  There are 2 ways around this:
+1. Set fingerprint_method to "none" in config/yettings/social_engine.yml, which will disable the uniqueness validation
+2. pass validate false to the save method to skip validations.  You have to use new/save instead of create like so:
+    
+    vote = post.votes.new(:value=>1)
+    vote.save(false) # or vote.save(:validate=>false)
+
+###Comments
+
+Create a comment and attach a user to it
+
+    post.comments.create(:comment => "I'm sure whatever your thinking is correct", :user_id=>123)
+    
+Create a comment using an anauthenticated user
+
+    post.comments.create(:comment => "I'm sure whatever your thinking is correct", 
+                         :unauthenticated_name => "ignored name",
+                         :unauthenticated_email => "ignore@email.com",
+                         :unauthenticated_website => "http://ignore.com")
+
+Destroy a comment
+
+    post.comments.first.destroy
+    post.comments(true)  # remove the cache, so you can get the correct array size if you need it
+
+###Ratings    
+
+Create a new rating with a user_id
+
+    post.ratings.create(:value=>5, :user_id=>123)
+    
+Destroy a rating for a user_id
+
+    post.ratings.where(:user_id=>123).destroy_all
+    
+Destroy all ratings for a post
+
+    post.ratings.destroy_all
+
+###Favorites
+
+    post.favorites.create(:user_id=>123)
+    User.find(123).favorites #=> outputs the favorite you just created
+
+###Reputation
+
+A primitive admin panel is provided to allow you to adjust reputation action values based on their name.  The names of all reputation actions are pulled directly from 
+the source code and a list is provided at the bottom of the admin panel for your convenience.
+
+There is a Reputation model and a ReputationAction model.  Reputation stores the reputation_action_id, user_id, and the value.  ReputationAction stores the name of an action, which is defined by you, and the default value.  
+Note that if you change the value, you will have to update the existing records in the reputation table manually.  By default, the reputation table stores the value of the reputation action at the time of creation.
+So in order for you to add reputation points to a user, you have to define the action and pass the user.  Let's say you have a reputation action called "answered question" with a value of 5 points.  And you have a controller 
+called answers, with a create method.  You would add this method to the controller:
+
+    class AnswersController < ApplicationController
+      def create
+        #do some stuff here to create the answer
+        
+        # add the reputation
+        Reputation.add("answered question", current_user)
+      end
+
+The method aboves assumes that "current_user" returns the logged in user in this session.  This add a record to the reputations table.  If you ran the user_reputation generator shown in the Installation section of this document, then 
+then Reputation.add will also add the value of that reputation action to the "reputation" field in the users table.  This field is used to avoid joins and store the sum of all reputation record's values for that user.
+
+Assuming you have the "reputation" field in your users table, you just do this to get the total reputation value:
+
+    User.first.reputation
+    
+Or if you choose not to add that field, you can get the reputation this way:
+
+    User.first.reputations.sum(:value)
+
+### Friends
+By making your User model friendable, you allow users to request friends and to confirm or reject friendship requests that come their way. The friendship model is directional, meaning it distinguishes between the friendor and the friendee. This may be useful for situations where users can "follow" others, while having many followers.
+
+You can have @user request to be friends with @other_user
+
+    @user.add_friend(@other_user)
+
+Get the last user who requested to be friends with @other_user
+
+    @other_user.requesting_friends.last #=> @user
+
+You can get the same result through the Friending record for that request
+
+    @other_user.friend_requests.last.friendor #=> @user
+
+Confirm the request
+
+    @other_user.friend_requests.last.confirm
+
+Or reject it
+
+    @other_user.friend_requests.last.reject
+
+If you want your app to skip the confirmation step and automatically activate all friend requests, set confirm_friends to "false" in config/yettings/social_engine.yml
+
+You also get the following instance methods for your users
+
+    @user.friends   #=> Return collection of users that are friends with @user
+    @user.friendors #=> Only list friends that have requested friendship with @user
+    @user.friendees #=> Only list friends that @user has requested friendship with
+
+These methods return only friends that are confirmed and not rejected. To get info on unconfirmed friends:
+
+    @user.pending_friends    #=> Return users that have not confirmed friendship requests from @user.
+                             #   This will include users that have rejected a friendship request from @user.
+    @user.requesting_friends #=> Return users that have requested to be friends with @user, but which @user has not confirmed
+    @user.rejected_friends   #=> users from which @user has rejected a friendship request
+
+The above methods are all associated with collections of Friending instances, which can be obtainer from the friendorings, friendeeings, pending_friendships, friend_requests, and friend_rejections instance methods for User.
+
+## Development Roadmap / TODO
+###Features
+1. More helpers for reputation
+2. Ajax methods for controllers & views, so you don't have to redirect_to :back
+3. Improve CSS and views
+
+###Behind the scenes
+1. Better test coverage
+2. Refactoring and DRYing (mainly tests)
+
+
+
+## Contributing to social_engine
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests.  Patches will not be accepted without Rspec or Cucumber tests.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2011 John McAliley. See LICENSE.txt for
+further details.
+

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/app/controllers/comments_controller.rb

@@ -0,0 +1,13 @@
+class CommentsController < InheritedResources::Base
+  def create
+    create! do |success, failure|
+      success.html do
+        add_fingerprint_and_user_id(@comment,true)
+        add_able_rep("commented on",@comment)
+        Reputation.add("commentor",current_user)
+        redirect_to :back
+      end
+      failure.html { redirect_to :back }
+    end
+  end
+end

data/app/controllers/favorites_controller.rb

@@ -0,0 +1,21 @@
+class FavoritesController < InheritedResources::Base
+  def create
+    create! do |success, failure|
+      success.html do
+        add_fingerprint_and_user_id(@favorite,true)
+        add_able_rep("favorited",@favorite)
+        redirect_to :back
+      end
+      failure.html { redirect_to :back }
+    end
+  end
+  
+  def destroy
+    def destroy
+      destroy! do |success, failure|
+        success.html{redirect_to :back}
+        failure.html{redirect_to :back}
+      end
+    end
+  end
+end

data/app/controllers/ratings_controller.rb

@@ -0,0 +1,15 @@
+class RatingsController < InheritedResources::Base
+  def create
+    @rating = Rating.new(params[:rating])
+    set_polymorphic_vars(@rating,"rateable")
+    add_fingerprint_and_user_id(@rating)
+
+    create! do |success, failure|
+      success.html do
+        Reputation.add("rated",current_user)
+        redirect_to :back
+      end
+      failure.html { redirect_to :back }
+    end
+  end
+end

data/app/controllers/reputation_actions_controller.rb

@@ -0,0 +1,13 @@
+class ReputationActionsController < InheritedResources::Base
+  def create
+    create!{reputation_actions_url}
+  end
+  
+  def update
+    update!{reputation_actions_url}
+  end
+  
+  def destroy
+    destroy!{reputation_actions_url}
+  end
+end