reactive-mvc 0.2.0

data/lib/reactive-mvc/controller/flash.rb

@@ -0,0 +1,161 @@
+module Reactive::Mvc::Controller #:nodoc:
+  # The flash provides a way to pass temporary objects between actions. Anything you place in the flash will be exposed
+  # to the very next action and then cleared out. This is a great way of doing notices and alerts, such as a create
+  # action that sets <tt>flash[:notice] = "Successfully created"</tt> before redirecting to a display action that can
+  # then expose the flash to its template. Actually, that exposure is automatically done. Example:
+  #
+  #   class WeblogController < Reactive::Controller::Base
+  #     def create
+  #       # save post
+  #       flash[:notice] = "Successfully created post"
+  #       redirect_to :action => "display", :params => { :id => post.id }
+  #     end
+  #
+  #     def display
+  #       # doesn't need to assign the flash notice to the template, that's done automatically
+  #     end
+  #   end
+  #
+  #   display.erb
+  #     <% if flash[:notice] %><div class="notice"><%= flash[:notice] %></div><% end %>
+  #
+  # This example just places a string in the flash, but you can put any object in there. And of course, you can put as
+  # many as you like at a time too. Just remember: They'll be gone by the time the next action has been performed.
+  #
+  # See docs on the FlashHash class for more details about the flash.
+  module Flash
+    def self.included(base)
+      base.class_eval do
+        include InstanceMethods
+        alias_method_chain :assign_shortcuts, :flash
+        alias_method_chain :process_cleanup,  :flash
+      end
+    end
+    
+    
+    class FlashNow #:nodoc:
+      def initialize(flash)
+        @flash = flash
+      end
+      
+      def []=(k, v)
+        @flash[k] = v
+        @flash.discard(k)
+        v
+      end
+      
+      def [](k)
+        @flash[k]
+      end
+    end
+    
+    class FlashHash < Hash
+      def initialize #:nodoc:
+        super
+        @used = {}
+      end
+      
+      def []=(k, v) #:nodoc:
+        keep(k)
+        super
+      end
+      
+      def update(h) #:nodoc:
+        h.keys.each { |k| keep(k) }
+        super
+      end
+      
+      alias :merge! :update
+      
+      def replace(h) #:nodoc:
+        @used = {}
+        super
+      end
+    
+      # Sets a flash that will not be available to the next action, only to the current.
+      #
+      #     flash.now[:message] = "Hello current action"
+      # 
+      # This method enables you to use the flash as a central messaging system in your app.
+      # When you need to pass an object to the next action, you use the standard flash assign (<tt>[]=</tt>).
+      # When you need to pass an object to the current action, you use <tt>now</tt>, and your object will
+      # vanish when the current action is done.
+      #
+      # Entries set via <tt>now</tt> are accessed the same way as standard entries: <tt>flash['my-key']</tt>.
+      def now
+        FlashNow.new(self)
+      end
+    
+      # Keeps either the entire current flash or a specific flash entry available for the next action:
+      #
+      #    flash.keep            # keeps the entire flash
+      #    flash.keep(:notice)   # keeps only the "notice" entry, the rest of the flash is discarded
+      def keep(k = nil)
+        use(k, false)
+      end
+    
+      # Marks the entire flash or a single flash entry to be discarded by the end of the current action:
+      #
+      #     flash.discard              # discard the entire flash at the end of the current action
+      #     flash.discard(:warning)    # discard only the "warning" entry at the end of the current action
+      def discard(k = nil)
+        use(k)
+      end
+    
+      # Mark for removal entries that were kept, and delete unkept ones.
+      #
+      # This method is called automatically by filters, so you generally don't need to care about it.
+      def sweep #:nodoc:
+        keys.each do |k| 
+          unless @used[k]
+            use(k)
+          else
+            delete(k)
+            @used.delete(k)
+          end
+        end
+
+        # clean up after keys that could have been left over by calling reject! or shift on the flash
+        (@used.keys - keys).each{ |k| @used.delete(k) }
+      end
+    
+      private
+        # Used internally by the <tt>keep</tt> and <tt>discard</tt> methods
+        #     use()               # marks the entire flash as used
+        #     use('msg')          # marks the "msg" entry as used
+        #     use(nil, false)     # marks the entire flash as unused (keeps it around for one more action)
+        #     use('msg', false)   # marks the "msg" entry as unused (keeps it around for one more action)
+        def use(k=nil, v=true)
+          unless k.nil?
+            @used[k] = v
+          else
+            keys.each{ |key| use(key, v) }
+          end
+        end
+    end
+
+    module InstanceMethods #:nodoc:
+      protected
+        # Access the contents of the flash. Use <tt>flash["notice"]</tt> to read a notice you put there or 
+        # <tt>flash["notice"] = "hello"</tt> to put a new one.
+        # Note that if sessions are disabled only flash.now will work.
+        def flash(refresh = false) #:doc:
+          if !defined?(@_flash) || refresh
+            @_flash = FlashHash.new
+          end
+          @_flash
+        end
+
+      private
+        def assign_shortcuts_with_flash(request, response) #:nodoc:
+          assign_shortcuts_without_flash(request, response)
+          flash(:refresh)
+        end
+    
+        def process_cleanup_with_flash
+          flash.sweep if @_session
+          process_cleanup_without_flash
+        end
+    end
+  end
+end

