padrino-helpers 0.10.2 → 0.10.3

data/.document

@@ -1,5 +1,5 @@
-README.rdoc
 lib/**/*.rb
 bin/*
-features/**/*.feature
-LICENSE
+-
+README.rdoc
+LICENSE.txt

data/.yardopts

@@ -0,0 +1 @@
+--title 'Padrino Helpers Documentation' --protected

data/README.rdoc

@@ -34,7 +34,8 @@ Added to a template, this will capture the includes from the block and allow the
   ...
 
 This will automatically insert the contents of the block (in this case a stylesheet include) into the
-location the content is yielded within the layout.
+location the content is yielded within the layout. You can also check if content exists for a block using
+<tt>content_for?(true)</tt> which returns true if content exists.
 
 The capture_html and the concat_content methods allow content to be manipulated and stored for use in building
 additional helpers accepting blocks or displaying information in a template. One example is the use of
@@ -183,8 +184,7 @@ For more information on using the Padrino form builders, check out the guide for
 === Format Helpers
 
 Format helpers are several useful utilities for manipulating the format of text to achieve a goal.
-The four format helpers are <tt>escape_html</tt>, <tt>relative_time_ago</tt>, <tt>time_in_words</tt>,
-and <tt>js_escape_html</tt>.
+The four format helpers are <tt>escape_html</tt>, <tt>time_ago_in_words</tt>, and <tt>js_escape_html</tt>.
 
 The escape_html and js_escape_html function are for taking an html string and escaping certain characters.
 <tt>escape_html</tt> will escape ampersands, brackets and quotes to their HTML/XML entities. This is useful

data/lib/padrino-helpers.rb

@@ -15,25 +15,32 @@ I18n.load_path += Dir["#{File.dirname(__FILE__)}/padrino-helpers/locale/*.yml"]
 
 module Padrino
   ##
-  # This component provides a great deal of view helpers related to html markup generation.
+  # This component provides a variety of view helpers related to html markup generation.
   # There are helpers for generating tags, forms, links, images, and more.
   # Most of the basic methods should be very familiar to anyone who has used rails view helpers.
   #
   module Helpers
-    ##
-    # Register these helpers:
-    #
-    #   Padrino::Helpers::OutputHelpers
-    #   Padrino::Helpers::TagHelpers
-    #   Padrino::Helpers::AssetTagHelpers
-    #   Padrino::Helpers::FormHelpers
-    #   Padrino::Helpers::FormatHelpers
-    #   Padrino::Helpers::RenderHelpers
-    #   Padrino::Helpers::NumberHelpers
-    #
-    # for Padrino::Application
-    #
     class << self
+      ##
+      # Registers these helpers into your application:
+      #
+      #   Padrino::Helpers::OutputHelpers
+      #   Padrino::Helpers::TagHelpers
+      #   Padrino::Helpers::AssetTagHelpers
+      #   Padrino::Helpers::FormHelpers
+      #   Padrino::Helpers::FormatHelpers
+      #   Padrino::Helpers::RenderHelpers
+      #   Padrino::Helpers::NumberHelpers
+      #
+      # @param [Sinatra::Application] app
+      #   The specified padrino application
+      #
+      # @example Register the helper module
+      #   require 'padrino-helpers'
+      #   class Padrino::Appliocation
+      #     register Padrino::Helpers
+      #   end
+      #
       def registered(app)
         app.set :default_builder, 'StandardFormBuilder'
         app.helpers Padrino::Helpers::OutputHelpers

data/lib/padrino-helpers/asset_tag_helpers.rb

@@ -4,10 +4,18 @@ module Padrino
       ##
       # Creates a div to display the flash of given type if it exists
       #
-      # ==== Examples
-      #   # Generates: <div class="notice">flash-notice</div>
+      # @param [Symbol] kind
+      #   The type of flash to display in the tag.
+      # @param [Hash] options
+      #   The html options for this section.
+      #
+      # @return [String] Flash tag html with specified +options+.
+      #
+      # @example
       #   flash_tag(:notice, :id => 'flash-notice')
+      #   # Generates: <div class="notice">flash-notice</div>
       #
+      # @api public
       def flash_tag(kind, options={})
         flash_text = flash[kind]
         return '' if flash_text.blank?
@@ -18,16 +26,40 @@ module Padrino
       ##
       # Creates a link element with given name, url and options
       #
