ramaze 2011.01.30 → 2011.07.25

data/lib/ramaze/helper/layout.rb

@@ -1,97 +1,113 @@
 module Ramaze
   module Helper
-
+    ##
     # Provides wrapper methods for a higher-level approach than the core layout
-    # method.  These are useful for simpler layout needs, particularly:
+    # method. The layout() method that comes with Innate/Ramaze is fairly basic
+    # as it only allows you to specify a single layout to always use or a block
+    # giving you some extra flexibility. The latter however is still a bit of a
+    # pain when dealing with many custom layouts in a single controller. Meet
+    # the Layout helper. This helper provides a single method (since April 2011,
+    # it used to provide more) called "set_layout".  This method allows you to
+    # specify a number of layouts and the methods for which these layouts should
+    # be used.
+    #
+    # == Examples
+    #
+    # The most basic example is simply setting a layout as you would do with the
+    # layout() method:
+    #
+    #  set_layout 'default'
     #
-    # * layout all actions
-    # * layout a whitelist of actions
-    # * layout all but a blacklist of actions
+    # This of course is very boring, time to add some more spices to our code:
     #
-    # As with the core layout method, the layout rules apply only to the
-    # controller on which they are applied.  Furthermore, multiple layout
-    # definitions are not combined; only the last definition will be used.
+    #  set_layout 'default' => [:index]
     #
-    # This helper is one of the default helpers, so no explicit helper call
-    # is necessary before using it in your controllers.
+    # Woah! What just happened? It's quite easy actually, we merely defined that
+    # the layout called "default" should be used for the index method *only*.
+    # Pretty sweet huh? It gets even better:
     #
-    # Usage:
+    #  set_layout 'default' => [:index, :edit], 'alternative' => [:add, :process]
     #
-    #    class MainController < Controller
-    #      # Apply the default layout (e.g. ./layout/default.xhtml) to all
-    #      # three actions.
-    #      set_layout 'default'
-    #      def action1; end
-    #      def action2; end
-    #      def action3; end
-    #    end
+    # A few things changed. First of all there are now two key/value groups.
+    # Each group defines a layout (the key) and a set of methods (the value) for
+    # which each layout should be used. In this case the layout "default" will
+    # be used for index() and edit() but the layout "alternative" will be used
+    # for add() and process().
     #
-    #    class MainController < Controller
-    #      # These two layout definitions accomplish the same thing.  The
-    #      # first uses a whitelist, the second uses a blacklist.
-    #      set_layout 'default' => [:laid_out1, :laid_out2]
-    #      set_layout_except 'default' => [:not_laid_out1, :not_laid_out2]
+    # Last but not least, multiple calls to set_layout will no longer override
+    # any existing settings *unless* you actually specify the same method with a
+    # different layout. This is possible because the set_layout method stores
+    # all these details in an instance variable called "_ramaze_layouts".
     #
-    #      def laid_out1; end
-    #      def laid_out2; end
+    # @author Yorick Peterse
+    # @author Michael Fellinger
+    # @author Pistos
     #
-    #      def not_laid_out1; end
-    #      def not_laid_out2; end
-    #    end
     module Layout
+
+      ##
+      # Extends the class that included this module so that the methods that
+      # this helper provides can be called outside of instance of class methods.
+      #
+      # @param [Object] into The class that included this module.
+      # @author Michael Fellinger
+      # @author Pistos
+      #
       def self.included(into)
         into.extend SingletonMethods
       end
 
       module SingletonMethods
