padrino-helpers 0.9.6 → 0.9.7

data/README.rdoc

@@ -10,7 +10,7 @@ methods should be very familiar to anyone who has used rails view helpers.
 
 Output helpers are a collection of important methods for managing, capturing and displaying output
 in various ways and is used frequently to support higher-level helper functions. There are
-three output helpers worth mentioning: <tt>content_for</tt>, <tt>capture_html</tt>, and <tt>concat_content</tt> 
+three output helpers worth mentioning: <tt>content_for</tt>, <tt>capture_html</tt>, and <tt>concat_content</tt>
 
 The content_for functionality supports capturing content and then rendering this into a different place
 such as within a layout. One such popular example is including assets onto the layout from a template:
@@ -21,7 +21,7 @@ such as within a layout. One such popular example is including assets onto the l
     <%= stylesheet_link_tag 'index', 'custom' %>
   <% end %>
   ...
-  
+
 Added to a template, this will capture the includes from the block and allow them to be yielded into the layout:
 
   # app/views/layout.erb
@@ -32,8 +32,8 @@ Added to a template, this will capture the includes from the block and allow the
     <%= yield_content :assets %>
   </head>
   ...
-  
-This will automatically insert the contents of the block (in this case a stylesheet include) into 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.
 
 The capture_html and the concat_content methods allow content to be manipulated and stored for use in building
@@ -46,9 +46,9 @@ these in constructing a simplified 'form_tag' helper which accepts a block.
     inner_form_html = capture_html(&block)
     concat_content '<form>' + inner_form_html + '</form>'
   end
-  
+
 This will capture the template body passed into the form_tag block and then append the content
-to the template through the use of <tt>concat_content</tt>. Note have been built to work for both haml and erb 
+to the template through the use of <tt>concat_content</tt>. Note have been built to work for both haml and erb
 templates using the same syntax.
 
 For more information on using output helpers, check out the guide for
@@ -64,12 +64,12 @@ the tag contains 'content' within then <tt>content_tag</tt> is used. For example
 
   tag(:br, :style => ‘clear:both’) => <br style="clear:both" />
   content_tag(:p, "demo", :class => ‘light’) => <p class="light">demo</p>
-  
+
 The input_tag is used to build tags that are related to accepting input from the user:
 
   input_tag :text, :class => "demo" => <input type='text' class='demo' />
   input_tag :password, :value => "secret", :class => "demo"
-  
+
 Note that all of these accept html options and result in returning a string containing html tags.
 
 For more information on using tag helpers, check out the guide for
@@ -78,7 +78,7 @@ For more information on using tag helpers, check out the guide for
 === Asset Helpers
 
 Asset helpers are intended to help insert useful html onto a view template such as 'flash' notices,
-hyperlinks, mail_to links, images, stylesheets and javascript. An example of their uses would be on a 
+hyperlinks, mail_to links, images, stylesheets and javascript. An example of their uses would be on a
 simple view template:
 
   # app/views/example.haml
