Skip to content
This repository
Browse code

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.
  • Loading branch information...
commit d6ecce66f4e125531875006eea8022b73fe135b5 1 parent 9226b3e
Michael Hartl authored May 15, 2008
63  actionpack/lib/action_view/helpers/url_helper.rb
@@ -120,17 +120,72 @@ def url_for(options = {})
120 120
       # exception.
121 121
       #
122 122
       # ==== Examples
  123
+      # Because it relies on url_for, link_to supports both older-style controller/action/id arguments
  124
+      # and newer RESTful routes.  Current Rails style favors
  125
+      # RESTful routes whenever possible, so use 
  126
+      #
  127
+      #   link_to "Profile", profile_path(@profile)
  128
+      #   # => <a href="/profiles/1">Profile</a>
  129
+      #
  130
+      # or the even pithier
  131
+      #
  132
+      #   link_to "Profile", @profile
  133
+      #   # => <a href="/profiles/1">Profile</a>
  134
+      #
  135
+      # in place of the more verbose
  136
+      #
  137
+      #   link_to "Profile", :controller => "profiles", :action => "show", :id => @profile.id
  138
+      #   # => <a href="/profiles/show/1">Profile</a>
  139
+      # 
  140
+      # Similarly, 
  141
+      #
  142
+      #   link_to "Profiles", profiles_path
  143
+      #   # => <a href="/profiles">Profiles</a>
  144
+      #
  145
+      # is better than
  146
+      #
  147
+      #   link_to "Profiles", :controller => "profiles"
  148
+      #   # => <a href="/profiles">Profiles</a>
  149
+      #
  150
+      # Classes and ids for CSS are easy to produce:
  151
+      #
  152
+      #   link_to "Articles", articles_path, :id => "news", :class => "article"
  153
+      #   # => <a href="/articles" class="article" id="news">Articles</a>
  154
+      #
  155
+      # Be careful when using the older argument style, as an extra literal hash is needed:
  156
+      #
  157
+      #   link_to "Articles", { :controller => "articles" }, :id => "news", :class => "article"
  158
+      #   # => <a href="/articles" class="article" id="news">Articles</a>
  159
+      #
  160
+      # Leaving the hash off gives the wrong link:
  161
+      #
  162
+      #   link_to "WRONG!", :controller => "articles", :id => "news", :class => "article"
  163
+      #   # => <a href="/articles/index/news?class=article">WRONG!</a>
  164
+      #
  165
+      # link_to can also produce links with anchors or query strings:
  166
+      #
  167
+      #   link_to "Comment wall", profile_path(@profile, :anchor => "wall")
  168
+      #   # => <a href="/profiles/1#wall">Comment wall</a>
  169
+      #
  170
+      #   link_to "Ruby on Rails search", :controller => "searches", :query => "ruby on rails"
  171
+      #   # => <a href="/searches?query=ruby+on+rails">Ruby on Rails search</a>
  172
+      #
  173
+      #   link_to "Nonsense search", searches_path(:foo => "bar", :baz => "quux")
  174
+      #   # => <a href="/searches?foo=bar&amp;baz=quux">Nonsense search</a>
  175
+      #
  176
+      # The three options specfic to link_to (<tt>confirm</tt>, <tt>popup</tt>, and <tt>method</tt>) are used as follows:
  177
+      #
123 178
       #   link_to "Visit Other Site", "http://www.rubyonrails.org/", :confirm => "Are you sure?"
124 179
       #   # => <a href="http://www.rubyonrails.org/" onclick="return confirm('Are you sure?');">Visit Other Site</a>
125 180
       #
126 181
       #   link_to "Help", { :action => "help" }, :popup => true
127 182
       #   # => <a href="/testing/help/" onclick="window.open(this.href);return false;">Help</a>
128 183
       #
129  
-      #   link_to "View Image", { :action => "view" }, :popup => ['new_window_name', 'height=300,width=600']
130  
-      #   # => <a href="/testing/view/" onclick="window.open(this.href,'new_window_name','height=300,width=600');return false;">View Image</a>
  184
+      #   link_to "View Image", @image, :popup => ['new_window_name', 'height=300,width=600']
  185
+      #   # => <a href="/images/9" onclick="window.open(this.href,'new_window_name','height=300,width=600');return false;">View Image</a>
131 186
       #
132  
-      #   link_to "Delete Image", { :action => "delete", :id => @image.id }, :confirm => "Are you sure?", :method => :delete
133  
-      #   # => <a href="/testing/delete/9/" onclick="if (confirm('Are you sure?')) { var f = document.createElement('form'); 
  187
+      #   link_to "Delete Image", @image, :confirm => "Are you sure?", :method => :delete
  188
+      #   # => <a href="/images/9" onclick="if (confirm('Are you sure?')) { var f = document.createElement('form'); 
134 189
       #        f.style.display = 'none'; this.parentNode.appendChild(f); f.method = 'POST'; f.action = this.href;
135 190
       #        var m = document.createElement('input'); m.setAttribute('type', 'hidden'); m.setAttribute('name', '_method'); 
136 191
       #        m.setAttribute('value', 'delete'); f.appendChild(m);f.submit(); };return false;">Delete Image</a>

0 notes on commit d6ecce6

Please sign in to comment.
Something went wrong with that request. Please try again.