raymond 0.0.1

data/.document

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

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Christoph Petschnig
+
+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,82 @@
+= raymond
+
+Gives your view tables nice sorting ability with ease.
+
+== Usage
+
+Prepare your model: specify, which columns may get sorted.
+
+  class VeryImportantData < ActiveRecord::Base
+
+    include Raymond::Model
+
+    # sort by these db table columns
+    allow_sort_by :name, :created_at
+
+    # sort by this method, that is _not_ a db table column
+    allow_sort_by :my_custom_method, :db => false
+
+    # do a very customized sort
+    allow_sort_by :my_sort_key, :method => Proc.new{|obj| obj.my_method(:my_param)}
+
+    ...
+
+Not very much to do in the Controller:
+
+  class VeryImportantDataController < ApplicationController
+
+    def index
+      # create the sorting object and pass the sorting parameters
+      @sorting = Raymond::Control.new(self, params[:sort])
+
+      # fetch the ordered result from the db; do method based sorting if necessary.
+      @very_important_data = @sorting.result
+
+      respond_to do |format|
+        format.html # index.html.erb
+      end
+    end
+
+    ...
+
+Use a helper method in your view to show the table headers:
+
+  <tr>
+    <th><%= sort_header :name, 'Name' %></th>
+    <th><%= sort_header :my_custom_method, 'Column #2' %></th>
+    <th><%= sort_header :my_sort_key, 'Column #3' %></th>
+    <th><%= sort_header :created_at, 'Since' %></th>
+  </tr>
+
+And the helper method (not included in Gem):
+
+  def sort_header(key, label)
+    current = @sorting.current_attr?(key)
+    symbol = current ? (@sorting.dir == :up ? '▲' : '▼') : ''
+    link_to "#{symbol}#{label}", "?sort=#{key}-#{current ? @sorting.inverse_dir : Raymond::DEFAULT_SORTING_DIR.to_s}"
+  end
+
+== More Customization
+
+  @sorting = Raymond::Control.new(self, params[:sort])
+
+In the example above, the class to query it determined by the name of the controller
+applying Ruby on Rails conventions (PeopleController will use the class Person).
+Passing the option :class will allow you to use any other class:
+
+  @sorting = Raymond::Control.new(self, params[:sort], :class => PlzUseThisClass)
+
+Often, you may want more control of the underlying SQL statement. Thanks to Arel,
+anything is possible:
+
+  @comments = @sorting.result do |active_relation|
+    active_relation.where(:deleted => false).limit(20)
+  end
+
+== What's next?
+
+There's more to come, this is only version 0.0.1.
+
+== Copyright
+
+Copyright (c) 2010 Christoph Petschnig. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "raymond"
+    gem.summary = %Q{Sort columns in tables}
+    gem.description = %Q{Enhance your views with sortable tables}
+    gem.email = "info@purevirtual.de"
+    gem.homepage = "http://github.com/cpetschnig/raymond"
+    gem.authors = ["Christoph Petschnig"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "yard", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc, you must: sudo gem install yard"
+  end
+end

data/VERSION

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

data/lib/raymond.rb

@@ -0,0 +1,26 @@
+#encoding: UTF-8
+
+#module SortHelper
+#
+#  def sort_header(key, label)
+#    current = @sorterer.current_attr?(key)
+#    symbol = current ? "#{Raymond::SORTING_SYMBOLS[@sorterer.dir]} " : ''
+#    link_to "#{symbol}#{label}", "?sort=#{key}-#{current ? @sorterer.inverse_dir : Raymond::DEFAULT_SORTING_DIR.to_s}"
+#  end
+#
+#end
+
+module Raymond
+
+  SORTING_DIRECTIONS = {:up => 'ASC', :down => 'DESC'}
+
+  #   ⇓ ⇑   ➷ ➹    ➴ ➶     ▼ ▲
+  SORTING_SYMBOLS = {:up => '▲', :down => '▼'}
+
+  DEFAULT_SORTING_DIR = :down
+
+end
+
+
+require 'raymond/control'
+require 'raymond/model'

data/lib/raymond/control.rb

@@ -0,0 +1,90 @@
+module Raymond
+
+  class Control
+
+    attr_reader :dir, :attr
+
+    # Constructor
+    #
+    # @param [Object] controller is used to figure out the sort class; if option[:class] is
+    #   given, the value is ignored.
+    # @param [String, Array] sort_params comes in the string form of "my_attribute-down" or
+    #   "other_attribute-up", or in Array form of [:attribute, :direction]
+    # @param [Hash, #[]] options:
+    #   +:class+: specify which class to sort; if omitted, will try to build out
+    #   of the name of controller. The class must include Raymond::Model
+    #   +:logger+: the logger to use; defaults to the controllers logger or +Rails.logger+
+    def initialize(controller, sort_params, options = {})
+      @attr, @dir = if sort_params.kind_of?(String)
+        (sort_params || '').split('-').map(&:to_sym)
+      else
+        raise ArgumentError.new("sort_params must be either String or Array.") unless sort_params.kind_of?(Array)
+        raise ArgumentError.new("As as Array, sort_params must be in the form of [:my_attribute, :up_or_down].") unless sort_params.size == 2
+        sort_params.map(&:to_sym)
+      end
+
+      @class = if (klass = options[:class])
+        if klass.kind_of?(Class)
+          klass
+        else
+          klass.to_s.constantize    # ActiveSupport dependency
+        end
+      else
+        # class was not explicitly specified; we assume it's related to the name controller name
+        controller.class.name[0..-11].singularize.constantize  # 'Controller' is 11 characters long; ActiveSupport dependency!
+        #
+        # achieve the same without ActiveSupport:
+        #@class = Module.const_get(controller.class.name[0..-11].singularize) # 'Controller' is 11 characters long
+      end
+
+      # try to use the controllers logger, if available
+      @logger = options[:logger] || (controller.respond_to?(:logger) && controller.logger)
+
+      self.logger.warn "Trying to sort by `#{@attr}`, which is not allowed for class #{@class}." unless attr_valid?
+    end
+
+    # Returns the sorted result
+    # When a block is given, you can hook in between SQL sorting and Ruby sorting.
+    #
+    # Example:
+    #   @sorting = Raymond::Control.new(self, params[:sort], :class => MyFaboulousModel)
+    #   @retrieved_data = @sorting.result do |arel|
+    #     arel.limit(20).offset(120).where(:foo => 'bar')
+    #   end
+    #
+    # @return [Array] the results in the requested sort order
+    def result
+      result = @class.scoped
+
+      sql_order = @class.sql_sort_order(@attr, @dir)
+      result = result.order(sql_order) unless sql_order.blank?
+
+      result = yield(result) if block_given?
+
+      sort_proc = @class.sort_proc(@attr)
+      result = result.sort_by{|obj| sort_proc.call(obj)} if sort_proc
+
+      return result.reverse if sort_proc && @dir == :up
+
+      result
+    end
+
+    def inverse_dir
+      SORTING_DIRECTIONS.keys.detect{|dir| dir != @dir}
+    end
+
+    def attr_valid?
+      @class.sort_attributes.include?(@attr)
+    end
+
+    def current_attr?(attr)
+      attr.to_sym == @attr && self.attr_valid?
+    end
+
+    def logger #:nodoc:
+      @logger ||= (Module.const_defined?('Rails') && Rails.logger)
+    end
+
+  end
+end
+

data/lib/raymond/model.rb

@@ -0,0 +1,66 @@
+module Raymond
+
+  module Model
+
+    def self.included(base)
+      #  Class enhancements
+      base.extend(ClassMethods)
+    end
+
+    # the methods in this module will become class methods
+    module ClassMethods
+
+      # Define all columns or attributes, that may be sorted upon, by this method
+      # @param [Array, Hash] params can be
+      #   an array of column names
+      #   a single parameter with a Hash of options
+      def allow_sort_by(*params)
+        @sort_attributes ||= []
+
+        # give the use a little bit more freedom by allowing to pass an array of column names
+        params = params.first if params.size == 1 && params.first.kind_of?(Array)
+
+        options = params.pop if params.last.kind_of?(Hash)
+
+        raise ArgumentError.new('Method allow_sort_by takes either an array of column names or' +
+            'a single column name with a optional hash of options.') if params.size != 1 && options
+
+        params = params.map(&:to_sym)
+
+        params = [{params.first => options}] if options
+
+        # the items of params must all be column names, if params are symbols
+
+        @sort_attributes += params
+      end
+
+      def sort_attributes
+        raise "Trying to sort with no sort attributes defined." unless @sort_attributes
+        @sort_attributes.map{|attr| attr.kind_of?(Symbol) ? attr : attr.keys.first}
+      end
+
+      def sort_proc(attr)#, direction)
+        hash = @sort_attributes.detect{|obj| obj.kind_of?(Hash) && obj[attr]}
+        method_result = hash && hash[attr] && hash[attr][:method]
+        return method_result if method_result
+        hash && hash[attr] && hash[attr][:db] == false && Proc.new{|obj| obj.send(attr)}
+      end
+
+      def sql_sort_order(attr, direction)
+        second = @secondary_sort_attr ? "#{@secondary_sort_attr} #{SORTING_DIRECTIONS[@secondary_sort_direction]}" : nil
+        first = (@sort_attributes || []).include?(attr) ? "#{attr} #{SORTING_DIRECTIONS[direction]}" : nil
+        [first, second].compact.join(', ')
+      end
+
+      def secondary_sort_attr(attr, direction = :up)
+        raise ArgumentError.new("First argument of secondary_sort_attr must be a column name.") unless self.column_names.include?(attr.to_s)
+        raise ArgumentError.new("Second argument of secondary_sort_attr must be one of #{SORTING_DIRECTIONS.keys.map{|key| ":#{key}"}}.") unless SORTING_DIRECTIONS.keys.include?(direction)
+        @secondary_sort_attr = attr
+        @secondary_sort_direction = direction
+      end
+
+    end
+
+  end
+
+end

data/raymond.gemspec

@@ -0,0 +1,60 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{raymond}
+  s.version = "0.0.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Christoph Petschnig"]
+  s.date = %q{2010-11-09}
+  s.description = %q{Enhance your views with sortable tables}
+  s.email = %q{info@purevirtual.de}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+     ".gitignore",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "lib/raymond.rb",
+     "lib/raymond/control.rb",
+     "lib/raymond/model.rb",
+     "raymond.gemspec",
+     "spec/raymond_spec.rb",
+     "spec/spec.opts",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/cpetschnig/raymond}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.7}
+  s.summary = %q{Sort columns in tables}
+  s.test_files = [
+    "spec/raymond_spec.rb",
+     "spec/spec_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::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_development_dependency(%q<yard>, [">= 0"])
+    else
+      s.add_dependency(%q<rspec>, [">= 1.2.9"])
+      s.add_dependency(%q<yard>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 1.2.9"])
+    s.add_dependency(%q<yard>, [">= 0"])
+  end
+end
+

data/spec/raymond_spec.rb

@@ -0,0 +1,28 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+class MySpecController
+  include Raymond::Control
+  def index(params)
+    @sorting = Raymond::Control.new(self, params[:sort])
+    @result_array = @sorting.result
+  end
+end
+
+class MySpecModel
+  include Raymond::Model
+  
+  allow_sort_by :start_at, :title, :km
+  allow_sort_by :duration, :method => Proc.new{|obj| obj.duration(:numeric)}
+  allow_sort_by :modality, :method => Proc.new{|obj| obj.modality && obj.modality.name}
+  allow_sort_by :costs, :db => false
+
+  secondary_sort_attr :start_at
+
+  
+end
+
+describe "Raymond" do
+  it "fails" do
+    fail "hey buddy, you should probably rename this file and start specing for real"
+  end
+end

data/spec/spec.opts

@@ -0,0 +1 @@
+--color

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'raymond'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+  
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification 
+name: raymond
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: false
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Christoph Petschnig
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-09 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 13
+        segments: 
+        - 1
+        - 2
+        - 9
+        version: 1.2.9
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: Enhance your views with sortable tables
+email: info@purevirtual.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- lib/raymond.rb
+- lib/raymond/control.rb
+- lib/raymond/model.rb
+- raymond.gemspec
+- spec/raymond_spec.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/cpetschnig/raymond
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Sort columns in tables
+test_files: 
+- spec/raymond_spec.rb
+- spec/spec_helper.rb