thorero-slices 0.9.4

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Fabien Franzen <info@loobmedia.com>
+
+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,102 @@
+Merb-Slices
+===========
+
+Merb-Slices is a Merb plugin for using and creating application 'slices' which
+help you modularize your application. Usually these are reuseable extractions
+from your main app. In effect, a Slice is just like a regular Merb MVC
+application, both in functionality as well as in structure.
+
+When you generate a Slice stub structure, a module is setup to serve as a
+namespace for your controller, models, helpers etc. This ensures maximum
+encapsulation. You could say a Slice is a mixture between a Merb plugin (a
+Gem) and a Merb application, reaping the benefits of both.
+
+A host application can 'mount' a Slice inside the router, which means you have
+full over control how it integrates. By default a Slice's routes are prefixed
+by its name (a router :namespace), but you can easily provide your own prefix
+or leave it out, mounting it at the root of your url-schema. You can even
+mount a Slice multiple times and give extra parameters to customize an
+instance's behaviour.
+
+A Slice's Application controller uses controller_for_slice to setup slice
+specific behaviour, which mainly affects cascaded view handling. Additionaly,
+this method is available to any kind of controller, so it can be used for
+Merb Mailer too for example.
+
+There are many ways which let you customize a Slice's functionality and
+appearance without ever touching the Gem-level code itself. It's not only easy
+to add template/layout overrides, you can also add/modify controllers, models
+and other runtime code from within the host application.
+
+To create your own Slice run this (somewhere outside of your merb app):
+
+$ merb-gen slice <your-lowercase-slice-name>
+
+------------------------------------------------------------------------------
+
+Instructions for installation of an imaginary 'BlogSlice' slice:
+
+file: config/init.rb
+
+# add the slice as a regular dependency
+
+dependency 'blog-slice'
+
+# if needed, configure which slices to load and in which order
+
+Merb::Plugins.config[:merb_slices] = { :queue => ["BlogSlice", ...] }
+
+# optionally configure the plugins in a before_app_loads callback
+
+Merb::BootLoader.before_app_loads do
+  
+  Merb::Slices::config[:blog_slice] = { ... }
+  
+end
+
+file: config/router.rb
+
+# example: /blog-slice/:controller/:action/:id
+
+r.add_slice(:BlogSlice)
+
+# example: /foo/:controller/:action/:id
+
+r.add_slice(:BlogSlice, 'foo') # same as :path => 'foo'
+
+# example: /:lang/:controller/:action/:id (with :a param set)
+
+r.add_slice(:BlogSlice, :path => ':lang', :params => { :a => 'b' })
+
+# example: /:controller/:action/:id
+
+r.slice(:BlogSlice)
+
+Normally you should also run the following rake task:
+
+rake slices:blog_slice:install
+
+------------------------------------------------------------------------------
+
+You can put your application-level overrides in:
+
+host-app/slices/blog-slice/app - controllers, models, views ...
+
+Templates are located in this order:
+
+1. host-app/slices/blog-slice/app/views/*
+2. gems/blog-slice/app/views/*
+3. host-app/app/views/*
+
+You can use the host application's layout by configuring the
+blog-slice slice in a before_app_loads block:
+
+Merb::Slices.config[:blog_slice] = { :layout => :application }
+
+By default :blog_slice is used. If you need to override
+stylesheets or javascripts, just specify your own files in your layout
+instead/in addition to the ones supplied (if any) in 
+host-app/public/slices/blog-slice.
+
+In any case don't edit those files directly as they may be clobbered any time
+rake blog_slice:install is run.

data/Rakefile

@@ -0,0 +1,65 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require "extlib"
+require 'merb-core/tasks/merb_rake_helper'
+require "spec/rake/spectask"
+
+##############################################################################
+# Package && release
+##############################################################################
+RUBY_FORGE_PROJECT  = "thorero"
+PROJECT_URL         = "http://merbivore.com"
+PROJECT_SUMMARY     = "Merb-Slices is a Merb plugin for using and creating application 'slices' which help you modularize your application."
+PROJECT_DESCRIPTION = PROJECT_SUMMARY
+
+GEM_AUTHOR = "Fabien Franzen"
+GEM_EMAIL  = "info@fabien.be"
+
+GEM_NAME    = "thorero-slices"
+PKG_BUILD   = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
+GEM_VERSION = (Merb::MORE_VERSION rescue "0.9.4") + PKG_BUILD
+
+RELEASE_NAME    = "REL #{GEM_VERSION}"
+
+require "extlib/tasks/release"
+
+spec = Gem::Specification.new do |s|
+  s.rubyforge_project = RUBY_FORGE_PROJECT
+  s.name = GEM_NAME
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = ["README", "LICENSE", 'TODO']
+  s.summary = PROJECT_SUMMARY
+  s.description = PROJECT_DESCRIPTION
+  s.author = GEM_AUTHOR
+  s.email = GEM_EMAIL
+  s.homepage = PROJECT_URL
+  s.add_dependency('merb-core', '>= 0.9.4')
+  s.require_path = 'lib'
+  s.files = %w(LICENSE README Rakefile TODO) + Dir.glob("{lib,spec,merb_generators}/**/*")
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "Install the gem"
+task :install => [:package] do
+  sh %{#{sudo} gem install #{install_home} pkg/#{GEM_NAME}-#{GEM_VERSION} --no-update-sources}
+end
+
+namespace :jruby do
+
+  desc "Run :package and install the resulting .gem with jruby"
+  task :install => :package do
+    sh %{#{sudo} jruby -S gem install #{install_home} pkg/#{GEM_NAME}-#{GEM_VERSION}.gem --no-rdoc --no-ri}
+  end
+
+end
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new("specs") do |t|
+  t.spec_opts = ["--format", "specdoc", "--colour"]
+  t.spec_files = Dir["spec/**/*_spec.rb"].sort
+end

data/lib/merb-slices.rb

@@ -0,0 +1,126 @@
+require 'merb-slices/module'
+
+if defined?(Merb::Plugins)
+  
+  Merb::Plugins.add_rakefiles "merb-slices/merbtasks"
+  
+  Merb::Plugins.config[:merb_slices] ||= {}
+  
+  require "merb-slices/module_mixin"
+  require "merb-slices/controller_mixin"
+  require "merb-slices/router_ext"
+  
+  # Enable slice behaviour for any class inheriting from AbstractController.
+  # To use this call controller_for_slice in your controller class.
+  Merb::AbstractController.send(:include, Merb::Slices::ControllerMixin)
+  
+  # Load Slice classes before the app's classes are loaded.
+  #
+  # This allows the application to override/merge any slice-level classes.
+  class Merb::Slices::Loader < Merb::BootLoader
+
+    before LoadClasses
+
+    class << self
+
+      # Gather all slices from search path and gems and load their classes.
+      def run
+        Merb::Slices.register_slices_from_search_path! if auto_register?
+        Merb::Slices.each_slice { |slice| slice.load_slice }
+      end
+      
+      # Load a single file and its requirements.
+      #
+      # @param file<String> The file to load.
+      def load_file(file)
+        Merb::BootLoader::LoadClasses.load_file file
+      end
+      
+      # Remove a single file and the classes loaded by it from ObjectSpace.
+      #
+      # @param file<String> The file to load.
+      def remove_file(file)
+        Merb::BootLoader::LoadClasses.remove_file file
+      end
+        
+      # Load classes from given paths - using path/glob pattern.
+      #
+      # @param *paths <Array> Array of paths to load classes from - may contain glob pattern
+      def load_classes(*paths)
+        Merb::BootLoader::LoadClasses.load_classes paths
+      end
+    
+      # Reload the router - takes all_slices into account to load slices at runtime.
+      def reload_router!
+        Merb::BootLoader::LoadClasses.reload_router!
+      end
+      
+      # Slice-level paths for all loaded slices.
+      #
+      # @return <Array[String]> Any slice-level paths that have been loaded.
+      def slice_paths
+        paths = []
+        Merb::Slices.each_slice { |slice| paths += slice.collected_slice_paths }
+        paths
+      end
+      
+      # App-level paths for all loaded slices.
+      #
+      # @return <Array[String]> Any app-level paths that have been loaded.
+      def app_paths
+        paths = []
+        Merb::Slices.each_slice { |slice| paths += slice.collected_app_paths }
+        paths
+      end
+      
+      private
+      
+      # Whether slices from search paths should be registered automatically.
+      # Defaults to true if not explicitly set.
+      def auto_register?
+        Merb::Plugins.config[:merb_slices][:auto_register] || !Merb::Plugins.config[:merb_slices].key?(:auto_register)
+      end
+      
+    end
+
+  end
+  
+  # Call initialization method for each registered Slice.
+  #
+  # This is done just before the app's after_load_callbacks are run.
+  # The application has been practically loaded completely, letting
+  # the callbacks work with what has been loaded.
+  class Merb::Slices::Initialize < Merb::BootLoader
+  
+    before AfterAppLoads
+  
+    def self.run
+      Merb::Slices.each_slice do |slice|
+        Merb.logger.info!("Initializing slice '#{slice}' ...") 
+        slice.init if slice.respond_to?(:init)
+      end
+    end
+  
+  end
+  
+  # Call activation method for each registered Slice.
+  #
+  # This is done right after the app's after_load_callbacks are run.
+  # Any settings can be taken into account in the activation step.
+  #
+  # @note Activation will only take place if the slice has been routed;
+  #   this means you need have at least one slice route setup.
+  class Merb::Slices::Activate < Merb::BootLoader
+  
+    after AfterAppLoads
+  
+    def self.run
+      Merb::Slices.each_slice do |slice|
+        Merb.logger.info!("Activating slice '#{slice}' ...")
+        slice.activate if slice.respond_to?(:activate) && slice.routed?
+      end
+    end
+  
+  end
+  
+end

data/lib/merb-slices/controller_mixin.rb

@@ -0,0 +1,129 @@
+module Merb
+  module Slices
+    
+    module ControllerMixin
+      
+      def self.included(klass)
+        klass.extend ClassMethods
+      end
+      
+      module ClassMethods
+        
+        # Setup a controller to reference a slice and its template roots
+        #
+        # This method is available to any class inheriting from Merb::AbstractController;
+        # it enabled correct location of templates, as well as access to the slice module.
+        #
+        # @param slice_module<#to_s> The slice module to use; defaults to current module.
+        # @param options<Hash> 
+        #   Optional parameters to set which component path is used (defaults to :view) and
+        #   the :path option lets you specify a subdirectory of that component path.
+        #   When :layout is set, then this is used instead of the config's :layout setting.
+        #
+        # @example controller_for_slice # uses current module
+        # @example controller_for_slice SliceMod # defaults to :view templates and no subdirectory
+        # @example controller_for_slice :templates_for => :mailer, :path => 'views' # for Merb::Mailer
+        # @example controller_for_slice SliceMod, :templates_for => :mailer, :path => 'views' # for Merb::Mailer
+        def controller_for_slice(slice_module = nil, options = {})
+          options, slice_module = slice_module.merge(options), nil if slice_module.is_a?(Hash)
+          slice_module ||= self.name.split('::').first
+          options[:templates_for] = :view unless options.key?(:templates_for)
+          if slice_mod = Merb::Slices[slice_module.to_s]
+            # Include the instance methods
+            unless self.kind_of?(Merb::Slices::ControllerMixin::MixinMethods)
+              self.send(:extend, Merb::Slices::ControllerMixin::MixinMethods)
+            end
+            # Reference this controller's slice module
+            self.class_inheritable_accessor :slice
+            self.slice = slice_mod
+            # Setup template roots
+            if options[:templates_for]
+              self._template_root  = join_template_path(slice_mod.dir_for(options[:templates_for]), options[:path])
+              self._template_roots = []
+              # app-level app/views directory for shared and fallback views, layouts and partials
+              self._template_roots << [join_template_path(Merb.dir_for(options[:templates_for]), options[:path]), :_template_location] if Merb.dir_for(options[:templates_for])
+              # slice-level app/views for the standard supplied views
+              self._template_roots << [self._template_root, :_slice_template_location] 
+              # app-level slices/<slice>/app/views for specific overrides
+              self._template_roots << [join_template_path(slice_mod.app_dir_for(options[:templates_for]), options[:path]), :_slice_template_location]
+              # additional template roots for specific overrides (optional)
+              self._template_roots += Array(options[:template_roots]) if options[:template_roots]
+            end
+            # Set the layout for this slice controller
+            layout_for_slice(options[:layout])
+          end
+        end
+        
+        private
+        
+        def join_template_path(*segments)
+          File.join(*segments.compact)
+        end
+        
+      end
+      
+      module MixinMethods
+        
+        def self.extended(klass)
+          klass.send(:include, InstanceMethods)
+          klass.hide_action :slice
+        end
+        
+        # Use the slice's layout - defaults to underscored identifier.
+        #
+        # This is set for generated stubs that support layouts.
+        #
+        # @param layout<#to_s> The layout name to use.
+        def layout_for_slice(layout = nil)
+          layout(layout || self.slice.config[:layout]) if layout || self.slice.config.key?(:layout)
+        end
+        
+        module InstanceMethods
+      
+          # Reference this controller's slice module directly.
+          #
+          # @return <Module> A slice module.
+          def slice; self.class.slice; end
+          
+          # Generate a url - takes the slice's :path_prefix into account.
+          def slice_url(name, rparams={})
+            self.slice.url(name, rparams, { 
+              :controller => controller_name,
+              :action => action_name,
+              :format => params[:format]
+            })
+          end
+
+          private
+  
+          # This is called after the controller is instantiated to figure out where to
+          # for templates under the _template_root. This helps the controllers
+          # of a slice to locate templates without looking in a subdirectory with
+          # the name of the module. Instead it will just be app/views/controller/*
+          #
+          # @param context<#to_str> The controller context (the action or template name).
+          # @param type<#to_str> The content type. Defaults to nil.
+          # @param controller<#to_str> The name of the controller. Defaults to controller_name.
+          #
+          # @return <String> 
+          #   Indicating where to look for the template for the current controller,
+          #   context, and content-type.
+          def _slice_template_location(context, type = nil, controller = controller_name)
+            if controller && controller.include?('/')
+              # skip first segment if given (which is the module name)
+              segments = controller.split('/')
+              "#{segments[1,segments.length-1].join('/')}/#{context}.#{type}"
+            else
+              # default template location logic
+              _template_location(context, type, controller)
+            end
+          end
+          
+        end
+      
+      end
+
+    end
+    
+  end
+end