padrino-helpers 0.10.2 → 0.10.3

data/lib/padrino-helpers/output_helpers.rb

@@ -7,8 +7,8 @@ module Padrino
       end
 
       ##
-      # Module used to detect in vanilla sinatra apps the current engine
-      #
+      # Module used to detect the current engine in vanilla sinatra apps.
+      # @private
       module SinatraCurrentEngine
         attr_reader :current_engine
 
@@ -21,12 +21,20 @@ module Padrino
       end
 
       ##
-      # Captures the html from a block of template code for any available handler
+      # Captures the html from a block of template code for any available handler.
+      #
+      # @param [Object] *args
+      #   Objects yield to the captured block
+      # @param [Proc] &block
+      #   Template code to capture as html
       #
-      # ==== Examples
+      # @return [String] Captured html resulting from the block
       #
+      # @example
       #   capture_html(&block) => "...html..."
+      #   capture_html(object_for_block, &block) => "...html..."
       #
+      # @api semipublic
       def capture_html(*args, &block)
         handler = find_proper_handler
         captured_html = ""
@@ -40,12 +48,15 @@ module Padrino
       alias :capture :capture_html
 
       ##
-      # Outputs the given text to the templates buffer directly
+      # Outputs the given text to the templates buffer directly.
       #
-      # ==== Examples
+      # @param [String] text
+      #   Text to concatenate to the buffer.
       #
+      # @example
       #   concat_content("This will be output to the template buffer")
       #
+      # @api semipublic
       def concat_content(text="")
         handler = find_proper_handler
         if handler && handler.is_type?
@@ -58,12 +69,17 @@ module Padrino
 
       ##
       # Returns true if the block is from a supported template type; false otherwise.
-      # Used to determine if html should be returned or concatenated to the view
+      # Used to determine if html should be returned or concatenated to the view.
       #
-      # ==== Examples
+      # @param [Block] block
+      #   Determine if this block is a view template.
       #
-      #   block_is_template?(block)
+      # @example
+      #   block_is_template?(block) => true
       #
+      # @return [Boolean] True if the block is a template; false otherwise.
+      #
+      # @api semipublic
       def block_is_template?(block)
         handler = find_proper_handler
         block && handler && handler.block_is_type?(block)
@@ -73,27 +89,57 @@ module Padrino
       # Capture a block or text of content to be rendered at a later time.
       # Your blocks can also receive values, which are passed to them by <tt>yield_content</tt>
       #
-      # ==== Examples
+      # @overload content_for(key, content)
+      #   @param [Symbol] key      Name of your key for the content yield.
+      #   @param [String] content  Text to be stored for this key.
+      # @overload content_for(key, &block)
+      #   @param [Symbol] key      Name of your key for the content yield.
+      #   @param [Proc]   block    Block to be stored as content for this key.
       #
+      # @example
       #   content_for(:name) { ...content... }
       #   content_for(:name) { |name| ...content... }
       #   content_for(:name, "I'm Jeff")
       #
+      # @api public
       def content_for(key, content = nil, &block)
         content_blocks[key.to_sym] << (block_given? ? block : Proc.new { content })
       end
 
+      ##
+      # Is there a content block for a given key?
+      #
+      # @param [Symbol] key
+      #   Name of content to yield
+      #
+      # @return [TrueClass,FalseClass] Result html for the given +key+
+      #
+      # @example
+      #   content_for? :header => true
+      #
+      # @api public
+      def content_for?(key)
+        content_blocks[key.to_sym].present?
+      end
+
       ##
       # Render the captured content blocks for a given key.
       # You can also pass values to the content blocks by passing them
       # as arguments after the key.
       #
-      # ==== Examples
+      # @param [Symbol] key
+      #   Name of content to yield
+      # @param *args
+      #   Values to pass to the content block
       #
+      # @return [String] Result html for the given +key+
+      #
+      # @example
       #   yield_content :include
       #   yield_content :head, "param1", "param2"
       #   yield_content(:title) || "My page title"
       #
+      # @api public
       def yield_content(key, *args)
         blocks = content_blocks[key.to_sym]
         return nil if blocks.empty?
@@ -104,8 +150,7 @@ module Padrino
         ##
         # Retrieves content_blocks stored by content_for or within yield_content
         #
-        # ==== Examples
-        #
+        # @example
         #   content_blocks[:name] => ['...', '...']
         #
         def content_blocks
@@ -116,8 +161,7 @@ module Padrino
         # Retrieves the template handler for the given output context.
         # Can handle any output related to capturing or concating in a given template.
         #
-        # ==== Examples
-        #
+        # @example
         #   find_proper_handler => <OutputHelpers::HamlHandler>
         #
         def find_proper_handler

data/lib/padrino-helpers/output_helpers/abstract_handler.rb

@@ -4,10 +4,10 @@ module Padrino
       ##
       # Returns the list of all available template handlers
       #
-      # ==== Examples
-      #
+      # @example
       #   OutputHelpers.handlers => [<OutputHelpers::HamlHandler>, <OutputHelpers::ErbHandler>]
       #
+      # @private
       def self.handlers
         @_template_handlers ||= []
       end