data/lib/reactive-mvc/controller/helpers.rb

@@ -0,0 +1,203 @@
+# FIXME: helper { ... } is broken on Ruby 1.9
+module Reactive::Mvc::Controller #:nodoc:
+  module Helpers #:nodoc:
+
+    def self.included(base)
+      # Initialize the base module to aggregate its helpers.
+      base.class_inheritable_accessor :master_helper_module
+      base.master_helper_module = Module.new
+
+      # Extend base with class methods to declare helpers.
+      base.extend(ClassMethods)
+
+      base.class_eval do
+        # Wrap inherited to create a new master helper module for subclasses.
+        class << self
+          alias_method_chain :inherited, :helper
+        end
+      end
+    end
+
+    # The Rails framework provides a large number of helpers for working with +assets+, +dates+, +forms+, 
+    # +numbers+ and +ActiveRecord+ objects, to name a few. These helpers are available to all templates
+    # by default.
+    #
+    # In addition to using the standard template helpers provided in the Rails framework, creating custom helpers to
+    # extract complicated logic or reusable functionality is strongly encouraged.  By default, the controller will 
+    # include a helper whose name matches that of the controller, e.g., <tt>MyController</tt> will automatically
+    # include <tt>MyHelper</tt>.
+    # 
+    # Additional helpers can be specified using the +helper+ class method in <tt>ActionController::Base</tt> or any
+    # controller which inherits from it.
+    #
+    # ==== Examples
+    # The +to_s+ method from the +Time+ class can be wrapped in a helper method to display a custom message if 
+    # the Time object is blank:
+    #
+    #   module FormattedTimeHelper
+    #     def format_time(time, format=:long, blank_message="&nbsp;")
+    #       time.blank? ? blank_message : time.to_s(format)
+    #     end
+    #   end
+    #
+    # +FormattedTimeHelper+ can now be included in a controller, using the +helper+ class method:
+    #
+    #   class EventsController < ActionController::Base
+    #     helper FormattedTimeHelper
+    #     def index
+    #       @events = Event.find(:all)
+    #     end
+    #   end
+    #
+    # Then, in any view rendered by <tt>EventController</tt>, the <tt>format_time</tt> method can be called:
+    #
+    #   <% @events.each do |event| -%>
+    #     <p>
+    #       <% format_time(event.time, :short, "N/A") %> | <%= event.name %> 
+    #     </p>
+    #   <% end -%>
+    #
+    # Finally, assuming we have two event instances, one which has a time and one which does not, 
+    # the output might look like this:
+    #
+    #   23 Aug 11:30 | Carolina Railhawks Soccer Match 
+    #   N/A | Carolina Railhaws Training Workshop
+    #
+    module ClassMethods
+      # Makes all the (instance) methods in the helper module available to templates rendered through this controller.
+      # See ActionView::Helpers (link:classes/ActionView/Helpers.html) for more about making your own helper modules
+      # available to the templates.
+      def add_template_helper(helper_module) #:nodoc:
+        master_helper_module.module_eval { include helper_module }
+      end
+
+      # The +helper+ class method can take a series of helper module names, a block, or both.
+      #
+      # * <tt>*args</tt>: One or more +Modules+, +Strings+ or +Symbols+, or the special symbol <tt>:all</tt>.
+      # * <tt>&block</tt>: A block defining helper methods.
+      # 
+      # ==== Examples
+      # When the argument is a +String+ or +Symbol+, the method will provide the "_helper" suffix, require the file 
+      # and include the module in the template class.  The second form illustrates how to include custom helpers 
+      # when working with namespaced controllers, or other cases where the file containing the helper definition is not
+      # in one of Rails' standard load paths:
+      #   helper :foo             # => requires 'foo_helper' and includes FooHelper
+      #   helper 'resources/foo'  # => requires 'resources/foo_helper' and includes Resources::FooHelper
+      #
+      # When the argument is a +Module+, it will be included directly in the template class.
+      #   helper FooHelper # => includes FooHelper
+      #
+      # When the argument is the symbol <tt>:all</tt>, the controller will include all helpers from 
+      # <tt>app/helpers/**/*.rb</tt> under +RAILS_ROOT+.
+      #   helper :all
+      #
+      # Additionally, the +helper+ class method can receive and evaluate a block, making the methods defined available 
+      # to the template.
+      #   # One line
+      #   helper { def hello() "Hello, world!" end }
+      #   # Multi-line
+      #   helper do
+      #     def foo(bar) 
+      #       "#{bar} is the very best" 
+      #     end
+      #   end
+      # 
+      # Finally, all the above styles can be mixed together, and the +helper+ method can be invoked with a mix of
+      # +symbols+, +strings+, +modules+ and blocks.
+      #   helper(:three, BlindHelper) { def mice() 'mice' end }
+      #
+      def helper(*args, &block)
+        args.flatten.each do |arg|
+          case arg
+            when Module
+              add_template_helper(arg)
+            when :all
+              helper(all_application_helpers)
+            when String, Symbol
+              file_name  = arg.to_s.underscore + '_helper'
+              class_name = file_name.camelize
+
+              begin
+                require_dependency(file_name)
+              rescue LoadError => load_error
+                requiree = / -- (.*?)(\.rb)?$/.match(load_error.message).to_a[1]
+                if requiree == file_name
+                  msg = "Missing helper file helpers/#{file_name}.rb"
+                  raise LoadError.new(msg).copy_blame!(load_error)
+                else
+                  raise
+                end
+              end
+
+              add_template_helper(class_name.constantize)
+            else
+              raise ArgumentError, "helper expects String, Symbol, or Module argument (was: #{args.inspect})"
+          end
+        end
+
+        # Evaluate block in template class if given.
+        master_helper_module.module_eval(&block) if block_given?
+      end
+
+      # Declare a controller method as a helper. For example, the following
+      # makes the +current_user+ controller method available to the view:
+      #   class ApplicationController < ActionController::Base
+      #     helper_method :current_user
+      #     def current_user
+      #       @current_user ||= User.find(session[:user])
+      #     end
+      #   end
+      def helper_method(*methods)
+        methods.flatten.each do |method|
+          master_helper_module.module_eval <<-end_eval
+            def #{method}(*args, &block)
+              controller.send(%(#{method}), *args, &block)
+            end
+          end_eval
+        end
+      end
+
+      # Declares helper accessors for controller attributes. For example, the
+      # following adds new +name+ and <tt>name=</tt> instance methods to a
+      # controller and makes them available to the view:
+      #   helper_attr :name
+      #   attr_accessor :name
+      def helper_attr(*attrs)
+        attrs.flatten.each { |attr| helper_method(attr, "#{attr}=") }
+      end
+
+
+      private
+        def default_helper_module!
+          unless name.blank?
+            module_name = name.sub(/Controller$|$/, 'Helper')
+            module_path = module_name.split('::').map { |m| m.underscore }.join('/')
+            require_dependency module_path
+            helper module_name.constantize
+          end
+        rescue MissingSourceFile => e
+          raise unless e.is_missing? module_path
+        rescue NameError => e
+          raise unless e.missing_name? module_name
+        end
+
+        def inherited_with_helper(child)
+          inherited_without_helper(child)
+
+          begin
+            child.master_helper_module = Module.new
+            child.master_helper_module.send :include, master_helper_module
+            child.send :default_helper_module!
+          rescue MissingSourceFile => e
+            raise unless e.is_missing?("helpers/#{child.controller_path}_helper")
+          end
+        end
+
+        # Extract helper names from files in app/helpers/**/*.rb
+        def all_application_helpers
+          extract = /^#{Regexp.quote(Reactive.dir_for(:helper))}\/?(.*)_helper.rb$/
+          Dir["#{Reactive.dir_for(:helper)}/**/*_helper.rb"].map { |file| file.sub extract, '\1' }
+        end
+    end
+  end
+end

data/lib/reactive-mvc/controller/layout.rb

@@ -0,0 +1,285 @@
+module Reactive::Mvc::Controller #:nodoc:
+  module Layout #:nodoc:
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.class_eval do
+        class << self
+          alias_method_chain :inherited, :layout
+        end
+      end
+    end
+
+    # Layouts reverse the common pattern of including shared headers and footers in many templates to isolate changes in
+    # repeated setups. The inclusion pattern has pages that look like this:
+    #
+    #   <%= render "shared/header" %>
+    #   Hello World
+    #   <%= render "shared/footer" %>
+    #
+    # This approach is a decent way of keeping common structures isolated from the changing content, but it's verbose
+    # and if you ever want to change the structure of these two includes, you'll have to change all the templates.
+    #
+    # With layouts, you can flip it around and have the common structure know where to insert changing content. This means
+    # that the header and footer are only mentioned in one place, like this:
+    #
+    #   // The header part of this layout
+    #   <%= yield %>
+    #   // The footer part of this layout -->
+    #
+    # And then you have content pages that look like this:
+    #
+    #    hello world
+    #
+    # Not a word about common structures. At rendering time, the content page is computed and then inserted in the layout, 
+    # like this:
+    #
+    #   // The header part of this layout
+    #   hello world
+    #   // The footer part of this layout -->
+    #
+    # == Accessing shared variables
+    #
+    # Layouts have access to variables specified in the content pages and vice versa. This allows you to have layouts with
+    # references that won't materialize before rendering time:
+    #
+    #   <h1><%= @page_title %></h1>
+    #   <%= yield %>
+    #
+    # ...and content pages that fulfill these references _at_ rendering time:
+    #
+    #    <% @page_title = "Welcome" %>
+    #    Off-world colonies offers you a chance to start a new life
+    #
+    # The result after rendering is:
+    #
+    #   <h1>Welcome</h1>
+    #   Off-world colonies offers you a chance to start a new life
+    #
+    # == Automatic layout assignment
+    #
+    # If there is a template in <tt>app/views/layouts/</tt> with the same name as the current controller then it will be automatically
+    # set as that controller's layout unless explicitly told otherwise. Say you have a WeblogController, for example. If a template named 
+    # <tt>app/views/layouts/weblog.erb</tt> or <tt>app/views/layouts/weblog.builder</tt> exists then it will be automatically set as
+    # the layout for your WeblogController. You can create a layout with the name <tt>application.erb</tt> or <tt>application.builder</tt>
+    # and this will be set as the default controller if there is no layout with the same name as the current controller and there is 
+    # no layout explicitly assigned with the +layout+ method. Nested controllers use the same folder structure for automatic layout.
+    # assignment. So an Admin::WeblogController will look for a template named <tt>app/views/layouts/admin/weblog.erb</tt>.
+    # Setting a layout explicitly will always override the automatic behaviour for the controller where the layout is set.
+    # Explicitly setting the layout in a parent class, though, will not override the child class's layout assignment if the child
+    # class has a layout with the same name. 
+    #
+    # == Inheritance for layouts
+    #
+    # Layouts are shared downwards in the inheritance hierarchy, but not upwards. Examples:
+    #
+    #   class BankController < ActionController::Base
+    #     layout "bank_standard"
+    #
+    #   class InformationController < BankController
+    #
+    #   class VaultController < BankController
+    #     layout :access_level_layout
+    #
+    #   class EmployeeController < BankController
+    #     layout nil
+    #
+    # The InformationController uses "bank_standard" inherited from the BankController, the VaultController overwrites
+    # and picks the layout dynamically, and the EmployeeController doesn't want to use a layout at all.
+    #
+    # == Types of layouts
+    #
+    # Layouts are basically just regular templates, but the name of this template needs not be specified statically. Sometimes
+    # you want to alternate layouts depending on runtime information, such as whether someone is logged in or not. This can
+    # be done either by specifying a method reference as a symbol or using an inline method (as a proc).
+    #
+    # The method reference is the preferred approach to variable layouts and is used like this:
+    #
+    #   class WeblogController < ActionController::Base
+    #     layout :writers_and_readers
+    #
+    #     def index
+    #       # fetching posts
+    #     end
+    #
+    #     private
+    #       def writers_and_readers
+    #         logged_in? ? "writer_layout" : "reader_layout"
+    #       end
+    #
+    # Now when a new request for the index action is processed, the layout will vary depending on whether the person accessing 
+    # is logged in or not.
+    #
+    # If you want to use an inline method, such as a proc, do something like this:
+    #
+    #   class WeblogController < ActionController::Base
+    #     layout proc{ |controller| controller.logged_in? ? "writer_layout" : "reader_layout" }
+    #
+    # Of course, the most common way of specifying a layout is still just as a plain template name:
+    #
+    #   class WeblogController < ActionController::Base
+    #     layout "weblog_standard"
+    #
+    # If no directory is specified for the template name, the template will by default be looked for in +app/views/layouts/+. 
+    # Otherwise, it will be looked up relative to the template root.
+    #
+    # == Conditional layouts
+    #
+    # If you have a layout that by default is applied to all the actions of a controller, you still have the option of rendering
+    # a given action or set of actions without a layout, or restricting a layout to only a single action or a set of actions. The 
+    # <tt>:only</tt> and <tt>:except</tt> options can be passed to the layout call. For example:
+    #
+    #   class WeblogController < ActionController::Base
+    #     layout "weblog_standard", :except => :rss
+    # 
+    #     # ...
+    #
+    #   end
+    #
+    # This will assign "weblog_standard" as the WeblogController's layout  except for the +rss+ action, which will not wrap a layout 
+    # around the rendered view.
+    #
+    # Both the <tt>:only</tt> and <tt>:except</tt> condition can accept an arbitrary number of method references, so 
+    # #<tt>:except => [ :rss, :text_only ]</tt> is valid, as is <tt>:except => :rss</tt>.
+    #
+    # == Using a different layout in the action render call
+    # 
+    # If most of your actions use the same layout, it makes perfect sense to define a controller-wide layout as described above.
+    # Some times you'll have exceptions, though, where one action wants to use a different layout than the rest of the controller.
+    # This is possible using the <tt>render</tt> method. It's just a bit more manual work as you'll have to supply fully
+    # qualified template and layout names as this example shows:
+    #
+    #   class WeblogController < ActionController::Base
+    #     def help
+    #       render :action => "help/index", :layout => "help"
+    #     end
+    #   end
+    #
+    # As you can see, you pass the template as the first parameter, the status code as the second ("200" is OK), and the layout
+    # as the third.
+    #
+    # NOTE: The old notation for rendering the view from a layout was to expose the magic <tt>@content_for_layout</tt> instance 
+    # variable. The preferred notation now is to use <tt>yield</tt>, as documented above.
+    module ClassMethods
+      # If a layout is specified, all rendered actions will have their result rendered  
+      # when the layout <tt>yield</tt>s. This layout can itself depend on instance variables assigned during action
+      # performance and have access to them as any normal template would.
+      def layout(template_name, conditions = {}, auto = false)
+        add_layout_conditions(conditions)
+        write_inheritable_attribute(:layout, template_name)
+        write_inheritable_attribute(:auto_layout, auto)
+      end
+
+      def layout_conditions #:nodoc:
+        @layout_conditions ||= read_inheritable_attribute(:layout_conditions)
+      end
+      
+      def default_layout(format) #:nodoc:
+        layout = read_inheritable_attribute(:layout)
+        return layout unless read_inheritable_attribute(:auto_layout)
+        @default_layout ||= {}
+        @default_layout[format] ||= default_layout_with_format(format, layout)
+        @default_layout[format]
+      end
+      
+      def layout_list #:nodoc:
+        Array(view_paths).sum([]) { |path| Dir["#{path}/layouts/**/*"] }
+      end
+      
+      private
+        def inherited_with_layout(child)
+          inherited_without_layout(child)
+          unless child.name.blank?
+            layout_match = child.name.underscore.sub(/_controller$/, '').sub(/^controllers\//, '')
+            child.layout(layout_match, {}, true) unless child.layout_list.grep(%r{layouts/#{layout_match}(\.[a-z][0-9a-z]*)+$}).empty?
+          end
+        end
+
+        def add_layout_conditions(conditions)
+          write_inheritable_hash(:layout_conditions, normalize_conditions(conditions))
+        end
+
+        def normalize_conditions(conditions)
+          conditions.inject({}) {|hash, (key, value)| hash.merge(key => [value].flatten.map {|action| action.to_s})}
+        end
+        
+        def default_layout_with_format(format, layout)
+          list = layout_list
+          if list.grep(%r{layouts/#{layout}\.#{format}(\.[a-z][0-9a-z]*)+$}).empty?
+            (!list.grep(%r{layouts/#{layout}\.([a-z][0-9a-z]*)+$}).empty? && format == :rb) ? layout : nil
+          else
+            layout
+          end
+        end
+    end
+
+    # Returns the name of the active layout. If the layout was specified as a method reference (through a symbol), this method
+    # is called and the return value is used. Likewise if the layout was specified as an inline method (through a proc or method
+    # object). If the layout was defined without a directory, layouts is assumed. So <tt>layout "weblog/standard"</tt> will return
+    # weblog/standard, but <tt>layout "standard"</tt> will return layouts/standard.
+    def active_layout(passed_layout = nil)
+      layout = passed_layout || self.class.default_layout(default_template_format)
+      active_layout = case layout
+        when String then layout
+        when Symbol then send(layout)
+        when Proc   then layout.call(self)
+      end
+      
+      # Explicitly passed layout names with slashes are looked up relative to the template root,
+      # but auto-discovered layouts derived from a nested controller will contain a slash, though be relative
+      # to the 'layouts' directory so we have to check the file system to infer which case the layout name came from.
+      if active_layout
+        if active_layout.include?('/') && ! layout_directory?(active_layout)
+          active_layout
+        else
+          "layouts/#{active_layout}"
+        end
+      end
+    end
+
+    private
+      def candidate_for_layout?(options)
+        options.values_at(:text, :xml, :json, :file, :inline, :partial, :nothing, :update).compact.empty? &&
+          !@template.__send__(:_exempt_from_layout?, options[:template] || default_template_name(options[:action]))
+      end
+
+      def pick_layout(options)
+        if options.has_key?(:layout)
+          case layout = options.delete(:layout)
+          when FalseClass
+            nil
+          when NilClass, TrueClass
+            active_layout if action_has_layout? && !@template.__send__(:_exempt_from_layout?, default_template_name)
+          else
+            active_layout(layout)
+          end
+        else
+          active_layout if action_has_layout? && candidate_for_layout?(options)
+        end
+      end
+
+      def action_has_layout?
+        if conditions = self.class.layout_conditions
+          case
+            when only = conditions[:only]
+              only.include?(action_name)
+            when except = conditions[:except]
+              !except.include?(action_name)
+            else
+              true
+          end
+        else
+          true
+        end
+      end
+
+      def layout_directory?(layout_name)
+        @template.template_exists?("#{File.join('layouts', layout_name)}.#{@template.template_format}")
+      rescue Reactive::View::MissingTemplate
+        false
+      end
+
+      def default_template_format
+        response.template.template_format
+      end
+  end
+end