Commit progress on Action View Overview

1 files changed, 317 insertions, 2 deletions

diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile
index b8116dc88d..d449f54ee6 100644
--- a/railties/guides/source/action_view_overview.textile
+++ b/railties/guides/source/action_view_overview.textile
@@ -96,6 +96,8 @@ h3. Templates, Partials and Layouts
 
 TODO...
 
+TODO see http://guides.rubyonrails.org/layouts_and_rendering.html
+
 h3. Using Templates, Partials and Layouts in "The Rails Way"
 
 TODO...
@@ -168,9 +170,322 @@ h3. View Paths
 
 TODO...
 
-h3. Overview of all the helpers provided by AV
+h3. Overview of all the helpers provided by Action View
 
-TODO...
+h4. Active Record Helper
+
+The Active Record Helper makes it easier to create forms for records kept in instance variables. You may also want to review the "Rails Form helpers guide":form_helpers.html.
+
++error_message_on+
+
+Returns a string containing the error message attached to the method on the object if one exists.
+
+<ruby>
+error_message_on "post", "title"
+</ruby>
+
++error_messages_for+
+
+Returns a string with a DIV containing all of the error messages for the objects located as instance variables by the names given.
+
+<ruby>
+error_messages_for "post"
+</ruby>
+
++form+
+
+Returns a form with inputs for all attributes of the specified Active Record object. For example, let's say we have a +@post+ with attributes named +title+ of type +String+ and +body+ of type +Text+. Calling +form+ would produce a form to creating a new post with inputs for those attributes. 
+
+<ruby>
+form("post")
+</ruby>
+
+<ruby>
+<form action='/posts/create' method='post'>
+  <p>
+    <label for="post_title">Title</label><br />
+    <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" />
+  </p>
+  <p>
+    <label for="post_body">Body</label><br />
+    <textarea cols="40" id="post_body" name="post[body]" rows="20"></textarea>
+  </p>
+  <input name="commit" type="submit" value="Create" />
+</form>
+</ruby>
+
+Typically, +form_for+ is used instead of +form+ because it doesn't automatically include all of the model's attributes.
+
++input+
+
+Returns a default input tag for the type of object returned by the method. 
+
+For example, if +@post+ has an attribute +title+ mapped to a +String+ column that holds "Hello World":
+
+<ruby>
+input("post", "title") # => 
+  <input id="post_title" name="post[title]" size="30" type="text" value="Hello World" />
+</ruby>
+
+h4. Asset Tag Helper
+
+This module provides methods for generating HTML that links views to assets such as images, javascripts, stylesheets, and feeds. 
+
+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 +config/environment.rb+. For example, let's say your asset host is +assets.example.com+:
+
+<ruby>
+ActionController::Base.asset_host = "assets.example.com"
+image_tag("rails.png") # => <img src="http://assets.example.com/images/rails.png" alt="Rails" /> 
+</ruby>
+
++register_javascript_expansion+
+
+Register one or more javascript files to be included when symbol is passed to javascript_include_tag. This method is typically intended to be called from plugin initialization to register javascript files that the plugin installed in public/javascripts.
+
+<ruby>
+ActionView::Helpers::AssetTagHelper.register_javascript_expansion :monkey => ["head", "body", "tail"]
+
+javascript_include_tag :monkey # =>
+  <script type="text/javascript" src="/javascripts/head.js"></script>
+  <script type="text/javascript" src="/javascripts/body.js"></script>
+  <script type="text/javascript" src="/javascripts/tail.js"></script>
+</ruby>
+
++register_javascript_include_default+
+
+Register one or more additional JavaScript files to be included when +javascript_include_tag :defaults+ is called. This method is typically intended to be called from plugin initialization to register additional +.js+ files that the plugin installed in +public/javascripts+.
+
++register_stylesheet_expansion+
+
+Register one or more stylesheet files to be included when symbol is passed to +stylesheet_link_tag+. This method is typically intended to be called from plugin initialization to register stylesheet files that the plugin installed in +public/stylesheets+.
+
+<ruby>
+ActionView::Helpers::AssetTagHelper.register_stylesheet_expansion :monkey => ["head", "body", "tail"]
+
+stylesheet_link_tag :monkey # =>
+  <link href="/stylesheets/head.css"  media="screen" rel="stylesheet" type="text/css" />
+  <link href="/stylesheets/body.css"  media="screen" rel="stylesheet" type="text/css" />
+  <link href="/stylesheets/tail.css"  media="screen" rel="stylesheet" type="text/css" />
+</ruby>
+
++auto_discovery_link_tag+
+
+Returns a link tag that browsers and news readers can use to auto-detect an RSS or ATOM feed.
+
+<ruby>
+auto_discovery_link_tag(:rss, "http://www.example.com/feed.rss", {:title => "RSS Feed"}) # =>
+  <link rel="alternate" type="application/rss+xml" title="RSS Feed" href="http://www.example.com/feed" />
+</ruby>
+
++image_path+
+
+Computes the path to an image asset in the public images directory. Full paths from the document root will be passed through. Used internally by +image_tag+ to build the image path.
+
+<ruby>
+image_path("edit.png") # => /images/edit.png
+</ruby>
+
++image_tag+
+
+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.
+
+<ruby>
+image_tag("icon.png") # => <img src="/images/icon.png" alt="Icon" />
+</ruby>
+
++javascript_include_tag+
+
+Returns an html script tag for each of the sources provided. You can pass in the filename (+.js+ extension is optional) of javascript files that exist in your +public/javascripts+ directory for inclusion into the current page or you can pass the full path relative to your document root.
+
+<ruby>
+javascript_include_tag "common" # =>
+  <script type="text/javascript" src="/javascripts/common.js"></script>  
+</ruby>
+
+To include the Prototype and Scriptaculous javascript libraries in your application, pass +:defaults+ as the source. When using +:defaults+, if an +application.js+ file exists in your +public/javascripts+ directory, it will be included as well. 
+
+<ruby>
+javascript_include_tag :defaults
+</ruby>
+
+You can also include all javascripts in the javascripts directory using +:all+ as the source.
+
+<ruby>
+javascript_include_tag :all
+</ruby>
+
+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).
+
+<ruby>
+javascript_include_tag :all, :cache => true # => 
+  <script type="text/javascript" src="/javascripts/all.js"></script>  
+</ruby>
+
++javascript_path+
+
+Computes the path to a javascript asset in the +public/javascripts+ directory. If the source filename has no extension, +.js+ will be appended. Full paths from the document root will be passed through. Used internally by +javascript_include_tag+ to build the script path.
+
+<ruby>
+javascript_path "common" # => /javascripts/common.js
+</ruby>
+
++stylesheet_link_tag+
+
+Returns a stylesheet link tag for the sources specified as arguments. If you don't specify an extension, +.css+ will be appended automatically. 
+
+<ruby>
+stylesheet_link_tag "application" # =>
+  <link href="/stylesheets/application.css" media="screen" rel="stylesheet" type="text/css" />
+</ruby>
+
+You can also include all styles in the stylesheet directory using :all as the source:
+
+<ruby>
+stylesheet_link_tag :all
+</ruby>
+
+You can also cache multiple stylesheets into one file, which requires less HTTP connections 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). 
+
+<ruby>
+stylesheet_link_tag :all, :cache => true
+  <link href="/stylesheets/all.css"  media="screen" rel="stylesheet" type="text/css" />
+</ruby>
+
++stylesheet_path+
+
+Computes the path to a stylesheet asset in the public stylesheets directory. If the source filename has no extension, .css will be appended. Full paths from the document root will be passed through. Used internally by stylesheet_link_tag to build the stylesheet path.
+
+<ruby>
+stylesheet_path "application" # => /stylesheets/application.css
+</ruby>
+
+h4. Atom Feed Helper
+
++atom_feed+
+
+This helper makes building an ATOM feed easy. Here's a full usage example:
+
+*config/routes.rb*
+
+<ruby>
+map.resources :posts
+</ruby>
+
+*app/controllers/posts_controller.rb*
+
+<ruby>
+def index
+  @posts = Post.find(:all)
+
+  respond_to do |format|
+    format.html
+    format.atom
+  end
+end
+</ruby>
+
+*app/views/posts/index.atom.builder*
+
+<ruby>
+atom_feed do |feed|
+  feed.title("Posts Index")
+  feed.updated((@posts.first.created_at))
+
+  for post in @posts
+    feed.entry(post) do |entry|
+      entry.title(post.title)
+      entry.content(post.body, :type => 'html')
+
+      entry.author do |author|
+        author.name(post.author_name)
+      end
+    end
+  end
+end
+</ruby>
+
+h4. Benchmark Helper
+
++benchmark+
+
+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.
+
+<ruby>
+<% benchmark "Process data files" do %>
+  <%= expensive_files_operation %>
+<% end %>  
+</ruby>
+
+This would add something like "Process data files (0.34523)" to the log, which you can then use to compare timings when optimizing your code.
+
+h4. Cache Helper
+
++cache+
+
+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.
+
+<ruby>
+<% cache do %>
+  <%= render :partial => "shared/footer" %>
+<% end %>
+</ruby>
+
+h4. Capture Helper
+
++capture+
+
+The +capture+ method allows you to extract part of a template into a variable. You can then use this variable anywhere in your templates or layout.
+
+<ruby>
+<% @greeting = capture do %>
+  <p>Welcome! The date and time is <%= Time.now %></p>
+<% end %>
+<ruby>
+
+The captured variable can then be used anywhere else.
+
+<ruby>
+<html>
+  <head>
+    <title>Welcome!</title>
+  </head>
+  <body>
+    <%= @greeting %>
+  </body>
+</html>
+</ruby>  
+
++content_for+
+
+Calling +content_for+ stores a block of markup in an identifier for later use. You can make subsequent calls to the stored content in other templates or the layout by passing the identifier as an argument to +yield+.
+
+For example, let's say we have a standard application layout, but also a special page that requires certain Javascript that the rest of the site doesn't need. We can use +content_for+ to include this Javascript on our special page without fattening up the rest of the site.
+
+*app/views/layouts/application.html.erb*
+
+<ruby>
+<html>
+  <head>
+    <title>Welcome!</title>
+    <%= yield :special_script %>
+  </head>
+  <body>
+    <p>Welcome! The date and time is <%= Time.now %></p>
+  </body>
+</html>
+</ruby>
+
+*app/views/posts/special.html.erb*
+
+<ruby>
+<p>This is a special page.</p>
+
+<% content_for :special_script do %>
+  <script type="text/javascript">alert('Hello!')</script>
+<% end %>  
+</ruby>
+
+TODO continue at http://ap.rubyonrails.org/ on ActionView::Helpers::DateHelper
 
 h3. Localized Views