-      # ==== Examples
-      #
+      # @overload link_to(caption, url, options={})
+      #   @param [String]  caption  The text caption.
+      #   @param [String]  url      The url href.
+      #   @param [Hash]    options  The html options.
+      # @overload link_to(url, options={}, &block)
+      #   @param [String]  url      The url href.
+      #   @param [Hash]    options  The html options.
+      #   @param [Proc]    block    The link content.
+      #
+      # @option options [String] :anchor
+      #   The anchor for the link (i.e #something)
+      # @option options [Boolean] :if
+      #   If true, the link will appear, otherwise not;
+      # @option options [Boolean] :unless
+      #   If false, the link will appear, otherwise not;
+      # @option options [Boolean] :remote
+      #   If true, this link should be handled by a ajax ujs handler.
+      # @option options [String] :confirm
+      #   Instructs ujs handler to alert confirm message.
+      # @option options [Symbol] :method
+      #   Instructs ujs handler to use different http method (i.e :post, :delete).
+      #
+      # @return [String] Link tag html with specified +options+.
+      #
+      # @example
       #   link_to('click me', '/dashboard', :class => 'linky')
       #   link_to('click me', '/dashboard', :remote => true)
       #   link_to('click me', '/dashboard', :method => :delete)
-      #   link_to('click me', :class => 'blocky') do ... end
+      #   link_to('click me', :class => 'blocky') do; end
       #
       # Note that you can pass :+if+ or :+unless+ conditions, but if you provide :current as
       # condition padrino return true/false if the request.path_info match the given url
       #
+      # @api public
       def link_to(*args, &block)
         options = args.extract_options!
         options = parse_js_attributes(options) # parses remote, method and confirm options
@@ -51,15 +83,33 @@ module Padrino
       ##
       # Creates a form containing a single button that submits to the url.
       #
-      # ==== Examples
-      #
+      # @overload button_to(name, url, options={})
+      #   @param [String]  caption  The text caption.
+      #   @param [String]  url      The url href.
+      #   @param [Hash]    options  The html options.
+      # @overload button_to(name, options={}, &block)
+      #   @param [String]  url      The url href.
+      #   @param [Hash]    options  The html options.
+      #   @param [Proc]    block    The button content.
+      #
+      # @option options [Boolean] :multipart
+      #   If true, this form will support multipart encoding.
+      # @option options [String] :remote
+      #   Instructs ujs handler to handle the submit as ajax.
+      # @option options [Symbol] :method
+      #   Instructs ujs handler to use different http method (i.e :post, :delete).
+      #
+      # @return [String] Form and button html with specified +options+.
+      #
+      # @example
+      #   button_to 'Delete', url(:accounts_destroy, :id => account), :method => :delete, :class => :form
       #   # Generates:
       #   # <form class="form" action="/admin/accounts/destroy/2" method="post">
       #   #   <input type="hidden" value="delete" name="_method" />
       #   #   <input type="submit" value="Delete" />
       #   # </form>
-      #   button_to 'Delete', url(:accounts_destroy, :id => account), :method => :delete, :class => :form
       #
+      # @api public
       def button_to(*args, &block)
         name, url = args[0], args[1]
         options   = args.extract_options!
@@ -76,34 +126,56 @@ module Padrino
       ##
       # Creates a link tag that browsers and news readers can use to auto-detect an RSS or ATOM feed.
       #
-      # === Options
-      #
-      #   :rel::   Specify the relation of this link, defaults to "alternate"
-      #   :type::  Override the auto-generated mime type
-      #   :title:: Specify the title of the link, defaults to the type
-      #
-      # === Examples
-      #
-      #   # Generates: <link type="application/atom+xml" rel="alternate" href="/blog/posts.atom" title="ATOM" />
+      # @param [Symbol] mime
+      #   The mime type of the feed (i.e :atom or :rss).
+      # @param [String] url
+      #   The url for the feed tag to reference.
+      # @param[Hash] options
+      #   The options for the feed tag.
+      # @option options [String] :rel ("alternate")
+      #   Specify the relation of this link
+      # @option options [String] :type
+      #   Override the auto-generated mime type
+      # @option options [String] :title
+      #   Specify the title of the link, defaults to the type
+      #
+      # @return [String] Feed link html tag with specified +options+.
+      #
+      # @example
       #   feed_tag :atom, url(:blog, :posts, :format => :atom), :title => "ATOM"
-      #   # Generates: <link type="application/rss+xml" rel="alternate" href="/blog/posts.rss" title="rss" />
+      #   # Generates: <link type="application/atom+xml" rel="alternate" href="/blog/posts.atom" title="ATOM" />
       #   feed_tag :rss, url(:blog, :posts, :format => :rss)
+      #   # Generates: <link type="application/rss+xml" rel="alternate" href="/blog/posts.rss" title="rss" />
       #