-        # @param [String Hash] Either a layout name, or a single-element Hash
-        #   which maps a layout name to an Array containing a whitelist of
-        #   action names
-        # @see set_layout_except Innate::Node::layout
-        # @author Pistos, manveru
-        # @example Use a layout named 'default' on all actions of the controller:
-        #   set_layout 'default'
-        # @example Use a layout named 'default' on just the index and admin actions:
-        #   set_layout 'default' => [ :index, :admin ]
-        def set_layout(hash_or_the_layout)
-          if hash_or_the_layout.respond_to?(:to_hash)
-            f = hash_or_the_layout.to_hash.find{|k,v| k && v }
-            the_layout = f[0]
-            whitelist = f[1].map{|action| action.to_s }
-          else
-            the_layout = hash_or_the_layout
-          end
+        ##
+        # The set_layout method allows you to specify a number of methods and
+        # their layout. This allows you to use layout A for methods 1, 2 and 3
+        # but layout B for method 4.
+        #
+        # @example
+        #  # The key is the layout, the value an array of methods
+        #  set_layout 'default' => [:method_1], 'alternative' => [:method_2]
+        #
+        #  # We can combine this method with layout()
+        #  layout 'default'
+        #  set_layout 'alternative' => [:method_1]
+        #
+        #  # This is also perfectly fine
+        #  set_layout 'default'
+        #
+        # @param  [String, Symbol, #to_hash] hash_or_layout
+        #   In case it's a String or Symbol it will directly be used as the
+        #   layout.
+        #   When setting a Hash this hash should have it's keys set to the
+        #   layouts and it's values to an array of methods that use the
+        #   specific layout. For more information see the examples.
+        #
+        # @author Yorick Peterse
+        # @author Michael Fellinger
+        # @author Pistos
+        # @since 2011-04-07
+        def set_layout(hash_or_layout)
+          @_ramaze_layouts ||= {}
 
-          layout do |path, wish|
-            if whitelist.nil? || whitelist.include?(path.to_s)
-              the_layout
+          # Extract the layout to use
+          if hash_or_layout.respond_to?(:to_hash)
+            # Invert the method/layout hash and save them so they don't get lost
+            hash_or_layout.to_hash.each do |layout, layout_methods|
+              layout_methods.each do |layout_method|
+                @_ramaze_layouts[layout_method.to_s] = layout.to_s
+              end
             end
-          end
-        end
 
-        # @param [String Hash] Either a layout name, or a single-element Hash
-        #   which maps a layout name to an Array containing a blacklist of
-        #   action names
-        # @see set_layout Innate::Node::layout
-        # @author Pistos, manveru
-        # @example Use a layout named 'default' on all actions except the user_data action:
-        #   set_layout_except 'default' => [ :user_data ]
-        def set_layout_except(hash_or_the_layout)
-          if hash_or_the_layout.respond_to?(:to_hash)
-            f = hash_or_the_layout.to_hash.find{|k,v| k && v }
-            the_layout = f[0]
-            blacklist = f[1].map{|action| action.to_s }
+            layout{|path| @_ramaze_layouts[path.to_s] }
           else
-            the_layout = hash_or_the_layout
+            layout{|path| hash_or_layout }
           end
+        end
 
-          layout do |path, wish|
-            if blacklist.nil? || !blacklist.include?(path.to_s)
-              the_layout
-            end
-          end
+        # @deprecated because it's not longer useful
+        def set_layout_except(hash_or_layout)
+          Ramaze.deprecated('set_layout_except', 'set_layout')
         end
-      end
-    end
-  end
-end
+      end # SingletonMethods
+    end # Layout
+  end # Helper
+end # Ramaze

data/lib/ramaze/helper/link.rb

@@ -16,9 +16,10 @@ module Ramaze
         [prefix, location].join('/')
       end
 
-      # Give it a path with character to split at and one to join the crumbs with.
-      # It will generate a list of links that act as pointers to previous pages on
-      # this path.
+      ##
+      # Give it a path with character to split at and one to join the crumbs
+      # with.  It will generate a list of links that act as pointers to previous
+      # pages on this path.
       #
       # @example usage
       #   breadcrumbs('/path/to/somewhere')
@@ -51,6 +52,6 @@ module Ramaze
         end
         bread.join(join)
       end
-    end
-  end
-end
+    end # Link
+  end # Helper
+end # Ramaze

data/lib/ramaze/helper/localize.rb

@@ -4,8 +4,9 @@ require 'locale'
 module Ramaze
   module Helper
     ##
-    # The localization helper can be used to output translated strings.
-    # This enables your application to use multiple language files for English, Dutch and so on.
+    # The localization helper can be used to output translated strings.  This
+    # enables your application to use multiple language files for English, Dutch
+    # and so on.
     #
     module Localize
       include Traited
