Permalink
Browse files

Massive documentation update for all helpers (closes #8223, #8177, #8175

, #8108, #7977, #7972, #7971, #7969) [jeremymcanally]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@7106 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
1 parent 8aefa3e commit b00e6a984df51a2f891c2a4c819ac2ab08359eed @dhh dhh committed Jun 23, 2007
@@ -4,27 +4,38 @@
module ActionView
module Helpers #:nodoc:
- # Provides methods for linking an HTML page together with other assets such
- # as images, javascripts, stylesheets, and feeds. You can direct Rails to
- # link to assets from a dedicated assets server by setting ActionController::Base.asset_host
- # in your environment.rb. These methods do not verify the assets exist before
- # linking to them.
+ # This module provides methods for generating HTML that links views to assets such
+ # as images, javascripts, stylesheets, and feeds. These methods do not verify
+ # the assets exist before linking to them.
+ #
+ # === Using asset hosts
+ # By default, Rails links to these assets on the current host in the public
+ # folder, but you can direct Rails to link to assets from a dedicated assets server by
+ # setting ActionController::Base.asset_host in your environment.rb. For example,
+ # let's say your asset host is assets.example.com.
#
# ActionController::Base.asset_host = "assets.example.com"
# image_tag("rails.png")
# => <img src="http://assets.example.com/images/rails.png" alt="Rails" />
# stylesheet_include_tag("application")
# => <link href="http://assets.example.com/stylesheets/application.css" media="screen" rel="Stylesheet" type="text/css" />
#
- # Since browsers typically open at most two connections to a single host,
- # your assets often wait in single file for their turn to load.
+ # This is useful since browsers typically open at most two connections to a single host,
+ # which means your assets often wait in single file for their turn to load. You can
+ # alleviate this by using a %d wildcard in <tt>asset_host</tt> (for example, "assets%d.example.com")
+ # to automatically distribute asset requests among four hosts (e.g., assets0.example.com through assets3.example.com)
+ # so browsers will open eight connections rather than two.
+ #
+ # image_tag("rails.png")
+ # => <img src="http://assets0.example.com/images/rails.png" alt="Rails" />
+ # stylesheet_include_tag("application")
+ # => <link href="http://assets3.example.com/stylesheets/application.css" media="screen" rel="Stylesheet" type="text/css" />
#
- # Use a %d wildcard in asset_host (asset%d.myapp.com) to automatically
- # distribute asset requests among four hosts (asset0-asset3.myapp.com)
- # so browsers will open eight connections rather than two. Use wildcard
- # DNS to CNAME the wildcard to your real asset host.
+ # To do this, you can either setup four actual hosts, or you can use wildcard DNS to CNAME
+ # the wildcard to a single asset host. You can read more about setting up your DNS CNAME records from
+ # your ISP.
#
- # Note: this is purely a browser performance optimization and is not meant
+ # Note: This is purely a browser performance optimization and is not meant
# for server load balancing. See http://www.die.net/musings/page_load_time/
# for background.
module AssetTagHelper
@@ -37,19 +48,24 @@ module AssetTagHelper
# <tt>:atom</tt>. Control the link options in url_for format using the
# +url_options+. You can modify the LINK tag itself in +tag_options+.
#
- # Tag Options:
+ # ==== Options:
# * <tt>:rel</tt> - Specify the relation of this link, defaults to "alternate"
# * <tt>:type</tt> - Override the auto-generated mime type
# * <tt>:title</tt> - Specify the title of the link, defaults to the +type+
#
+ # ==== Examples
# auto_discovery_link_tag # =>
- # <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.curenthost.com/controller/action" />
+ # <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.currenthost.com/controller/action" />
# auto_discovery_link_tag(:atom) # =>
- # <link rel="alternate" type="application/atom+xml" title="ATOM" href="http://www.curenthost.com/controller/action" />
+ # <link rel="alternate" type="application/atom+xml" title="ATOM" href="http://www.currenthost.com/controller/action" />
# auto_discovery_link_tag(:rss, {:action => "feed"}) # =>
- # <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.curenthost.com/controller/feed" />
+ # <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.currenthost.com/controller/feed" />
# auto_discovery_link_tag(:rss, {:action => "feed"}, {:title => "My RSS"}) # =>
- # <link rel="alternate" type="application/rss+xml" title="My RSS" href="http://www.curenthost.com/controller/feed" />
+ # <link rel="alternate" type="application/rss+xml" title="My RSS" href="http://www.currenthost.com/controller/feed" />
+ # auto_discovery_link_tag(:rss, {:controller => "news", :action => "feed"}) # =>
+ # <link rel="alternate" type="application/rss+xml" title="RSS" href="http://www.currenthost.com/news/feed" />
+ # auto_discovery_link_tag(:rss, "http://www.example.com/feed.rss", {:title => "Example RSS"}) # =>
+ # <link rel="alternate" type="application/rss+xml" title="Example RSS" href="http://www.example.com/feed" />
def auto_discovery_link_tag(type = :rss, url_options = {}, tag_options = {})
tag(
"link",
@@ -65,9 +81,12 @@ def auto_discovery_link_tag(type = :rss, url_options = {}, tag_options = {})
# Full paths from the document root will be passed through.
# Used internally by javascript_include_tag to build the script path.
#
+ # ==== Examples
# javascript_path "xmlhr" # => /javascripts/xmlhr.js
# javascript_path "dir/xmlhr.js" # => /javascripts/dir/xmlhr.js
# javascript_path "/dir/xmlhr" # => /dir/xmlhr.js
+ # javascript_path "http://www.railsapplication.com/js/xmlhr" # => http://www.railsapplication.com/js/xmlhr.js
+ # javascript_path "http://www.railsapplication.com/js/xmlhr.js" # => http://www.railsapplication.com/js/xmlhr.js
def javascript_path(source)
compute_public_path(source, 'javascripts', 'js')
end
@@ -85,22 +104,35 @@ def javascript_path(source)
# javascripts directory, it will be included as well. You can modify the
# html attributes of the script tag by passing a hash as the last argument.
#
+ # ==== Examples
# javascript_include_tag "xmlhr" # =>
# <script type="text/javascript" src="/javascripts/xmlhr.js"></script>
#
+ # javascript_include_tag "xmlhr.js" # =>
+ # <script type="text/javascript" src="/javascripts/xmlhr.js"></script>
+ #
# javascript_include_tag "common.javascript", "/elsewhere/cools" # =>
# <script type="text/javascript" src="/javascripts/common.javascript"></script>
# <script type="text/javascript" src="/elsewhere/cools.js"></script>
#
+ # javascript_include_tag "http://www.railsapplication.com/xmlhr" # =>
+ # <script type="text/javascript" src="http://www.railsapplication.com/xmlhr.js"></script>
+ #
+ # javascript_include_tag "http://www.railsapplication.com/xmlhr.js" # =>
+ # <script type="text/javascript" src="http://www.railsapplication.com/xmlhr.js"></script>
+ #
# javascript_include_tag :defaults # =>
# <script type="text/javascript" src="/javascripts/prototype.js"></script>
# <script type="text/javascript" src="/javascripts/effects.js"></script>
# ...
- # <script type="text/javascript" src="/javascripts/application.js"></script> *see below
+ # <script type="text/javascript" src="/javascripts/application.js"></script> <!-- * see below -->
#
# * = The application.js file is only referenced if it exists
#
- # You can also include all javascripts in the javascripts directory using :all as the source:
+ # Though it's not really recommended practice, if you need to extend the default JavaScript set for any reason
+ # (e.g., you're going to be using a certain .js file in every action), then take a look at the register_javascript_include_default method.
+ #
+ # You can also include all javascripts in the javascripts directory using <tt>:all</tt> as the source:
#
# javascript_include_tag :all # =>
# <script type="text/javascript" src="/javascripts/prototype.js"></script>
@@ -110,16 +142,17 @@ def javascript_path(source)
# <script type="text/javascript" src="/javascripts/shop.js"></script>
# <script type="text/javascript" src="/javascripts/checkout.js"></script>
#
- # Note that the default javascript files will be included first. So Prototype and Scriptaculous are available for
- # all subsequently included files. They
+ # Note that the default javascript files will be included first. So Prototype and Scriptaculous are available to
+ # all subsequently included files.
#
# == Caching multiple javascripts into one
#
- # You can also cache multiple javascripts into one file, which requires less HTTP connections and can better be
+ # You can also cache multiple javascripts into one file, which requires less HTTP connections to download and can better be
# compressed by gzip (leading to faster transfers). Caching will only happen if ActionController::Base.perform_caching
- # is set to true (which is the case by default for the Rails production environment, but not for the development
- # environment). Examples:
+ # is set to <tt>true</tt> (which is the case by default for the Rails production environment, but not for the development
+ # environment).
#
+ # ==== Examples
# javascript_include_tag :all, :cache => true # when ActionController::Base.perform_caching is false =>
# <script type="text/javascript" src="/javascripts/prototype.js"></script>
# <script type="text/javascript" src="/javascripts/effects.js"></script>
@@ -168,7 +201,7 @@ def javascript_include_tag(*sources)
# Register one or more additional JavaScript files to be included when
# <tt>javascript_include_tag :defaults</tt> is called. This method is
- # only intended to be called from plugin initialization to register additional
+ # typically intended to be called from plugin initialization to register additional
# .js files that the plugin installed in <tt>public/javascripts</tt>.
def self.register_javascript_include_default(*sources)
@@javascript_default_sources.concat(sources)
@@ -183,9 +216,12 @@ def self.reset_javascript_include_default #:nodoc:
# Full paths from the document root will be passed through.
# Used internally by stylesheet_link_tag to build the stylesheet path.
#
+ # ==== Examples
# stylesheet_path "style" # => /stylesheets/style.css
# stylesheet_path "dir/style.css" # => /stylesheets/dir/style.css
# stylesheet_path "/dir/style.css" # => /dir/style.css
+ # stylesheet_path "http://www.railsapplication.com/css/style" # => http://www.railsapplication.com/css/style.css
+ # stylesheet_path "http://www.railsapplication.com/css/style.js" # => http://www.railsapplication.com/css/style.css
def stylesheet_path(source)
compute_public_path(source, 'stylesheets', 'css')
end
@@ -194,12 +230,22 @@ def stylesheet_path(source)
# you don't specify an extension, .css will be appended automatically.
# You can modify the link attributes by passing a hash as the last argument.
#
+ # ==== Examples
# stylesheet_link_tag "style" # =>
# <link href="/stylesheets/style.css" media="screen" rel="Stylesheet" type="text/css" />
#
+ # stylesheet_link_tag "style.css" # =>
+ # <link href="/stylesheets/style.css" media="screen" rel="Stylesheet" type="text/css" />
+ #
+ # stylesheet_link_tag "http://www.railsapplication.com/style.css" # =>
+ # <link href="http://www.railsapplication.com/style.css" media="screen" rel="Stylesheet" type="text/css" />
+ #
# stylesheet_link_tag "style", :media => "all" # =>
# <link href="/stylesheets/style.css" media="all" rel="Stylesheet" type="text/css" />
#
+ # stylesheet_link_tag "style", :media => "print" # =>
+ # <link href="/stylesheets/style.css" media="print" rel="Stylesheet" type="text/css" />
+ #
# stylesheet_link_tag "random.styles", "/css/stylish" # =>
# <link href="/stylesheets/random.styles" media="screen" rel="Stylesheet" type="text/css" />
# <link href="/css/stylish.css" media="screen" rel="Stylesheet" type="text/css" />
@@ -218,6 +264,7 @@ def stylesheet_path(source)
# is set to true (which is the case by default for the Rails production environment, but not for the development
# environment). Examples:
#
+ # ==== Examples
# stylesheet_link_tag :all, :cache => true # when ActionController::Base.perform_caching is false =>
# <link href="/stylesheets/style1.css" media="screen" rel="Stylesheet" type="text/css" />
# <link href="/stylesheets/styleB.css" media="screen" rel="Stylesheet" type="text/css" />
@@ -271,9 +318,11 @@ def stylesheet_link_tag(*sources)
# Used internally by image_tag to build the image path. Passing
# a filename without an extension is deprecated.
#
+ # ==== Examples
# image_path("edit.png") # => /images/edit.png
# image_path("icons/edit.png") # => /images/icons/edit.png
# image_path("/icons/edit.png") # => /icons/edit.png
+ # image_path("http://www.railsapplication.com/img/edit.png") # => http://www.railsapplication.com/img/edit.png
def image_path(source)
unless (source.split("/").last || source).include?(".") || source.blank?
ActiveSupport::Deprecation.warn(
@@ -289,7 +338,9 @@ def image_path(source)
# Returns an html image tag for the +source+. The +source+ can be a full
# path or a file that exists in your public images directory. Note that
# specifying a filename without the extension is now deprecated in Rails.
- # You can add html attributes using the +options+. The +options+ supports
+ #
+ # ==== Options
+ # You can add HTML attributes using the +options+. The +options+ supports
# two additional keys for convienence and conformance:
#
# * <tt>:alt</tt> - If no alt text is given, the file name part of the
@@ -298,12 +349,17 @@ def image_path(source)
# width="30" and height="45". <tt>:size</tt> will be ignored if the
# value is not in the correct format.
#
+ # ==== Examples
# image_tag("icon.png") # =>
# <img src="/images/icon.png" alt="Icon" />
# image_tag("icon.png", :size => "16x10", :alt => "Edit Entry") # =>
# <img src="/images/icon.png" width="16" height="10" alt="Edit Entry" />
# image_tag("/icons/icon.gif", :size => "16x16") # =>
# <img src="/icons/icon.gif" width="16" height="16" alt="Icon" />
+ # image_tag("/icons/icon.gif", :height => '32', :width => '32') # =>
+ # <img alt="Icon" height="32" src="/icons/icon.gif" width="32" />
+ # image_tag("/icons/icon.gif", :class => "menu_icon") # =>
+ # <img alt="Icon" class="menu_icon" src="/icons/icon.gif" />
def image_tag(source, options = {})
options.symbolize_keys!
@@ -2,17 +2,24 @@
module ActionView
module Helpers
+ # This helper offers a method to measure the execution time of a block
+ # in a template.
module BenchmarkHelper
- # Measures the execution time of a block in a template and reports the result to the log. Example:
+ # Allows you to measure the execution time of a block
+ # in a template and records the result to the log. Wrap this block around
+ # expensive operations or possible bottlenecks to get a time reading
+ # for the operation. For example, let's say you thought your file
+ # processing method was taking too long; you could wrap it in a benchmark block.
#
- # <% benchmark "Notes section" do %>
- # <%= expensive_notes_operation %>
+ # <% benchmark "Process data files" do %>
+ # <%= expensive_files_operation %>
# <% end %>
#
- # Will add something like "Notes section (0.34523)" to the log.
+ # That would add something like "Process data files (0.34523)" to the log,
+ # which you can then use to compare timings when optimizing your code.
#
# You may give an optional logger level as the second argument
- # (:debug, :info, :warn, :error). The default is :info.
+ # (:debug, :info, :warn, :error); the default value is :info.
def benchmark(message = "Benchmarking", level = :info)
if @logger
real = Benchmark.realtime { yield }
@@ -1,7 +1,36 @@
module ActionView
module Helpers
+ # This helper to exposes a method for caching of view fragments.
# See ActionController::Caching::Fragments for usage instructions.
module CacheHelper
+ # A method for caching fragments of a view rather than an entire
+ # action or page. This technique is useful caching pieces like
+ # menus, lists of news topics, static HTML fragments, and so on.
+ # This method takes a block that contains the content you wish
+ # to cache. See ActionController::Caching::Fragments for more
+ # information.
+ #
+ # ==== Examples
+ # If you wanted to cache a navigation menu, you could do the
+ # following.
+ #
+ # <% cache do %>
+ # <%= render :partial => "menu" %>
+ # <% end %>
+ #
+ # You can also cache static content...
+ #
+ # <% cache do %>
+ # <p>Hello users! Welcome to our website!</p>
+ # <% end %>
+ #
+ # ...and static content mixed with RHTML content.
+ #
+ # <% cache do %>
+ # Topics:
+ # <%= render :partial => "topics", :collection => @topic_list %>
+ # <i>Topics listed alphabetically</i>
+ # <% end %>
def cache(name = {}, &block)
@controller.cache_erb_fragment(block, name)
end
Oops, something went wrong. Retry.

0 comments on commit b00e6a9

Please sign in to comment.