+      # @api public
       def feed_tag(mime, url, options={})
         full_mime = (mime == :atom) ? 'application/atom+xml' : 'application/rss+xml'
         content_tag(:link, options.reverse_merge(:rel => 'alternate', :type => full_mime, :title => mime, :href => url))
       end
 
       ##
-      # Creates a mail link element with given name and caption
-      #
-      # ==== Examples
-      #
+      # Creates a mail link element with given name and caption.
+      #
+      # @param [String] email
+      #   The email address for the link.
+      # @param [String] caption
+      #   The caption for the link.
+      # @param [Hash] mail_options
+      #   The options for the mail link. Accepts html options.
+      # @option mail_options [String] cc      The cc recipients.
+      # @option mail_options [String] bcc     The bcc recipients.
+      # @option mail_options [String] subject The subject line.
+      # @option mail_options [String] body    The email body.
+      #
+      # @return [String] Mail link html tag with specified +options+.
+      #
+      # @example
       #   # Generates: <a href="mailto:me@demo.com">me@demo.com</a>
       #   mail_to "me@demo.com"
       #   # Generates: <a href="mailto:me@demo.com">My Email</a>
       #   mail_to "me@demo.com", "My Email"
       #
+      # @api public
       def mail_to(email, caption=nil, mail_options={})
         html_options = mail_options.slice!(:cc, :bcc, :subject, :body)
         mail_query = Rack::Utils.build_query(mail_options).gsub(/\+/, '%20').gsub('%40', '@')
@@ -112,16 +184,23 @@ module Padrino
       end
 
       ##
-      # Creates a meta element with the content and given options
+      # Creates a meta element with the content and given options.
+      #
+      # @param [String] content
+      #   The content for the meta tag.
+      # @param [Hash] options
+      #   The html options for the meta tag.
       #
-      # ==== Examples
+      # @return [String] Meta html tag with specified +options+.
       #
+      # @example
       #   # Generates: <meta name="keywords" content="weblog,news">
       #   meta_tag "weblog,news", :name => "keywords"
       #
       #   # Generates: <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
       #   meta_tag "text/html; charset=UTF-8", 'http-equiv' => "Content-Type"
       #
+      # @api public
       def meta_tag(content, options={})
         options.reverse_merge!("content" => content)
         tag(:meta, options)
@@ -130,14 +209,21 @@ module Padrino
       ##
       # Generates a favicon link. looks inside images folder
       #
-      # ==== Examples
+      # @param [String] source
+      #   The source image path for the favicon link tag.
+      # @param [Hash] options
+      #   The html options for the favicon link tag.
       #
+      # @return [String] The favicon link html tag with specified +options+.
+      #
+      # @example
       #   favicon_tag 'favicon.png'
       #   favicon_tag 'icons/favicon.png'
       #   # or override some options
       #   favicon_tag 'favicon.png', :type => 'image/ico'
       #
-      def favicon_tag(source,options={})
+      # @api public
+      def favicon_tag(source, options={})
         type = File.extname(source).gsub('.','')
         options = options.dup.reverse_merge!(:href => image_path(source), :rel => 'icon', :type => "image/#{type}")
         tag(:link, options)
@@ -146,10 +232,17 @@ module Padrino
       ##
       # Creates an image element with given url and options
       #
-      # ==== Examples
+      # @param [String] url
+      #   The source path for the image tag.
+      # @param [Hash] options
+      #   The html options for the image tag.
+      #
+      # @return [String] Image html tag with +url+ and specified +options+.
       #
+      # @example
       #   image_tag('icons/avatar.png')
       #
+      # @api public
       def image_tag(url, options={})
         options.reverse_merge!(:src => image_path(url))
         tag(:img, options)
@@ -157,13 +250,19 @@ module Padrino
 
       ##
       # Returns an html script tag for each of the sources provided.
-      # You can pass in the filename without extension or a symbol and we search it in your +appname.public+
+      # You can pass in the filename without extension or a symbol and we search it in your +appname.public_folder+
       # like app/public/stylesheets for inclusion. You can provide also a full path.
       #
-      # ==== Examples
+      # @overload stylesheet_link_tag(*sources, options={})
+      #   @param [Array<String>] sources   Splat of css source paths
+      #   @param [Hash]          options   The html options for the link tag
+      #
+      # @return [String] Stylesheet link html tag for +sources+ with specified +options+.
       #
+      # @example
       #   stylesheet_link_tag 'style', 'application', 'layout'
       #
+      # @api public
       def stylesheet_link_tag(*sources)
         options = sources.extract_options!.symbolize_keys
         options.reverse_merge!(:media => 'screen', :rel => 'stylesheet', :type => 'text/css')