@@ -15,14 +15,15 @@ module Padrino
       ##
       # Registers a new handler as available to the output helpers
       #
-      # ==== Examples
-      #
+      # @example
       #   OutputHelpers.register(OutputHelpers::HamlHandler)
       #
+      # @private
       def self.register(handler)
         handlers << handler
       end
 
+      # @abstract Extend this to create a template handler
       class AbstractHandler
         attr_reader :template
 
@@ -33,9 +34,8 @@ module Padrino
         ##
         # Returns extension of the template
         #
-        # ==== Examples
-        #
-        #  @handler.template_extension => "erb"
+        # @example
+        #   @handler.template_extension => "erb"
         #
         def template_extension
           caller.find { |c| c =~ /\/views\// }[/\.([\w]*?)\:/, 1] rescue nil
@@ -46,8 +46,7 @@ module Padrino
         ##
         # Returns an array of engines used for the template
         #
-        # ==== Examples
-        #
+        # @example
         #   @handler.engines => [:erb, :erubis]
         #
         def engines
@@ -57,9 +56,8 @@ module Padrino
         ##
         # Returns true if the current template type is same as this handlers; false otherwise.
         #
-        # ==== Examples
-        #
-        #  @handler.is_type? => true
+        # @example
+        #   @handler.is_type? => true
         #
         def is_type?
           # Implemented in subclass
@@ -68,9 +66,8 @@ module Padrino
         ##
         # Returns true if the block given is of the handler's template type; false otherwise.
         #
-        # ==== Examples
-        #
-        #  @handler.block_is_type?(block) => true
+        # @example
+        #   @handler.block_is_type?(block) => true
         #
         def block_is_type?(block)
           # Implemented in subclass
@@ -79,9 +76,8 @@ module Padrino
         ##
         # Captures the html from a block of template code for this handler
         #
-        # ==== Examples
-        #
-        #  @handler.capture_from_template(&block) => "...html..."
+        # @example
+        #   @handler.capture_from_template(&block) => "...html..."
         #
         def capture_from_template(*args, &block)
           # Implemented in subclass
@@ -90,8 +86,7 @@ module Padrino
         ##
         # Outputs the given text to the templates buffer directly
         #
-        # ==== Examples
-        #
+        # @example
         #   @handler.concat_to_template("This will be output to the template buffer")
         #
         def concat_to_template(text="")

data/lib/padrino-helpers/output_helpers/erb_handler.rb

@@ -12,9 +12,8 @@ module Padrino
         ##
         # Returns true if the current template type is same as this handlers; false otherwise.
         #
-        # ==== Examples
-        #
-        #  @handler.is_type? => true
+        # @example
+        #   @handler.is_type? => true
         #
         def is_type?
           !self.output_buffer.nil?
@@ -22,9 +21,8 @@ module Padrino
 
         # Captures the html from a block of template code for this handler
         #
-        # ==== Examples
-        #
-        #  @handler.capture_from_template(&block) => "...html..."
+        # @example
+        #   @handler.capture_from_template(&block) => "...html..."
         #
         def capture_from_template(*args, &block)
           self.output_buffer, _buf_was = "", self.output_buffer
@@ -37,8 +35,7 @@ module Padrino
         ##
         # Outputs the given text to the templates buffer directly
         #
-        # ==== Examples
-        #
+        # @example
         #   @handler.concat_to_template("This will be output to the template buffer")
         #
         def concat_to_template(text="")
@@ -49,9 +46,8 @@ module Padrino
         ##
         # Returns true if the block given is of the handler's template type; false otherwise.
         #
-        # ==== Examples
-        #
-        #  @handler.block_is_type?(block) => true
+        # @example
+        #   @handler.block_is_type?(block) => true
         #
         def block_is_type?(block)
           is_type? || (block && eval('defined?(__in_erb_template)', block.binding))
@@ -60,8 +56,7 @@ module Padrino
         ##
         # Returns an array of engines used for the template
         #
-        # ==== Examples
-        #
+        # @example
         #   @handler.engines => [:erb, :erubis]
         #
         def engines
@@ -69,11 +64,13 @@ module Padrino
         end
 
         protected
+
           def output_buffer=(val)
             template.instance_variable_set(:@_out_buf, val)
           end
-        end # ErbHandler
-        OutputHelpers.register(ErbHandler)
+      end # ErbHandler
+
+      OutputHelpers.register(ErbHandler)
     end # OutputHelpers
   end # Helpers
 end # Padrino

data/lib/padrino-helpers/output_helpers/haml_handler.rb

@@ -5,9 +5,8 @@ module Padrino
         ##
         # Returns true if the current template type is same as this handlers; false otherwise.
         #
-        # ==== Examples
-        #
-        #  @handler.is_type? => true
+        # @example
+        #   @handler.is_type? => true
         #
         def is_type?
           template.respond_to?(:is_haml?) && template.is_haml?
@@ -16,9 +15,8 @@ module Padrino
         ##
         # Returns true if the block given is of the handler's template type; false otherwise.
         #
-        # ==== Examples
-        #
-        #  @handler.block_is_type?(block) => true
+        # @example
+        #   @handler.block_is_type?(block) => true
         #
         def block_is_type?(block)
           template.block_is_haml?(block)
@@ -26,9 +24,8 @@ module Padrino
 
         # Captures the html from a block of template code for this handler
         #
-        # ==== Examples
-        #
-        #  @handler.capture_from_template(&block) => "...html..."
+        # @example
+        #   @handler.capture_from_template(&block) => "...html..."
         #
         def capture_from_template(*args, &block)
           eval("_hamlout ||= @haml_buffer", block.binding) # this is for rbx
@@ -38,8 +35,7 @@ module Padrino
         ##
         # Outputs the given text to the templates buffer directly
         #
-        # ==== Examples
-        #
+        # @example
         #   @handler.concat_to_template("This will be output to the template buffer")
         #
         def concat_to_template(text="")
@@ -50,14 +46,14 @@ module Padrino
         ##
         # Returns an array of engines used for the template
         #
-        # ==== Examples
-        #
-        #   @handler.engines => [:erb, :erubis]
+        # @example
+        #   @handler.engines => [:haml]
         #
         def engines
           @_engines ||= [:haml]
         end
       end # HamlHandler
+
       OutputHelpers.register(HamlHandler)
     end # OutputHelpers
   end # Helpers

data/lib/padrino-helpers/output_helpers/slim_handler.rb

@@ -15,9 +15,8 @@ module Padrino
         ##
         # Returns true if the current template type is same as this handlers; false otherwise.
         #
-        # ==== Examples
-        #
-        #  @handler.is_type? => true
+        # @example
+        #   @handler.is_type? => true
         #
         def is_type?
           !self.output_buffer.nil?
@@ -25,9 +24,8 @@ module Padrino
 
         # Captures the html from a block of template code for this handler
         #
-        # ==== Examples
-        #
-        #  @handler.capture_from_template(&block) => "...html..."
+        # @example
+        #   @handler.capture_from_template(&block) => "...html..."
         #
         def capture_from_template(*args, &block)
           self.output_buffer, _buf_was = "", self.output_buffer
@@ -40,8 +38,7 @@ module Padrino
         ##
         # Outputs the given text to the templates buffer directly
         #
-        # ==== Examples
-        #
+        # @example
         #   @handler.concat_to_template("This will be output to the template buffer")
         #
         def concat_to_template(text="")
@@ -52,9 +49,8 @@ module Padrino
         ##
         # Returns true if the block given is of the handler's template type; false otherwise.
         #
-        # ==== Examples
-        #
-        #  @handler.block_is_type?(block) => true
+        # @example
+        #   @handler.block_is_type?(block) => true
         #
         def block_is_type?(block)
           is_type? || (block && eval('defined? __in_erb_template', block.binding))
@@ -63,8 +59,7 @@ module Padrino
         ##
         # Returns an array of engines used for the template
         #
-        # ==== Examples
-        #
+        # @example
         #   @handler.engines => [:erb, :erubis]
         #
         def engines
@@ -75,7 +70,8 @@ module Padrino
           def output_buffer=(val)
             template.instance_variable_set(:@_out_buf, val)
           end
-        end # ErbHandler
+        end # SlimHandler
+
         OutputHelpers.register(SlimHandler)
     end # OutputHelpers
   end # Helpers

data/lib/padrino-helpers/render_helpers.rb

@@ -2,23 +2,39 @@ module Padrino
   module Helpers
     module RenderHelpers
       ##
-      # Partials implementation which includes collections support
+      # Render a partials with collections support
       #
-      # ==== Examples
+      # @param [String] template
+      #   Relative path to partial template.
+      # @param [Hash] options
+      #   Options hash for rendering options.
+      # @option options [Object] :object
+      #   Object rendered in partial.
+      # @option options [Array<Object>] :collection
+      #   Partial is rendered for each object in this collection.
+      # @option options [Hash] :locals ({})
+      #   Local variables accessible in the partial.
+      # @option options [Symbol] :engine
+      #   Explicit rendering engine to use for this partial
       #
+      # @return [String] The html generated from this partial.
+      #
+      # @example
       #   partial 'photo/item', :object => @photo
       #   partial 'photo/item', :collection => @photos
       #   partial 'photo/item', :locals => { :foo => :bar }
       #   partial 'photo/item', :engine => :erb
       #
+      # @note If using this from Sinatra, pass explicit +:engine+ option
+      #
+      # @api public
       def partial(template, options={})
-        logger.debug "PARTIAL:  #{template} called" if defined?(logger)
         options.reverse_merge!(:locals => {}, :layout => false)
-        path = template.to_s.split(File::SEPARATOR)
-        object_name = path[-1].to_sym
-        path[-1] = "_#{path[-1]}"
+        path            = template.to_s.split(File::SEPARATOR)
+        object_name     = path[-1].to_sym
+        path[-1]        = "_#{path[-1]}"
         explicit_engine = options.delete(:engine)
-        template_path = File.join(path).to_sym
+        template_path   = File.join(path).to_sym
         raise 'Partial collection specified but is nil' if options.has_key?(:collection) && options[:collection].nil?
         if collection = options.delete(:collection)
           options.delete(:object)