meskyanichi-make_sortable 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,5 @@
+*.sw?
+.DS_Store
+coverage
+rdoc
+pkg

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Michael van Rooijen
+
+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.rdoc

@@ -0,0 +1,207 @@
+= Make Sortable
+
+This plugin/gem provides an easy way to implement a simple database record sorting solution.
+
+== Installation
+
+  gem sources -a http://gems.github.com
+  sudo gem install meskyanichi-make_sortable
+
+
+== Simple Setup
+
+Add the "make_sortable" method to your controller.
+
+  class PostsController < ApplicationController
+  	make_sortable
+  end
+
+The above will assume that:
+
+- You want to make "posts" sortable
+- You are using the "posts" controller
+- You are using the "post" model
+- You have a "position" attribute in your "post" model
+- You have a "position" attribute in your "posts" table
+
+Now, this single method, without any options, is already enough to start sorting!
+It will make 4 methods available to you in the view. Check the example below, it should make sense.
+
+==== RAILS_ROOT/app/views/posts/index.html.erb
+
+  <table>
+  	<tr>
+  		<th>Up</th>
+  		<th>Down</th>
+  		<th>Name</th>
+  	</tr>
+  
+  	<% @posts.each_with_index do |post, index| %>
+  	<tr>
+  		<td><%= button_up_for_posts_position(:object => @posts, :index => index) %></td>
+  		<td><%= button_down_for_posts_position(:object => @posts, :index => index) %></td>
+  		<td><%= post.name %></td>
+  	</tr>
+  	<% end %>
+  </table>
+
+Above you see a simple table, with posts being looped out using the "each_with_index" method.
+It is important that you use the "each_with_index" method, rather than just the "each" method
+since you will need the index to determine the position of each record.
+
+That's it! Just click on the up or down button and it works.
+
+==== What I always like to do is go into my mode, in this case, post.rb and add a default_scope:
+
+  class Post < ActiveRecord::Base
+  	default_scope :order => :position
+  end
+
+This will make sure that by default, all records are sorted by "position".
+
+
+== Slightly more advanced setup
+
+So, the above is quite easy to utilize if you follow the conventions, which in my option, are fine.
+Adding 1 method in a controller and providing you with helper methods to generate the buttons for the view. Quite nice.
+
+Now now, there are a couple of settings you can adjust through the make_sortable method. Settings you can adjust are:
+
+- the controller (:controller) that should be used (default: controller that it's invoked on)
+- the model (:model) that should be used (default: singular form of the controller name that the method is invoked on)
+- the attribute (:attribute) inside the model that should be used (default: position)
+- the redirect path (:redirect_path) where the user should be redirected to after the process (default: index action of specified controller) 
+- the filter (:filter) which you can use for associations. (default: nil)
+
+
+=== Specifying the :controller and :model options with make_sortable()
+
+The only time you would want to do this is when you for example have a bunch of posts displayed
+and wish to have their comments displayed below them on the same screen. Also, at the same time, you wish
+for these comments to ALSO be "sortable" from this location.
+
+==== Requirement
+
+  class PostsController < ApplicationController
+  	make_sortable # for posts
+  	make_sortable	:controller => :comments,
+  					:model => :comment
+  end
+
+We need to invoke a second "make_sortable" with the :controller => :comments and :model => :comment to let the view
+know it needs to generate the methods for comments as well for any PostController action.
+
+NOTE: Do not add any other options to the make_sortable for the comments. These settings need to be specified inside the CommentsController
+where they belong.
+
+==== So be sure to add the "make_sortable" method inside the CommentsController
+
+  class CommentsController < ApplicationController
+  	make_sortable
+  end
+
+And add any additional options to the "make_sortable" method here, NOT inside the PostsController.
+
+
+=== Using a different model/database attribute
+
+So you have your database set up with the attribute "order" instead of "position" and wish to use it instead of the default "position".
+
+==== Apply the following option to the "make_sortable()" method
+
+  class PostsController < ApplicationController
+  	make_sortable :attribute => :order
+  end
+
+=== Changing the "Redirect Path"
+
+If you do not wish to have your users be redirected to the index action after clicking on a "up" or "down" button to update the records "position",
+you can change this very easily.
+
+==== Redirecting to a different action
+
+  class PostsController < ApplicationController
+  	make_sortable :redirect_path => {:action => "other_action"}
+  end
+
+If you simply wish to return to the page on which you were when clicking on the "up" or "down" button, apply the following option.
+
+==== Redirecting Back
+
+  class PostsController < ApplicationController
+  	make_sortable :redirect_path => :back
+  end
+
+=== Filtering position updates
+
+So you are building a web application which has mulitple users, and each user has it's own posts. Obviously you do not want "User 1" to update
+"User 2"'s posts position. By default, "User 1" will have the ability to update "ALL" posts when updating his. Of course, that'd mean "User 1" should be able to see other users' posts. Regardless, it's best to just filter out that kind of behavior on the back-end to prevent it from ever happening.
+
+For example, we have a logged in user, and we store all it's data inside the "current_user" method/variable. It's an AR Object.
+Now, when this user clicks on the "up" or "down" button of a post item, we want to make sure that regardless of what he sees on the front-end,
+can't be adjusted unless he is the owner of the post.
+
+==== You can accomplish this by adding the following option
+
+  class PostsController < ApplicationController
+  	make_sortable :filter => current_user
+  end
+
+==== If you need to chain in a way (maybe for the users' -> post' -> comments), you can just do the following
+
+  class CommentsController < ApplicationController
+  	make_sortable :filter => current_user.post
+  end
+
+== View Helpers
+
+When the "make_sortable" method is invoked on a controller, it will dynamically generate 4 view helpers for you to use.
+
+==== Let's say we've written the following
+
+  class PostsController < ApplicationController
+  	make_sortable
+  end
+
+The above would provide you with 4 methods. These methods will be available to all "PostController" views.
+
+- button_up_for_posts_position		:object, :index, :html
+- button_down_for_posts_position	:object, :index, :html
+- link_up_for_posts_position		:object, :index, :html
+- link_down_for_posts_position		:object, :index, :html
+
+If you for any reason need these methods inside a different controller, see the (above) topic:
+"Specifying the :controller and :model options with make_sortable()"
+
+All 4 methods take the same arguments. Let me explain.
+
+==== Argument: :object
+This is a required argument. It expects you to provide the object/(array) on which you are performing the .each_with_index method.
+
+  button_up_for_posts_position(:object => @posts)
+
+==== Argument: :index
+This is a required argument. It expects you to provide the index of the currently looping object(record). You can get this index when calling .each_with_index on the @posts object/(array)
+
+  @posts.each_with_index do |post, index|
+  	button_up_for_posts_position(:object => @posts, :index => index)
+  end
+
+The example above is basically all that's required to get the sorting gem working. The :html argument is optional.
+Basically, it's like the "link_to()" and "button_to()" methods in the Rails-Core. With it you can provide any additional HTML attributes to the HTML tag.
+
+==== Argument: :html
+
+  button_up_for_posts_position(:object => @posts, :index => index, :html => {
+  	:id		=> "post_id_#{post.id}",
+  	:class	=> "post_class",
+  	:etc	=> "etc_etc_etc"
+  })
+
+So you are free to add whatever additional html attributes you like to all 4 methods.
+
+
+
+== Copyright
+
+Copyright (c) 2009, Michael van Rooijen / Final Creation. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,54 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "make_sortable"
+    gem.summary = "The \"Make Sortable\" Plugin/Gem makes database records sortable in a simple, quick and easy way."
+    gem.description = "This plugin/gem provides an easy way to implement a simple database record sorting solution."
+    gem.email = "meskyan@gmail.com"
+    gem.homepage = "http://github.com/meskyanichi/make_sortable"
+    gem.authors = ["Michael van Rooijen", "Jeff Kreeftmeijer"]
+  end
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "make_sortable #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/init.rb

@@ -0,0 +1 @@
+ActionController::Base.send(:include, MakeSortable)

data/lib/make_sortable/actions.rb

@@ -0,0 +1,20 @@
+module MakeSortable
+  module Actions
+    # Generates the necessary controller action which the user must route to.
+    def generate_controller_action
+      Kernel.const_get(controller_fullname).class_eval do
+        options = MakeSortable::get_options
+        define_method options[:attribute] do
+          params[options[:controller]].each_with_index do |id, index|
+            unless options[:filter]
+              Kernel.const_get(options[:model]).update_all(["#{options[:attribute]}=?", index+1], ['id=?', id])
+            else
+              options[:filter].send(options[:model].underscore.pluralize.to_sym).update_all(["#{options[:attribute]}=?", index+1], ['id=?', id])
+            end
+          end
+          redirect_to options[:redirect_path]
+        end
+      end
+    end
+  end
+end

data/lib/make_sortable/array.rb

@@ -0,0 +1,12 @@
+module MakeSortable
+  module Array
+    
+    # Swaps values of an array.
+    def swap(a,b)
+      swapped = self.clone
+      swapped[a], swapped[b] = self[b], self[a]
+      swapped
+    end
+    
+  end
+end

data/lib/make_sortable/helpers.rb

@@ -0,0 +1,78 @@
+module MakeSortable
+  module Helpers
+   
+   # This method generates the necessary view helpers to generate the up/down links/buttons.
+   def generate_view_helpers
+    
+     # Open the ActionController::Base class to insert the helper methods for the views
+     ActionController::Base.class_eval do
+       
+       # Includes ActionView::Helpers to be able to generate specific HTML tags for the methods below
+       include ActionView::Helpers
+     
+       options = MakeSortable::get_options
+     
+       # Enable Helper Method for Views
+       helper_method "button_up_for_#{options[:controller]}_#{options[:attribute]}",
+                     "link_up_for_#{options[:controller]}_#{options[:attribute]}",
+                     "button_down_for_#{options[:controller]}_#{options[:attribute]}",
+                     "link_down_for_#{options[:controller]}_#{options[:attribute]}"
+    
+        # Loop through both the button and link symbols to generate link_to and button_to helpers
+        [:button, :link].each do |trigger|
+
+         # Defines the up button helper method for the specified controller/action and attribute
+         define_method "#{trigger}_up_for_#{options[:controller]}_#{options[:attribute]}" do |view_options|
+           if trigger.eql?(:button)
+             if view_options[:index] > 0
+               
+               button_to( view_options[:name]         || "up",
+                         {:controller                 => options[:controller],
+                         :action                      => options[:attribute],
+                          options[:controller].to_sym => view_options[:object].swap(view_options[:index],
+                          view_options[:index] -1 )}, view_options[:html])
+                          
+             end
+           else
+             if view_options[:index] > 0
+               
+               link_to(   view_options[:name]         || "up",
+                         {:controller                 => options[:controller],
+                         :action                      => options[:attribute],
+                          options[:controller].to_sym => view_options[:object].swap(view_options[:index],
+                          view_options[:index] -1 )}, view_options[:html])
+                          
+             end
+           end
+         end
+       
+         # Defines the helper method for the specified controller/action and attribute
+         define_method "#{trigger}_down_for_#{options[:controller]}_#{options[:attribute]}" do |view_options|
+           if trigger.eql?(:button)
+             if view_options[:index] < view_options[:object].length - 1
+               
+               button_to( view_options[:name]         || "down",
+                         {:controller                 => options[:controller],
+                         :action                      => options[:attribute],
+                          options[:controller].to_sym => view_options[:object].swap(view_options[:index],
+                          view_options[:index] +1 )}, view_options[:html])
+                          
+             end
+           else
+             if view_options[:index] < view_options[:object].length - 1
+               
+               link_to( view_options[:name]         || "down",
+                        {:controller                 => options[:controller],
+                        :action                      => options[:attribute],
+                        options[:controller].to_sym  => view_options[:object].swap(view_options[:index],
+                        view_options[:index] +1 )}, view_options[:html])
+                        
+             end
+           end
+         end
+         
+        end # => Each
+      end # => ActionController::Base
+    end # => MakeSortable::Helpers::generate_view_helpers
+  end # => MakeSortable::Helpers
+end # => MakeSortable

data/lib/make_sortable.rb

@@ -0,0 +1,67 @@
+module MakeSortable
+  
+  class << self
+    
+    include MakeSortable::Actions
+    include MakeSortable::Helpers
+    
+    attr_accessor :controller, :controller_fullname, :attribute, :redirect_path, :filter, :model
+    
+    # Sets all the required options. These will be available throughout the library.
+    def set_options(options, controller_name)
+      @controller            = options[:controller] || controller_name
+      @controller_fullname   = "#{@controller}_controller".camelcase
+      @attribute             = options[:attribute] || 'position'
+      @redirect_path         = options[:redirect_path] || {:action => :index}
+      @filter                = options[:filter]
+      
+      if options[:model].blank?
+        @model = controller_name.singularize.camelcase
+      else
+        @model = options[:model].to_s.singularize.camelcase
+      end
+    end
+    
+    # Returns the set of options in their corresponding hash-key name.
+    def get_options
+      @options = Hash.new unless defined?(@options)
+      ['controller', 'controller_fullname', 'attribute', 'redirect_path', 'filter', 'model'].each do |option|
+        @options[option] = instance_variable_get("@#{option}")
+      end
+      @options.symbolize_keys
+    end
+    
+  end
+  
+  # Initializes when the module gets included into ActiveRecord::Base
+  def self.included(base)
+    base.extend InitializeMethods 
+  end
+  
+  # ActMethods are not initialized unless the user requests it.
+  module InitializeMethods 
+    
+    # Initializes the positioning method
+    def make_sortable(options = {})
+
+      # Define and Return the controller, model and attribute
+      MakeSortable::set_options(options, controller_name)
+      
+      # Include the Array module into the Array Class to add the "swap" method functionality
+      unless Array.methods.respond_to?(:swap)
+        Array.send(:include, MakeSortable::Array)
+      end
+
+      # Generates the controller action
+      # Makes it available in the corresponding controller
+      MakeSortable::generate_controller_action
+
+      # Generates the view helpers
+      # Makes them available in ActionController::Base
+      MakeSortable::generate_view_helpers
+      
+    end # => InitializeMethods#make_sortable
+  end # => InitializeMethods
+end # => MakeSortable
+
+ActionController::Base.send(:include, MakeSortable)

data/make_sortable.gemspec

@@ -0,0 +1,54 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{make_sortable}
+  s.version = "0.1.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Michael van Rooijen", "Jeff Kreeftmeijer"]
+  s.date = %q{2009-08-16}
+  s.description = %q{This plugin/gem provides an easy way to implement a simple database record sorting solution.}
+  s.email = %q{meskyan@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "init.rb",
+     "lib/make_sortable.rb",
+     "lib/make_sortable/actions.rb",
+     "lib/make_sortable/array.rb",
+     "lib/make_sortable/helpers.rb",
+     "make_sortable.gemspec",
+     "test/make_sortable_test.rb",
+     "test/test_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/meskyanichi/make_sortable}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{The "Make Sortable" Plugin/Gem makes database records sortable in a simple, quick and easy way.}
+  s.test_files = [
+    "test/make_sortable_test.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/test/make_sortable_test.rb

@@ -0,0 +1,7 @@
+require 'test_helper'
+
+class MakeSortableTest < Test::Unit::TestCase
+  should "probably rename this file and start testing for real" do
+    flunk "hey buddy, you should probably rename this file and start testing for real"
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'test/unit'
+require 'shoulda'
+
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'make_sortable'
+
+class Test::Unit::TestCase
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification 
+name: meskyanichi-make_sortable
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Michael van Rooijen
+- Jeff Kreeftmeijer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-08-16 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: This plugin/gem provides an easy way to implement a simple database record sorting solution.
+email: meskyan@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- init.rb
+- lib/make_sortable.rb
+- lib/make_sortable/actions.rb
+- lib/make_sortable/array.rb
+- lib/make_sortable/helpers.rb
+- make_sortable.gemspec
+- test/make_sortable_test.rb
+- test/test_helper.rb
+has_rdoc: false
+homepage: http://github.com/meskyanichi/make_sortable
+licenses: 
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: The "Make Sortable" Plugin/Gem makes database records sortable in a simple, quick and easy way.
+test_files: 
+- test/make_sortable_test.rb
+- test/test_helper.rb