@@ -174,13 +273,19 @@ module Padrino
 
       ##
       # Returns an html script tag for each of the sources provided.
-      # You can pass in the filename without extension or a symbol and we search it in your +appname.public+
+      # You can pass in the filename without extension or a symbol and we search it in your +appname.public_folder+
       # like app/public/javascript for inclusion. You can provide also a full path.
       #
-      # ==== Examples
+      # @overload javascript_include_tag(*sources, options={})
+      #   @param [Array<String>] sources   Splat of js source paths
+      #   @param [Hash]          options   The html options for the script tag
       #
+      # @return [String] Script tag for +sources+ with specified +options+.
+      #
+      # @example
       #   javascript_include_tag 'application', :extjs
       #
+      # @api public
       def javascript_include_tag(*sources)
         options = sources.extract_options!.symbolize_keys
         options.reverse_merge!(:type => 'text/javascript', :content => "")
@@ -190,14 +295,19 @@ module Padrino
       end
 
       ##
-      # Returns the path to the image, either relative or absolute. We search it in your +appname.public+
+      # Returns the path to the image, either relative or absolute. We search it in your +appname.public_folder+
       # like app/public/images for inclusion. You can provide also a full path.
       #
-      # ==== Examples
+      # @param [String] src
+      #   The path to the image file (relative or absolute)
+      #
+      # @return [String] Path to an image given the +kind+ and +source+.
       #
+      # @example
       #   # Generates: /images/foo.jpg?1269008689
       #   image_path("foo.jpg")
       #
+      # @api public
       def image_path(src)
         asset_path(:images, src)
       end
@@ -205,8 +315,14 @@ module Padrino
       ##
       # Returns the path to the specified asset (css or javascript)
       #
-      # ==== Examples
+      # @param [String] kind
+      #   The kind of asset (i.e :images, :js, :css)
+      # @param [String] source
+      #   The path to the asset (relative or absolute).
       #
+      # @return [String] Path for the asset given the +kind+ and +source+.
+      #
+      # @example
       #   # Generates: /javascripts/application.js?1269008689
       #   asset_path :js, :application
       #
@@ -216,6 +332,7 @@ module Padrino
       #   # Generates: /images/example.jpg?1269008689
       #   asset_path :images, 'example.jpg'
       #
+      # @api semipublic
       def asset_path(kind, source)
         return source if source =~ /^http/
         asset_folder  = case kind
@@ -237,6 +354,9 @@ module Padrino
         ##
         # Returns the uri root of the application.
         #
+        # @example
+        #   uri_root_path("/some/path") => "/base/some/path"
+        #
         def uri_root_path(*paths)
           root_uri = self.class.uri_root if self.class.respond_to?(:uri_root)
           File.join(ENV['RACK_BASE_URI'].to_s, root_uri || '/', *paths)
@@ -245,6 +365,9 @@ module Padrino
         ##
         # Returns the timestamp mtime for an asset
         #
+        # @example
+        #   asset_timestamp("some/path/to/file.png") => "?154543678"
+        #
         def asset_timestamp(file_path)
           return nil if file_path =~ /\?/ || (self.class.respond_to?(:asset_stamp) && !self.class.asset_stamp)
           public_path = Padrino.root("public", file_path) if Padrino.respond_to?(:root)
@@ -256,6 +379,9 @@ module Padrino
         ##
         # Parses link_to options for given correct conditions
         #
+        # @example
+        #   parse_conditions("/some/url", :if => false) => true
+        #
         def parse_conditions(url, options)
           if options.has_key?(:if)
             condition = options.delete(:if)
@@ -271,6 +397,9 @@ module Padrino
         # Parses link_to options for given js declarations (remote, method, confirm)
         # Not destructive on options; returns updated options
         #
+        # parse_js_attributes(:remote => true, :confirm => "test", :method => :delete)
+        # => { "data-remote" => true, "data-method" => "delete", "data-confirm" => "test" }
+        #
         def parse_js_attributes(options)
           options = options.dup
           options["data-remote"] = "true" if options.delete(:remote)

data/lib/padrino-helpers/form_builder/abstract_form_builder.rb

@@ -9,7 +9,7 @@ module Padrino
           @object   = build_object(object)
           @options  = options
           raise "FormBuilder template must be initialized!" unless template
-          raise "FormBuilder object must be not be nil value. If there's no object, use a symbol instead! (i.e :user)" unless object
+          raise "FormBuilder object must not be a nil value. If there's no object, use a symbol instead! (i.e :user)" unless object
         end
 
         # f.error_messages