has_browser 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 James Golick, Giraffesoft Inc.
+
+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

@@ -0,0 +1,44 @@
+HasBrowser
+==========
+
+has_browser makes it possible to create simple, parameterized browser interfaces to your models. That is, given a set of parameters, return all the models that match.
+
+== Usage
+
+It's a simple plugin, with a simple syntax. Using the canonical blog example, let's imagine we want to create a browse interface to posts. We'd want the user to be able to browse by category, author, or tags, but not to be able to access any of the other finders on the Post model for obvious security reasons. To set up has_browser, we'd do something like this:
+
+  has_browser :category, :tags, :author
+
+Then, assuming the has_finders are already written, the posts can be browsed as follows:
+
+  Post.browse(:category => 'Testing', :tags => 'activerecord', :author => 'james')
+
+In that example, each of the finders requires an argument; has_browser also supports finders that don't. As long as the argumentless finder is present in the browse hash, it will be called:
+
+  has_browser :category, :tags, :author, :without_args => [:order_by_date, :order_by_number_of_comments]
+
+  Post.browse(:category => 'Testing', :tags => 'activerecord', :author => 'james', :order_by_number_of_comments => 'true')
+
+Browse can also be called from association_proxies. For a multi-blog platform, we could easily restrict browsing of posts to the current blog:
+
+  @blog.posts.browse(:category => 'Testing', :tags => 'activerecord', :author => 'james', :order_by_number_of_comments => 'true')
+
+Since has_browser returns the same proxy as has_finder, it is possible to further restrict the results of a browse by chaining finders after the browse call. With our blog, for example, we'd probably want to restrict browsing to published posts.
+
+  @blog.posts.browse(:category => 'Testing', :tags => 'activerecord', :author => 'james', :order_by_number_of_comments => 'true').published
+
+Note: It is not possible to chain finders before the browse call.
+
+Finally, like has_finder, has_browser is compatible with will_paginate out of the box.
+
+== Releases & Development
+
+has_browser will be released as a gem:
+  
+  $ sudo gem install has_browser
+  
+development will continue at {github}[http://github.com/giraffesoft/has_browser]
+
+== Credits & License
+
+Copyright (c) 2008 {James Golick}[http://jamesgolick.com], {GiraffeSoft Inc.}[http://giraffesoft.ca], released under the {MIT License}[http://en.wikipedia.org/wiki/MIT_License]

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/clean'
+require 'lib/has_browser'
+require 'lib/has_browser/version'
+
+Dir['tasks/**/*.rake'].each { |rake| load rake }

data/init.rb

@@ -0,0 +1,4 @@
+ActiveRecord::Base.send(:include, HasBrowser)
+[ActiveRecord::Associations::HasManyAssociation, ActiveRecord::Associations::HasManyThroughAssociation].each do |c|
+  c.send(:include, HasBrowser::AssociationProxyMethods)
+end

data/lib/has_browser/version.rb

@@ -0,0 +1,11 @@
+module HasBrowser
+  module Version
+    MAJOR    = 0
+    MINOR    = 0
+    TINY     = 1
+
+    STRING   = [MAJOR, MINOR, TINY].join('.')
+    
+    CODENAME = 'None'
+  end
+end

data/lib/has_browser.rb

@@ -0,0 +1,45 @@
+module HasBrowser
+  NAME = 'has_browser'
+  
+  class InvalidFinder < ArgumentError; end
+  
+  def self.included(receiver)
+    receiver.send :extend, ClassMethods
+  end
+  
+  module ClassMethods
+    def has_browser(*args)
+      extend BrowserMethods
+      class_inheritable_accessor  :has_browser_allowed_finders
+      self.has_browser_allowed_finders = {}
+      
+      has_browser_allowed_finders[:without_args] = args.extract_options![:without_args] || []
+      has_browser_allowed_finders[:with_args]    = args
+    end
+  end
+  
+  module BrowserMethods
+    def browse(*args)
+      params = args.extract_options!.symbolize_keys
+      
+      invalid_finders = params.keys.reject { |k| has_browser_allowed_finders.values.inject(&:+).include?(k) }
+      raise InvalidFinder.new(invalid_finders.join(', ').to_s) unless invalid_finders.empty?
+      
+      params.inject(args.first || self) do |proxy, finder|
+        has_browser_allowed_finders[:with_args].include?(finder.first.to_sym) ? proxy.send(finder.first, finder.last) : proxy.send(finder.first)
+      end
+    end
+  end
+  
+  module AssociationProxyMethods
+    def self.included(receiver)
+      receiver.class_eval do
+        alias_method_chain :method_missing, :has_browser
+      end
+    end
+    
+    def method_missing_with_has_browser(method, *args, &block)
+      method == :browse && proxy_reflection.klass.respond_to?(:has_browser_allowed_finders) ? proxy_reflection.klass.browse(self, args.extract_options!) : method_missing_without_has_browser(method, *args, &block)
+    end
+  end
+end

data/tasks/gem.rake

@@ -0,0 +1,55 @@
+require 'rake/gempackagetask'
+
+task :clean => :clobber_package
+
+spec = Gem::Specification.new do |s|
+  s.name                  = HasBrowser::NAME
+  s.version               = HasBrowser::Version::STRING
+  s.platform              = Gem::Platform::RUBY
+  s.summary               = 
+  s.description           = "has_browser makes it possible to create simple, parameterized browser interfaces to your models."
+  s.author                = "James Golick"
+  s.email                 = 'james@giraffesoft.ca'
+  s.homepage              = 'http://jamesgolick.com/'
+  
+  s.required_ruby_version = '>= 1.8.6'
+
+  s.files                 = %w(MIT-LICENSE README Rakefile init.rb) +
+                            Dir.glob("{lib,test,tasks}/**/*")
+                              
+  s.require_path          = "lib"
+end
+
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+end
+
+task :tag_warn do
+  puts "*" * 40
+  puts "Don't forget to tag the release:"
+  puts "  git tag -a v#{HasBrowser::Version::STRING}"
+  puts "*" * 40
+end
+task :gem => :tag_warn
+
+task :compile do
+end
+
+namespace :gem do
+  namespace :upload do
+    desc 'Upload gems to rubyforge.org'
+    task :rubyforge => :gem do
+      sh 'rubyforge login'
+      sh "rubyforge add_release giraffesoft has_browser #{HasBrowser::Version::STRING} pkg/#{spec.full_name}.gem"
+      sh "rubyforge add_file giraffesoft has_browser #{HasBrowser::Version::STRING} pkg/#{spec.full_name}.gem"
+    end
+  end
+end
+
+task :install => [:clobber, :compile, :package] do
+  sh "sudo gem install pkg/#{spec.full_name}.gem"
+end
+
+task :uninstall => :clobber do
+  sh "sudo gem uninstall #{spec.name}"
+end

data/tasks/test.rake

@@ -0,0 +1,8 @@
+task :default => [:test]
+
+desc "Run basic tests"
+Rake::TestTask.new("test") { |t|
+  t.pattern = 'test/*_test.rb'
+  t.verbose = true
+  t.warning = true
+}

data/test/has_browser_test.rb

@@ -0,0 +1,51 @@
+require File.dirname(__FILE__)+'/test_helper'
+
+class HasBrowserTest < Test::Unit::TestCase
+  def test_should_call_appropriate_finders_when_somebody_browses_by_parameters
+    PhotoMock.expects(:title).with('something').returns(PhotoMock)
+    PhotoMock.expects(:description).with('lorem ipsum dolor').returns(PhotoMock)
+    PhotoMock.expects(:order_by_date).returns(PhotoMock)
+    
+    PhotoMock.browse(:title => 'something', :description => 'lorem ipsum dolor', :order_by_date => 'true')
+  end
+  
+  def test_browsing_with_an_alternate_target
+    proxy_mock = mock
+    proxy_mock.expects(:title).with('something').returns(proxy_mock)
+    proxy_mock.expects(:description).with('lorem ipsum dolor').returns(proxy_mock)
+    proxy_mock.expects(:order_by_date).returns(proxy_mock)
+    
+    PhotoMock.browse(proxy_mock, :title => 'something', :description => 'lorem ipsum dolor', :order_by_date => 'true')
+  end
+  
+  def test_association_proxy_finder_should_proxy_to_the_reflected_class_browse_method
+    proxy_mock = AssocProxyMock.new
+    proxy_mock.stubs(:proxy_reflection).returns(stub(:klass => PhotoMock))
+    
+    PhotoMock.expects(:browse).with(proxy_mock, :title => 'something', :description => 'lorem ipsum dolor', :order_by_date => 'true')
+    
+    proxy_mock.browse(:title => 'something', :description => 'lorem ipsum dolor', :order_by_date => 'true')
+  end
+  
+  def test_association_proxy_should_raise_if_browse_is_called_and_target_doesnt_have_a_browser
+    proxy_mock = AssocProxyMock.new
+    proxy_mock.stubs(:proxy_reflection).returns(stub(:klass => String))
+    
+    assert_raise(NoMethodError) do
+      proxy_mock.browse({})
+    end
+  end
+  
+  def test_should_not_raise_when_keys_are_strings
+    PhotoMock.stubs(:title)
+    assert_nothing_raised do
+      PhotoMock.browse('title' => 'asdf')
+    end
+  end
+  
+  def test_should_raise_invalid_finder_exception_if_somebody_tries_to_browse_by_a_finder_not_specified_in_the_browse_call
+    assert_raise(HasBrowser::InvalidFinder) do
+      PhotoMock.browse(:invalid => 'danger!')
+    end
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,15 @@
+require "rubygems"
+require "mocha"
+require "activesupport"
+require "test/unit"
+require File.dirname(__FILE__)+"/../lib/has_browser"
+
+class PhotoMock
+  include HasBrowser
+  
+  has_browser :title, :description, :without_args => [:order_by_date, :order_by_relevance]
+end
+
+class AssocProxyMock
+  include HasBrowser::AssociationProxyMethods
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: has_browser
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- James Golick
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-05-19 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: has_browser makes it possible to create simple, parameterized browser interfaces to your models.
+email: james@giraffesoft.ca
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- MIT-LICENSE
+- README
+- Rakefile
+- init.rb
+- lib/has_browser
+- lib/has_browser/version.rb
+- lib/has_browser.rb
+- test/has_browser_test.rb
+- test/test_helper.rb
+- tasks/gem.rake
+- tasks/test.rake
+has_rdoc: false
+homepage: http://jamesgolick.com/
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.6
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.1.1
+signing_key: 
+specification_version: 2
+summary: has_browser makes it possible to create simple, parameterized browser interfaces to your models.
+test_files: []
+