@@ -137,6 +138,6 @@ module Ramaze
             ::Locale::Tag.parse(lang) }
         end
       end
-    end
-  end
-end
+    end # Localize
+  end # Helper
+end # Ramaze

data/lib/ramaze/helper/markaby.rb

@@ -2,30 +2,32 @@
 # All files in this distribution are subject to the terms of the Ruby license.
 
 module Ramaze
+  module Helper
+    # Allows you to use some shortcuts for markaby in your Controller.
+    module Markaby
+      ##
+      # use this inside your controller to directly build Markaby
+      # Refer to the Markaby-documentation and testsuite for more examples.
+      #
+      # @example
+      #  mab { h1 "Apples & Oranges"}  #=> "<h1>Apples &amp; Oranges</h1>"
+      #  mab { h1 'Apples', :class => 'fruits&floots' }
+      #
+      def markaby(ivs = {}, helpers = nil, &block)
+        builder = ::Markaby::Builder
+        builder.extend(Ramaze::Helper::Methods)
+        builder.send(:helper, :link)
 
-  # Allows you to use some shortcuts for markaby in your Controller.
+        iv_hash = {}
+        instance_variables.each do |iv|
+          key, value = iv.gsub('@', '').to_sym, instance_variable_get(iv)
+          iv_hash[key] = value
+        end
 
-  module Helper::Markaby
-    # use this inside your controller to directly build Markaby
-    # Refer to the Markaby-documentation and testsuite for more examples.
-    # Usage:
-    #   mab { h1 "Apples & Oranges"}                    #=> "<h1>Apples &amp; Oranges</h1>"
-    #   mab { h1 'Apples', :class => 'fruits&floots' }  #=> "<h1 class=\"fruits&amp;floots\">Apples</h1>"
-
-    def markaby(ivs = {}, helpers = nil, &block)
-      builder = ::Markaby::Builder
-      builder.extend(Ramaze::Helper::Methods)
-      builder.send(:helper, :link)
-
-      iv_hash = {}
-      instance_variables.each do |iv|
-        key, value = iv.gsub('@', '').to_sym, instance_variable_get(iv)
-        iv_hash[key] = value
+        builder.new(iv_hash.merge(ivs), helpers, &block).to_s
       end
 
-      builder.new(iv_hash.merge(ivs), helpers, &block).to_s
-    end
-
-    alias mab markaby
-  end
-end
+      alias mab markaby
+    end # Markaby
+  end # Helper
+end # Ramaze

data/lib/ramaze/helper/maruku.rb

@@ -11,6 +11,6 @@ module Ramaze
       def maruku(text)
         ::Maruku.new(text.to_str).to_html
       end
-    end
-  end
-end
+    end # Maruku
+  end # Helper
+end # Ramaze

data/lib/ramaze/helper/paginate.rb

@@ -2,23 +2,21 @@ require 'ramaze/gestalt'
 
 module Ramaze
   module Helper
-
     # Helper for pagination and pagination-navigation.
     #
     # See detailed API docs for Paginator below.
     # Also have a look at the examples/helpers/paginate.rb
-
     module Paginate
       include Traited
 
       # Define default options in your Controller, they are being retrieved by
       # ancestral_trait, so you can also put it into a common superclass
-
       trait :paginate => {
         :limit => 10,
         :var   => 'pager',
       }
 
+      ##
       # Returns a new Paginator instance.
       #
       # Note that the pagination relies on being inside a Ramaze request to
@@ -53,18 +51,17 @@ module Ramaze
       #   :page   The page you are currently on, if not given it will be
       #           retrieved from current request variables. Defaults to 1 if
       #           neither exists.
-
+      #
       def paginate(dataset, options = {})
         options = ancestral_trait[:paginate].merge(options)
         limit = options[:limit]
         var   = options[:var]
         page  = options[:page] || (request[var] || 1).to_i
-          
+
         Paginator.new(dataset, page, limit, var)
       end
 
       # Provides easy pagination and navigation
-
       class Paginator
         include Ramaze::Helper
         helper :link, :cgi
@@ -76,6 +73,7 @@ module Ramaze
           @pager = pager_for(data)
         end
 
