snusnu-merb_resource_controller 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Martin Gamsjaeger
+
+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.textile

@@ -0,0 +1,306 @@
+h2. merb_resource_controller
+
+A merb plugin that provides the default @CRUD@ actions for controllers and allows for easy customization
+of the generated actions. @merb_resource_controller@ only supports @datamapper@ so far. Implementing support
+for @active_record@ would be trivial, but I have no need for it.
+
+Currently, @merb_resource_controller@ needs an extra specification inside the controller to define the nesting strategy
+to use. This shouldn't really be necessary, since this information could be provided by the @Merb::Router@.
+I'm planning to have a look into this soon! With that in place, nested resource_controllers could be _3 liners_ 
+that just do what you would expect them to do.
+
+To get you started with @merb_resource_controller@, all you have to do is extend it into your controller.
+Most probably you will want extend it into the @Application@ controller, which will make the @controlling@
+method available to all your application's controllers.
+
+<pre>
+<code>
+class Application < Merb::Controller
+  extend Merb::ResourceController::Mixin::ClassMethods
+end
+</code>
+</pre>
+
+And here is a quick example showing a controller for a standard toplevel resource with all standard @CRUD@ actions.
+
+<pre>
+<code>
+class Articles < Application
+  controlling :articles
+end
+</code>
+</pre>
+
+If you don't want all standard @CRUD@ actions to be generated, give @merb_resource_controller@ the exact list
+of actions you want your controller to have.
+
+<pre>
+<code>
+class Articles < Application
+  controlling :articles do |a|
+    a.action :create
+    a.action :update
+  end
+end
+</code>
+</pre>
+
+Alternatively, you can also add more than one action at once using the @actions@ method available on the @ResourceProxy@
+
+<pre>
+<code>
+class Articles < Application
+  controlling :articles do |a|
+    a.actions :create, :update
+  end
+end
+</code>
+</pre>
+
+
+If you are using models that are nested inside some @module@ (maybe you're developing a @slice@ ?), you need to 
+provide the fully qualified class name to the @controlling@ method. Per default, @merb_resource_controller@ assumes 
+that you don't want to use the fully qualified name to generate your instance variables and association calls.
+
+<pre>
+<code>
+class Ratings < Application
+  controlling "Community::Rating"
+end
+</code>
+</pre>
+
+This will initialize the instance variable @@ratings@ (or @@rating@ respectively). If this resource is nested below 
+another resource (see next section), this also means that the @:ratings@ (or @:rating@ respectively) association will
+be used to navigate from the parent resource down to this resource.
+
+If however, you want to use fully qualified names for your instance variables and association calls, you can explicitly
+pass @:fully_qualified => true@ to the @controlling@ method (@false@ is the default).
+
+<pre>
+<code>
+class Ratings < Application
+  controlling "Community::Rating", :fully_qualified => true
+end
+</code>
+</pre>
+
+This will initialize the instance variable @@community_ratings@ (or @@community_rating@ respectively). If this resource
+is nested below another resource (see next section), this also means that the @:community_ratings@ (or 
+@:community_rating@ respectively) association will be used to navigate from the parent resource down to this resource.
+
+h2. Nested Resources
+
+@merb_resource_controller@ will automatically recognize if it is accessed from a toplevel or a nested url, and
+will _adjust_ its actions accordingly. It will also initialize all the instance variables
+you would expect for your chosen nesting strategy. This means, that when you have an URL like
+@/articles/1/comments@, you will have an @@article@ variable pointing to @Article.get(1)@ and a @@comments@ variable
+pointing to @Article.get(1).comments@.
+
+It's important to note, that no database operations will be performed more than once!
+So in the case of @/articles/1/comments/1/ratings@, @merb_resource_controller@ will do exactly what you would
+expect it to do: It will issue @Article.get(1).comments.get(1).ratings@, initializing 
+@@article@, @@comment@ and @@ratings@ with the intermediate results on it's way down the association chain.
+
+Speaking of an _association chain_, it is worth mentioning that it is by no means necessary that your 
+underlying models are connected via _real datamapper associations_ (like @has n, ...@ or @belongs_to@). 
+The only requirement is, that the object returned from a call to the nested _collection_ @respond_to?(:get)@ 
+(in most cases it will be a @DataMapper::Collection@ anyway).
+
+
+<pre>
+</code>
+class Comments < Application
+  controlling :comments do |c|
+    c.belongs_to :article
+  end
+end
+
+class Ratings < Application
+  controlling :ratings do |r|
+    r.belongs_to [ :article, :comment ]
+  end
+end
+</code>
+</pre>
+
+h2. Nested Singleton Resources
+
+First of all, singleton resources (currently) must always be nested below at least one parent resource. 
+
+This is mostly because I somehow can't really imagine a usecase for a real toplevel singleton resource? I mean, there 
+must be  _some_ information on _how_ to load that _one_ resource. Since we're mostly dealing with database backends here,
+we should probably need some kind of _key_ to identify exactly _one_ dataset, but we don't get that _key_ from a resource 
+like  @/profile@ (_where_ is the @:id@ param here?). So my guess is, that most of the toplevel singleton resources that
+_are_ actually used, really are nested below some kind of resource that's stored in the @session@, most probably the
+authenticated @user@ object. If this is the case, it would be perfectly valid, to just _really nest_ those singletons 
+below their real parent, and probably add a route alias to keep up the disguise. If you can come up with a usecase
+where you have a real toplevel singleton resource that needs _no key_ to be loaded, just don't use
+@merb_resource_controller@. Really, it's that simple! If however, I'm completely on the wrong track here, I would be glad
+to be informed about it, so that I can fix things up.
+
+The example code below behaves almost exactly like described in the section on _Nested Resources_ above. The only
+two differences are, that 1) @no index action@ will be generated and that 2) the initialized instance variables will be
+named @@article@ and @@editor@ if you have a singleton resource nested like @/articles/1/editor@. Just like you would 
+expect, no?
+
+<pre>
+<code>
+class Editors < Application
+
+  controlling :editor, :singleton => true do |e|
+    e.belongs_to :article
+  end
+
+end
+</code>
+</pre>
+
+h2. DataMapper's Identity Map
+
+Including @Merb::ResourceController::DM::IdentityMapSupport@ into any of your controller will wrap all actions 
+inside a dm repository block in order to be able to use DM's identitiy map feature. For more information on that topic,
+have a look at "DataMapper's Identity Map":http://datamapper.org/doku.php?id=docs:identity_map
+
+Feel free to include this module into _single_ controllers instead of including it into @Application@ controller, which
+enables identity maps for _every_ controller action in your app.
+
+<pre>
+<code>
+class Application < Merb::Controller  
+  include Merb::ResourceController::DM::IdentityMapSupport
+end
+</code>
+</pre>
+
+h2. Action Timeouts
+
+Extending @Merb::ResourceController::ActionTimeout@  into any of your controllers, will give you the @set_action_timeout@
+method. If you specify an action_timeout greater or equal to @1@ and you have the @system_timer@ gem installed, the 
+action will timeout after the given amount of seconds. For a more detailed explanation on the topic have a look at
+"Battling Wedged Mongrels with a Request Timeout":http://adam.blog.heroku.com/past/2008/6/17/battling_wedged_mongrels_with_a/
+
+Feel free to set action timeouts for _single_ controllers instead of doing so in @Application@ controller, which sets 
+the same action timeout for _every_ controller action in your app.
+
+<pre>
+<code>
+class Application < Merb::Controller
+  extend Merb::ResourceController::ActionTimeout  
+  set_action_timeout 1
+end
+</code>
+</pre>
+
+h2. Defined Actions
+
+All the above controllers will have the following actions defined. Feel free to override them, to customize 
+how the controllers behave. Of course you are also free to override all the methods used by these defined actions.
+
+<pre>
+<code>  
+def index
+  load_resource
+  display requested_resource
+end
+
+def show
+  load_resource
+  raise Merb::ControllerExceptions::NotFound unless requested_resource
+  display requested_resource
+end
+
+def new
+  only_provides :html
+  load_resource
+  set_member(new_member)
+  display member
+end
+
+def edit
+  only_provides :html
+  load_resource
+  raise Merb::ControllerExceptions::NotFound unless requested_resource
+  display requested_resource
+end
+
+def create
+  load_resource
+  set_member(new_member(params[member_name]))
+  if member.save
+    options = flash_supported? ? { :message => successful_create_messages } : {}
+    redirect redirect_on_successful_create, options
+  else
+    message.merge!(failed_create_messages) if flash_supported?
+    render :new
+  end
+end
+
+def update
+  load_resource
+  raise Merb::ControllerExceptions::NotFound unless requested_resource
+  if requested_resource.update_attributes(params[member_name])
+    options = flash_supported? ? { :message => successful_update_messages } : {}
+    redirect redirect_on_successful_update, options
+  else
+    message.merge!(failed_update_messages) if flash_supported?
+    display requested_resource, :edit
+  end
+end
+
+def destroy
+  load_resource
+  raise Merb::ControllerExceptions::NotFound unless requested_resource
+  if requested_resource.destroy
+    options = flash_supported? ? { :message => successful_destroy_messages } : {}
+    redirect redirect_on_successful_destroy, options
+  else
+    raise Merb::ControllerExceptions::InternalServerError
+  end
+end
+</code>
+</pre>
+
+h2. Additional Helper Methods
+
+In addition to the actions and the methods they are using, you will probably want to override the redirection targets
+These are the default method implementations you can override to this effect:
+
+<pre>
+<code>
+def redirect_on_successful_create
+  target = singleton_controller? ? member_name : member
+  resource(*(has_parent? ? parents + [ target ] : [ target ]))
+end
+
+def redirect_on_successful_update
+  target = singleton_controller? ? member_name : member
+  resource(*(has_parent? ? parents + [ target ] : [ target ]))
+end
+
+def redirect_on_successful_destroy
+  if singleton_controller?
+    has_parent? ? resource(parent) : '/'
+  else
+    resource(*(has_parent? ? parents + [ collection_name ] : [ collection_name ]))
+  end
+end
+</code>
+</pre>
+
+h2. More Information
+
+Have a look at @Merb::ResourceController::Actions@, @Merb::ResourceController::Mixin::InstanceMethods@ and 
+@Merb::ResourceController::Mixin::FlashSupport@ inside @lib/merb_resource_controller/actions.rb@ and 
+@lib/merb_resource_controller/resource_controller.rb@ to see what methods will be available inside your controllers.
+If you want to see where the _real work gets done_, have a look at @lib/merb_resource_controller/resource_proxy.rb@
+
+Of course, you should also have a look at the specs, to get a more concrete idea of how @merb_resource_controller@
+behaves under the given circumstances.
+
+h2. TODO
+
+# Infer route nesting strategy from @Merb::Router@
+# Customizable support for @provides@ and @only_provides@
+# Support for user stamps (aka created_by and updated_by)
+# Support for pagination once an _official_ merb pagination solution exists

