From d6ecce66f4e125531875006eea8022b73fe135b5 Mon Sep 17 00:00:00 2001
From: Michael Hartl <michael@michaelhartl.com>
Date: Thu, 15 May 2008 10:46:40 -0700
Subject: Expanded and updated the link_to documentation link_to is the primary
 interface much of the Rails URL machinery, including url_for and routes.  The
 new examples (with explanations) are designed to reflect this importance, and
 are especially designed to be friendly to less experienced Rails programmers.
  The new docs are also updated to use RESTful routes.

---
 actionpack/lib/action_view/helpers/url_helper.rb | 63 ++++++++++++++++++++++--
 1 file changed, 59 insertions(+), 4 deletions(-)

(limited to 'actionpack')

diff --git a/actionpack/lib/action_view/helpers/url_helper.rb b/actionpack/lib/action_view/helpers/url_helper.rb
index 375ebfcdc5..856cb0d79f 100644
--- a/actionpack/lib/action_view/helpers/url_helper.rb
+++ b/actionpack/lib/action_view/helpers/url_helper.rb
@@ -120,17 +120,72 @@ module ActionView
       # exception.
       #
       # ==== Examples
+      # Because it relies on url_for, link_to supports both older-style controller/action/id arguments
+      # and newer RESTful routes.  Current Rails style favors
+      # RESTful routes whenever possible, so use 
+      #
+      #   link_to "Profile", profile_path(@profile)
+      #   # => <a href="/profiles/1">Profile</a>
+      #
+      # or the even pithier
+      #
+      #   link_to "Profile", @profile
+      #   # => <a href="/profiles/1">Profile</a>
+      #
+      # in place of the more verbose
+      #
+      #   link_to "Profile", :controller => "profiles", :action => "show", :id => @profile.id
+      #   # => <a href="/profiles/show/1">Profile</a>
+      # 
+      # Similarly, 
+      #
+      #   link_to "Profiles", profiles_path
+      #   # => <a href="/profiles">Profiles</a>
+      #
+      # is better than
+      #
+      #   link_to "Profiles", :controller => "profiles"
+      #   # => <a href="/profiles">Profiles</a>
+      #
+      # Classes and ids for CSS are easy to produce:
+      #
+      #   link_to "Articles", articles_path, :id => "news", :class => "article"
+      #   # => <a href="/articles" class="article" id="news">Articles</a>
+      #
+      # Be careful when using the older argument style, as an extra literal hash is needed:
+      #
+      #   link_to "Articles", { :controller => "articles" }, :id => "news", :class => "article"
+      #   # => <a href="/articles" class="article" id="news">Articles</a>
+      #
+      # Leaving the hash off gives the wrong link:
+      #
+      #   link_to "WRONG!", :controller => "articles", :id => "news", :class => "article"
+      #   # => <a href="/articles/index/news?class=article">WRONG!</a>
+      #
+      # link_to can also produce links with anchors or query strings:
+      #
+      #   link_to "Comment wall", profile_path(@profile, :anchor => "wall")
+      #   # => <a href="/profiles/1#wall">Comment wall</a>
+      #
+      #   link_to "Ruby on Rails search", :controller => "searches", :query => "ruby on rails"
+      #   # => <a href="/searches?query=ruby+on+rails">Ruby on Rails search</a>
+      #
+      #   link_to "Nonsense search", searches_path(:foo => "bar", :baz => "quux")
+      #   # => <a href="/searches?foo=bar&amp;baz=quux">Nonsense search</a>
+      #
+      # The three options specfic to link_to (<tt>confirm</tt>, <tt>popup</tt>, and <tt>method</tt>) are used as follows:
+      #
       #   link_to "Visit Other Site", "http://www.rubyonrails.org/", :confirm => "Are you sure?"
       #   # => <a href="http://www.rubyonrails.org/" onclick="return confirm('Are you sure?');">Visit Other Site</a>
       #
       #   link_to "Help", { :action => "help" }, :popup => true
       #   # => <a href="/testing/help/" onclick="window.open(this.href);return false;">Help</a>
       #
-      #   link_to "View Image", { :action => "view" }, :popup => ['new_window_name', 'height=300,width=600']
-      #   # => <a href="/testing/view/" onclick="window.open(this.href,'new_window_name','height=300,width=600');return false;">View Image</a>
+      #   link_to "View Image", @image, :popup => ['new_window_name', 'height=300,width=600']
+      #   # => <a href="/images/9" onclick="window.open(this.href,'new_window_name','height=300,width=600');return false;">View Image</a>
       #
-      #   link_to "Delete Image", { :action => "delete", :id => @image.id }, :confirm => "Are you sure?", :method => :delete
-      #   # => <a href="/testing/delete/9/" onclick="if (confirm('Are you sure?')) { var f = document.createElement('form'); 
+      #   link_to "Delete Image", @image, :confirm => "Are you sure?", :method => :delete
+      #   # => <a href="/images/9" onclick="if (confirm('Are you sure?')) { var f = document.createElement('form'); 
       #        f.style.display = 'none'; this.parentNode.appendChild(f); f.method = 'POST'; f.action = this.href;
       #        var m = document.createElement('input'); m.setAttribute('type', 'hidden'); m.setAttribute('name', '_method'); 
       #        m.setAttribute('value', 'delete'); f.appendChild(m);f.submit(); };return false;">Delete Image</a>
-- 
cgit v1.2.3