+        ##
         # Returns String with navigation div.
         #
         # This cannot be customized very nicely, but you can style it easily
@@ -100,8 +98,7 @@ module Ramaze
         #     <span class="next grey">&gt;</span>
         #     <span class="last grey">&gt;&gt;</span>
         #   </div>
-
-
+        #
         def navigation(limit = 8)
           g = Ramaze::Gestalt.new
           g.div :class => :pager do
@@ -140,24 +137,22 @@ module Ramaze
         end
 
         # Useful to omit pager if it's of no use.
-
         def needed?
           @pager.page_count > 1
         end
 
         # these methods are actually on the pager, but we def them here for
         # convenience (method_missing in helper is evil and even slower)
-
-        def page_count; @pager.page_count end
-        def each(&block) @pager.each(&block) end
-        def first_page?; @pager.first_page?; end
-        def prev_page; @pager.prev_page; end
+        def page_count  ; @pager.page_count  ; end
+        def each(&block); @pager.each(&block); end
+        def first_page? ; @pager.first_page? ; end
+        def prev_page   ; @pager.prev_page   ; end
         def current_page; @pager.current_page; end
-        def last_page; @pager.last_page; end
-        def last_page?; @pager.last_page?; end
-        def next_page; @pager.next_page; end
-        def empty?; @pager.empty?; end
-        def count; @pager.count; end
+        def last_page   ; @pager.last_page   ; end
+        def last_page?  ; @pager.last_page?  ; end
+        def next_page   ; @pager.next_page   ; end
+        def empty?      ; @pager.empty?      ; end
+        def count       ; @pager.count       ; end
 
         private
 
@@ -185,7 +180,6 @@ module Ramaze
         end
 
         # Wrapper for Array to behave like the Sequel pagination
-
         class ArrayPager
           def initialize(array, page, limit)
             @array, @page, @limit = array, page, limit
@@ -257,10 +251,8 @@ module Ramaze
           def empty?
             size == 0
           end
-
-        end
-
-      end
-    end
-  end
-end
+        end # DataMapperPager
+      end # Paginator
+    end # Paginate
+  end # Helper
+end # Ramaze

data/lib/ramaze/helper/remarkably.rb

@@ -9,6 +9,6 @@ module Ramaze
       def a(*args, &block)
         method_missing(:a, *args, &block)
       end
-    end
-  end
-end
+    end # Remarkably
+  end # Helper
+end # Ramaze

data/lib/ramaze/helper/request_accessor.rb

@@ -11,6 +11,6 @@ module Ramaze
           eval("def %s(*a) request.%s(*a); end" % [method, method])
         end
       end
-    end
-  end
-end
+    end # RequestAccessor
+  end # Helper
+end # Ramaze

data/lib/ramaze/helper/send_file.rb

@@ -2,16 +2,20 @@ module Ramaze
   module Helper
     ##
     # The SendFile module can be used to stream a file to the user's computer.
-    # While the performance of the module isn't optimal it's convenient and relatively easy to use.
+    # While the performance of the module isn't optimal it's convenient and
+    # relatively easy to use.
     #
     module SendFile
       ##
       # The send_file method streams the specified file to the user's browser.
       #
-      # @param [String] filename The name or path to the file which will be streamed to the user.
-      # @param [String] content_type The type of file we're dealing with. For example, if we want to stream
-      # a JPG image we'd set this variable to 'image/jpg'.
-      # @param [String] content_disposition Value for the Content-Disposition header.
+      # @param [String] filename The name or path to the file which will be 
+      #  streamed to the user.
+      # @param [String] content_type The type of file we're dealing with. For
+      #  example, if we want to stream a JPG image we'd set this variable to
+      #  'image/jpg'.
+      # @param [String] content_disposition Value for the Content-Disposition 
+      #  header.
       #
       def send_file(filename, content_type = nil, content_disposition = nil)
         content_type ||= Rack::Mime.mime_type(::File.extname(filename))
@@ -25,6 +29,6 @@ module Ramaze
 
         throw(:respond, response)
       end
-    end
-  end
-end
+    end # SendFile
+  end # Helper
+end # Ramaze