data/Rakefile

@@ -0,0 +1,81 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+
+require 'merb-core'
+require 'merb-core/tasks/merb'
+require "spec/rake/spectask"
+
+GEM_NAME = "merb_resource_controller"
+GEM_VERSION = "0.1.0"
+AUTHOR = "Martin Gamsjaeger"
+EMAIL = "gamsnjaga@gmail.com"
+HOMEPAGE = "http://merbivore.com/"
+SUMMARY = "A merb plugin that provides the default restful actions for controllers."
+
+spec = Gem::Specification.new do |s|
+  
+  s.rubyforge_project = 'merb_resource_controller'
+  s.name = GEM_NAME
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = false
+  s.extra_rdoc_files = [ "LICENSE", 'TODO']
+  s.summary = SUMMARY
+  s.description = s.summary
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+  s.require_path = 'lib'
+  
+  # be extra picky so that no coverage info and such gets included
+  s.files = %w(LICENSE README.textile Rakefile TODO) + 
+    Dir.glob("{lib,spec}/**/*.rb") + 
+    Dir.glob("{spec}/**") + 
+    Dir.glob("{spec}/**/*.rb") + 
+    Dir.glob("{spec}/**/*.yml") +
+    Dir.glob("{spec}/**/*.opts") +
+    Dir.glob("{spec}/**/*.html.erb") +
+    [ "spec/mrc_test_app/Rakefile"]
+  
+  # runtime dependencies
+  s.add_dependency('merb-core', '~> 1.0')
+  
+  # development dependencies
+  # if these are desired, install with:
+  # gem install merb_resource_controller --development
+  s.add_development_dependency('merb-assets',    '~>1.0')
+  s.add_development_dependency('merb-helpers',   '~>1.0')
+  s.add_development_dependency('dm-core',        '~>0.9.8')
+  s.add_development_dependency('dm-validations', '~>0.9.8')
+  s.add_development_dependency('dm-serializer',  '~>0.9.8')
+  s.add_development_dependency('dm-constraints', '~>0.9.8')
+  
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "install the plugin as a gem"
+task :install do
+  Merb::RakeHelper.install(GEM_NAME, :version => GEM_VERSION)
+end
+
+desc "Uninstall the gem"
+task :uninstall do
+  Merb::RakeHelper.uninstall(GEM_NAME, :version => GEM_VERSION)
+end
+
+desc "Create a gemspec file"
+task :gemspec do
+  File.open("#{GEM_NAME}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end
+
+desc 'Default: run spec examples'
+task :spec do 
+  puts "!!! README !!! Run 'rake spec' from the './spec/mrc_test_app' directory to run all specs for merb_resource_controller."
+end
+
+task :default => 'spec'

data/TODO

@@ -0,0 +1,7 @@
+TODO
+====
+
+# Infer route nesting strategy from @Merb::Router@
+# Customizable support for @provides@ and @only_provides@
+# Support for user stamps (aka created_by and updated_by)
+# Support for pagination once an _official_ merb pagination solution exists

data/lib/merb_resource_controller/action_timeout_support.rb

@@ -0,0 +1,53 @@
+require 'system_timer'
+
+module Merb
+  module ResourceController
+      
+    # To be extended into controllers
+    module ActionTimeout
+      
+      def self.for?(controller)
+        self.for(controller) > 0
+      end
+      
+      def self.for(controller)
+        (@controllers ||= {})[Application] || @controllers[controller] || 0
+      end
+      
+      def self.register(controller, seconds)
+        (@controllers ||= {})[controller] = seconds
+      end
+      
+      
+      def set_action_timeout(seconds)
+        if seconds >= 1
+          ActionTimeout.register(self, seconds)
+          include InstanceMethods
+        end
+      end
+      
+      module InstanceMethods
+        
+        # taken from:
+        # http://datamapper.org/doku.php?id=docs:identity_map
+        def _call_action(*args)
+          if Merb::Plugins.config[:merb_resource_controller][:action_timeout]
+            return super unless ActionTimeout.for?(self.class)
+            timeout = ActionTimeout.for(self.class)
+            Merb.logger.info "SystemTimer.timeout for #{args[0]}: #{timeout} seconds"
+            # more information on system_timer:
+            # http://adam.blog.heroku.com/past/2008/6/17/battling_wedged_mongrels_with_a/
+            SystemTimer.timeout(timeout) do
+              super
+            end
+          else
+            super
+          end
+        end
+        
+      end
+      
+    end
+      
+  end
+end

data/lib/merb_resource_controller/actions.rb

@@ -0,0 +1,169 @@
+module Merb
+  module ResourceController
+    
+    module Actions
+
+      module Index
+        
+        # def index
+        #   @articles = Article.all
+        #   display @articles
+        # end
+        
+        def index
+          load_resource
+          display requested_resource
+        end
+        
+      end
+
+      module Show
+        
+        # def show(id)
+        #   @article = Article.get(id)
+        #   raise NotFound unless @article
+        #   display @article
+        # end
+        
+        def show
+          load_resource
+          raise Merb::ControllerExceptions::NotFound unless requested_resource
+          display requested_resource
+        end
+        
+      end
+
+      module New
+        
+        # def new
+        #   only_provides :html
+        #   @article = Article.new
+        #   display @article
+        # end
+        
+        def new
+          only_provides :html
+          load_resource
+          set_member(new_member)
+          display member
+        end
+        
+      end
+
+      module Edit
+        
+        # def edit(id)
+        #   only_provides :html
+        #   @article = Article.get(id)
+        #   raise NotFound unless @article
+        #   display @article
+        # end
+        
+        def edit
+          only_provides :html
+          load_resource
+          raise Merb::ControllerExceptions::NotFound unless requested_resource
+          display requested_resource
+        end
+        
+      end
+
+      module Create
+        
+        # def create(article)
+        #   @article = Article.new(article)
+        #   if @article.save
+        #     redirect resource(@article), :message => { :notice => "Article was successfully created" }
+        #   else
+        #     message[:error] = "Article failed to be created"
+        #     render :new
+        #   end
+        # end
+        
+        def create
+          load_resource
+          set_member(new_member)
+          if member.save
+            options = flash_supported? ? { :message => successful_create_messages } : {}
+            redirect redirect_on_successful_create, options
+          else
+            message.merge!(failed_create_messages) if flash_supported?
+            render :new, :status => 406
+          end
+        end
+        
+        def redirect_on_successful_create
+          target = singleton_controller? ? member_name : member
+          resource(*(has_parent? ? parents + [ target ] : [ target ]))
+        end
+        
+      end
+
+      module Update
+        
+        # def update(id, article)
+        #   @article = Article.get(id)
+        #   raise NotFound unless @article
+        #   if @article.update_attributes(article)
+        #      redirect resource(@article), :message => { :notice => "Article was successfully updated" }
+        #   else
+        #     display @article, :edit
+        #   end
+        # end
+        
+        def update
+          load_resource
+          raise Merb::ControllerExceptions::NotFound unless requested_resource
+          if requested_resource.update_attributes(params[member_name])
+            options = flash_supported? ? { :message => successful_update_messages } : {}
+            redirect redirect_on_successful_update, options
+          else
+            message.merge!(failed_update_messages) if flash_supported?
+            display requested_resource, :edit, :status => 406
+          end
+        end
+        
+        def redirect_on_successful_update
+          target = singleton_controller? ? member_name : member
+          resource(*(has_parent? ? parents + [ target ] : [ target ]))
+        end
+        
+      end
+
+      module Destroy
+        
+        # def destroy(id)
+        #   @article = Article.get(id)
+        #   raise NotFound unless @article
+        #   if @article.destroy
+        #     redirect resource(:articles)
+        #   else
+        #     raise InternalServerError
+        #   end
+        # end
+        
+        def destroy
+          load_resource
+          raise Merb::ControllerExceptions::NotFound unless requested_resource
+          if requested_resource.destroy
+            options = flash_supported? ? { :message => successful_destroy_messages } : {}
+            redirect redirect_on_successful_destroy, options
+          else
+            raise Merb::ControllerExceptions::InternalServerError
+          end
+        end
+        
+        def redirect_on_successful_destroy
+          if singleton_controller?
+            has_parent? ? resource(parent) : '/'
+          else
+            resource(*(has_parent? ? parents + [ collection_name ] : [ collection_name ]))
+          end
+        end
+        
+      end
+
+    end
+    
+  end
+end

data/lib/merb_resource_controller/identity_map_support.rb

@@ -0,0 +1,20 @@
+module Merb
+  module ResourceController
+    module DM
+      
+      # include this into controllers
+      module IdentityMapSupport
+        
+        # taken from:
+        # http://datamapper.org/doku.php?id=docs:identity_map
+        def _call_action(*)
+          repository do |r| # enable identity_map
+            Merb.logger.info "Using DM Identity map inside #{r.name} repository block"
+            super
+          end
+        end
+        
+      end
+    end
+  end
+end