@@ -95,7 +95,7 @@ simple view template:
 
 For more information on using asset helpers, check out the guide for
 {Padrino Helpers}[http://wiki.github.com/padrino/padrino-framework/application-helpers].
-  
+
 === Form Helpers
 
 Form helpers are the 'standard' form tag helpers you would come to expect when building forms. A simple
@@ -120,7 +120,7 @@ example of constructing a non-object form would be:
 
 For more information on using form helpers, check out the guide for
 {Padrino Helpers}[http://wiki.github.com/padrino/padrino-framework/application-helpers].
-    
+
 === FormBuilders
 
 Form builders are full-featured objects allowing the construction of complex object-based forms
@@ -151,7 +151,7 @@ A form_for using these basic fields might look like:
         = location.text_field :city
     %p
       = f.submit "Create", :class => 'button'
-  
+
 There is also an additional StandardFormBuilder which builds on the abstract fields that can be used within a form_for.
 
 A form_for using these standard fields might be:
@@ -186,7 +186,7 @@ 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
-to sanitize user content before displaying this on a template. <tt>js_escape_html</tt> is used for 
+to sanitize user content before displaying this on a template. <tt>js_escape_html</tt> is used for
 passing javascript information from a js template to a javascript function.
 
   escape_html('<hello>&<goodbye>') # => &lt;hello&gt;&amp;&lt;goodbye&gt;
@@ -194,7 +194,7 @@ passing javascript information from a js template to a javascript function.
 There is also an alias for escape_html called <tt>h</tt> for even easier usage within templates.
 
 Format helpers also includes a number of useful text manipulation functions such as <tt>simple_format</tt>,
-<tt>pluralize</tt>, <tt>word_wrap</tt>, and <tt>truncate</tt>. 
+<tt>pluralize</tt>, <tt>word_wrap</tt>, and <tt>truncate</tt>.
 
   simple_format("hello\nworld") # => "<p>hello<br/>world</p>"
   pluralize(2, 'person') => '2 people'
@@ -208,26 +208,26 @@ For more information on using the format helpers, check out the guide for
 
 === Render Helpers
 
-This component provides a number of rendering helpers making the process of displaying templates a bit easier. 
+This component provides a number of rendering helpers making the process of displaying templates a bit easier.
 This plugin also has support for useful additions such as partials (with support for :collection) for the templating system.
 
 Using render plugin helpers is extremely simple. If you want to render an erb template in your view path:
 
   render :erb, 'path/to/erb/template'
-  
+
 or using haml templates works just as well:
 
   render :haml, 'path/to/haml/template'
-  
+
 There is also a method which renders the first view matching the path and removes the need to define an engine:
 
   render 'path/to/any/template'
-  
+
 Finally, we have the all-important partials support for rendering mini-templates onto a page:
 
   partial 'photo/_item', :object => @photo, :locals => { :foo => 'bar' }
   partial 'photo/_item', :collection => @photos
-  
+
 For more information on using the render and partial helpers, check out the guide for
 {Padrino Helpers}[http://wiki.github.com/padrino/padrino-framework/application-helpers].
 

data/Rakefile

@@ -61,4 +61,4 @@ Rake::RDocTask.new do |rdoc|
   rdoc.title = "padrino-helpers #{version}"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
-end
+end

data/VERSION

@@ -1 +1 @@
-0.9.6
+0.9.7

data/lib/padrino-helpers.rb

@@ -10,14 +10,14 @@ 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. 
-  # There are helpers for generating tags, forms, links, images, and more. 
+  # This component provides a great deal 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
@@ -25,9 +25,9 @@ module Padrino
     #   Padrino::Helpers::FormatHelpers
     #   Padrino::Helpers::RenderHelpers
     #   Padrino::Helpers::NumberHelpers
-    # 
+    #
     # for Padrino::Application
-    # 
+    #
     def self.registered(app)
       app.set :default_builder, 'StandardFormBuilder'
       app.helpers Padrino::Helpers::OutputHelpers

data/lib/padrino-helpers/asset_tag_helpers.rb

@@ -3,11 +3,11 @@ module Padrino
     module AssetTagHelpers
       ##
       # Creates a div to display the flash of given type if it exists
-      # 
+      #
       # ==== Examples
-      #   # => <div class="notice">flash-notice</div>
+      #   # Generates: <div class="notice">flash-notice</div>
       #   flash_tag(:notice, :id => 'flash-notice')
-      # 
+      #
       def flash_tag(kind, options={})
         flash_text = flash[kind]
         return '' if flash_text.blank?
@@ -17,18 +17,18 @@ module Padrino
 
       ##
       # Creates a link element with given name, url and options
-      # 
+      #
       # ==== Examples
-      # 
+      #
       #   link_to 'click me', '/dashboard', :class => 'linky'
       #   link_to 'click me', '/dashboard', :if => @foo.present?
       #   link_to 'click me', '/dashboard', :unless => @foo.empty?
       #   link_to 'click me', '/dashboard', :unless => :current
       #   link_to('/dashboard', :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
-      # 
+      #
       def link_to(*args, &block)
         options = args.extract_options!
         anchor  = "##{CGI.escape options.delete(:anchor).to_s}" if options[:anchor]
@@ -50,16 +50,16 @@ module Padrino
 
       ##
       # Creates a form containing a single button that submits to the url.
-      # 
+      #
       # ==== Examples
-      # 
+      #
       #   # 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
-      # 
+      #
       def button_to(*args, &block)
         name, url = args[0], args[1]
         options   = args.extract_options!
@@ -73,167 +73,189 @@ module Padrino
         content_tag('form', inner_form_html, options)
       end
 
+      ##
+      # 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" />
+      #   feed_tag :atom, url(:blog, :posts, :format => :atom), :title => "ATOM"
+      #   # Generates: <link type="application/rss+xml" rel="alternate" href="/blog/posts.rss" title="rss" />
+      #   feed_tag :rss, url(:blog, :posts, :format => :rss)
+      #
+      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
-      #   mail_to "me@demo.com"             => <a href="mailto:me@demo.com">me@demo.com</a>
-      #   mail_to "me@demo.com", "My Email" => <a href="mailto:me@demo.com">My Email</a>
-      # 
+      #
+      #   # 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"
+      #
       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', '@')
         mail_href = "mailto:#{email}"; mail_href << "?#{mail_query}" if mail_query.present?
-        link_to (caption || email), mail_href, html_options
+        link_to((caption || email), mail_href, html_options)
       end
 
       ##
       # Creates a meta element with the content and given options
-      # 
+      #
       # ==== Examples
-      # 
-      #   meta_tag "weblog,news", :name => "keywords"                         => <meta name="keywords" content="weblog,news">
-      #   meta_tag "text/html; charset=UTF-8", :http-equiv => "Content-Type"  => <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-      # 
+      #
+      #   # 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"
+      #
       def meta_tag(content, options={})
         options.reverse_merge!("content" => content)
         tag(:meta, options)
       end
 
+      ##
+      # Generates a favicon link. looks inside images folder
+      #
+      # ==== Examples
+      #
+      #   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={})
+        type = File.extname(source).gsub('.','')
+        options = options.dup.reverse_merge!(:href => image_path(source), :rel => 'icon', :type => "image/#{type}")
+        tag(:link, options)
+      end
+
       ##
       # Creates an image element with given url and options
-      # 
+      #
       # ==== Examples
-      # 
+      #
       #   image_tag('icons/avatar.png')
-      # 
+      #
       def image_tag(url, options={})
         options.reverse_merge!(:src => image_path(url))
         tag(:img, options)
       end
 
       ##
-      # 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+ 
+      # 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+
       # like app/public/stylesheets for inclusion. You can provide also a full path.
-      # 
+      #
       # ==== Examples
-      # 
+      #
       #   stylesheet_link_tag 'style', 'application', 'layout'
-      # 
+      #
       def stylesheet_link_tag(*sources)
         options = sources.extract_options!.symbolize_keys
-        sources.collect { |sheet| stylesheet_tag(sheet, options) }.join("\n")
+        options.reverse_merge!(:media => 'screen', :rel => 'stylesheet', :type => 'text/css')
+        sources.collect { |source|
+          tag(:link, options.reverse_merge(:href => asset_path(:css, source)))
+        }.join("\n")
       end
 
       ##
-      # 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+ 
+      # 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+
       # like app/public/javascript for inclusion. You can provide also a full path.
-      # 
+      #
       # ==== Examples
-      # 
+      #
       #   javascript_include_tag 'application', :extjs
-      # 
+      #
       def javascript_include_tag(*sources)
         options = sources.extract_options!.symbolize_keys
-        sources.collect { |script| javascript_tag(script, options) }.join("\n")
+        options.reverse_merge!(:type => 'text/javascript', :content => "")
+        sources.collect { |source|
+          tag(:script, options.reverse_merge(:src => asset_path(:js, source)))
+        }.join("\n")
       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+
       # like app/public/images for inclusion. You can provide also a full path.
-      # 
+      #
       # ==== Examples
-      # 
-      #   image_path("foo.jpg") => "yourapp/public/images/foo.jpg" 
-      # 
+      #
+      #   # Generates: /images/foo.jpg?1269008689
+      #   image_path("foo.jpg")
+      #
       def image_path(src)
-        src.gsub!(/\s/, '')
-        src =~ %r{^\s*(/|http)} ? src : uri_root_path('images', src)
+        asset_path(:images, src)
       end
 
       ##
-      # Generate a +link+ tag for stylesheet.
-      # 
+      # Returns the path to the specified asset (css or javascript)
+      #
       # ==== Examples
-      # 
-      #   stylesheet_tag('style', :media => 'screen')
-      # 
-      def stylesheet_tag(source, options={})
-        options = options.dup.reverse_merge!(:href => stylesheet_path(source), :media => 'screen', :rel => 'stylesheet', :type => 'text/css')
-        tag(:link, options)
-      end
-      ##
-      # Generate a link +script+ for javascript.
-      # 
-      # ==== Examples
-      # 
-      #   javascript_tag 'application', :src => '/javascripts/base/application.js'
-      # 
-      def javascript_tag(source, options={})
-        options = options.dup.reverse_merge!(:src => javascript_path(source), :type => 'text/javascript', :content => "")
-        tag(:script, options)
-      end
-
-      ##
-      # Returns the javascript_path appending the default javascripts path if necessary
-      # 
-      def javascript_path(source)
-        return source if source =~ /^http/
-        source        = source.to_s.gsub(/\.js$/, '')
-        source_name   = source; source_name << ".js" unless source =~ /\.js/
-        result_path   = source_name if source =~ %r{^/} # absolute path
-        result_path ||= uri_root_path("javascripts", source_name)
-        return result_path if result_path =~ /\?/
-        public_path = Padrino.root("public", result_path)
-        stamp = File.exist?(public_path) ? File.mtime(public_path).to_i : Time.now.to_i
-        "#{result_path}?#{stamp}"
-      end
-
-      ##
-      # Returns the stylesheet_path appending the default stylesheets path if necessary
-      # 
-      def stylesheet_path(source)
+      #
+      #   # Generates: /javascripts/application.js?1269008689
+      #   asset_path :js, :application
+      #
+      #   # Generates: /stylesheets/application.css?1269008689
+      #   asset_path :css, :application
+      #
+      #   # Generates: /images/example.jpg?1269008689
+      #   asset_path :images, 'example.jpg'
+      #
+      def asset_path(kind, source)
         return source if source =~ /^http/
-        source        = source.to_s.gsub(/\.css$/, '')
-        source_name   = source; source_name << ".css" unless source =~ /\.css/
-        result_path   = source_name if source =~ %r{^/} # absolute path
-        result_path ||= uri_root_path("stylesheets", source_name)
-        return result_path if result_path =~ /\?/
-        public_path   = Padrino.root("public", result_path)
-        stamp         = File.exist?(public_path) ? File.mtime(public_path).to_i : Time.now.to_i
-        "#{result_path}?#{stamp}"
-      end
-      
-      ##
-      # Generates a favicon link. looks inside images folder
-      # 
-      # ==== Examples
-      # 
-      #   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={})
-        type = File.extname(source).gsub('.','')
-        options = options.dup.reverse_merge!(:href => image_path(source), :rel => 'icon', :type => "image/#{type}")
-        tag(:link, options)
+        asset_folder  = case kind
+          when :css then 'stylesheets'
+          when :js  then 'javascripts'
+          else kind.to_s
+        end
+        source = source.to_s.gsub(/\s/, '')
+        ignore_extension = (asset_folder.to_s == kind.to_s) # don't append extension
+        source << ".#{kind}" unless ignore_extension or source =~ /\.#{kind}/
+        result_path   = source if source =~ %r{^/} # absolute path
+        result_path ||= uri_root_path(asset_folder, source)
+        timestamp = asset_timestamp(result_path)
+        "#{result_path}#{timestamp}"
       end
 
       private
+
         ##
-        # Returns the uri root of the application.'
-        # 
+        # Returns the uri root of the application.
+        #
         def uri_root_path(*paths)
           root_uri = self.class.uri_root if self.class.respond_to?(:uri_root)
           File.join(root_uri || '/', *paths)
         end
 
+        ##
+        # Returns the timestamp mtime for an asset
+        #
+        def asset_timestamp(file_path)
+          return nil if file_path =~ /\?/
+          public_path = Padrino.root("public", file_path) if Padrino.respond_to?(:root)
+          stamp = Time.now.to_i unless public_path && File.exist?(public_path)
+          stamp ||= File.mtime(public_path).to_i
+          "?#{stamp}"
+        end
+
         ##
         # Parse link_to options for give correct conditions
-        # 
+        #
         def parse_conditions(url, options)
           if options.has_key?(:if)
             condition = options.delete(:if)
@@ -246,4 +268,4 @@ module Padrino
         end
     end # AssetTagHelpers
   end # Helpers
-end # Padrino
+end # Padrino