diff options
| author | Mike Gunderloy <MikeG1@larkfarm.com> | 2008-11-03 14:23:29 -0600 |
|---|---|---|
| committer | Mike Gunderloy <MikeG1@larkfarm.com> | 2008-11-03 14:23:29 -0600 |
| commit | e025f94cbe87ad66b8dcef40facccc2a7ad15411 (patch) | |
| tree | a0b1563743f1348637637e4b76e49bb2f0dccbe2 /railties | |
| parent | a32be96753a02d2cad31231445346c905768399f (diff) | |
| download | rails-e025f94cbe87ad66b8dcef40facccc2a7ad15411.tar.gz rails-e025f94cbe87ad66b8dcef40facccc2a7ad15411.tar.bz2 rails-e025f94cbe87ad66b8dcef40facccc2a7ad15411.zip | |
Formatting tweaks on Getting Started, regen Guides HTML
Diffstat (limited to 'railties')
4 files changed, 142 insertions, 60 deletions
diff --git a/railties/doc/guides/html/actioncontroller_basics.html b/railties/doc/guides/html/actioncontroller_basics.html index 32ddbe1f60..23d3c2e450 100644 --- a/railties/doc/guides/html/actioncontroller_basics.html +++ b/railties/doc/guides/html/actioncontroller_basics.html @@ -862,10 +862,9 @@ url - The entire URL used for the request. </li>
</ul></div>
<h4 id="_path_parameters_query_parameters_and_request_parameters">8.1.1. path_parameters, query_parameters and request_parameters</h4>
-<div class="para"><p>TODO: Does this belong here?</p></div>
<div class="para"><p>Rails collects all of the parameters sent along with the request in the <tt>params</tt> hash, whether they are sent as part of the query string or the post body. The request object has three accessors that give you access to these parameters depending on where they came from. The <tt>query_parameters</tt> hash contains parameters that were sent as part of the query string while the <tt>request_parameters</tt> hash contains parameters sent as part of the post body. The <tt>path_parameters</tt> hash contains parameters that were recognised by the routing as being part of the path leading to this particular controller and action.</p></div>
<h3 id="_the_response">8.2. The response</h3>
-<div class="para"><p>The response objects is not usually used directly, but is built up during the execution of the action and rendering of the data that is being sent back to the user, but sometimes - like in an after filter - it can be useful to access the response directly. Some of these accessor methods also have setters, allowing you to change their values.</p></div>
+<div class="para"><p>The response object is not usually used directly, but is built up during the execution of the action and rendering of the data that is being sent back to the user, but sometimes - like in an after filter - it can be useful to access the response directly. Some of these accessor methods also have setters, allowing you to change their values.</p></div>
<div class="ilist"><ul>
<li>
<p>
@@ -896,7 +895,7 @@ charset - The character set being used for the response. Default is "utf8". </div>
<h2 id="_http_basic_authentication">9. HTTP Basic Authentication</h2>
<div class="sectionbody">
-<div class="para"><p>Rails comes with built-in HTTP Basic authentication. This is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, we will create an administration section which will only be available by entering a username and a password into the browser's HTTP Basic dialog window. Using the built-in authentication is quite easy and only requires you to use one method, <a href="http://api.rubyonrails.org/classes/ActionController/HttpAuthentication/Basic/ControllerMethods.html#M000610">authenticate_or_request_with_http_basic</a>.</p></div>
+<div class="para"><p>Rails comes with built-in <a href="http://en.wikipedia.org/wiki/Basic_access_authentication">HTTP Basic authentication</a>. This is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, we will create an administration section which will only be available by entering a username and a password into the browser's HTTP Basic dialog window. Using the built-in authentication is quite easy and only requires you to use one method, <a href="http://api.rubyonrails.org/classes/ActionController/HttpAuthentication/Basic/ControllerMethods.html#M000610">authenticate_or_request_with_http_basic</a>.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
@@ -1031,7 +1030,7 @@ http://www.gnu.org/software/src-highlite --> </div>
<h2 id="_parameter_filtering">11. Parameter filtering</h2>
<div class="sectionbody">
-<div class="para"><p>Rails keeps a log file for each environment (development, test and production) in the "log" folder. These are extremely useful when debugging what's actually going on in your application, but in a live application you may not want every bit of information to be stored in the log file. The <a href="http://api.rubyonrails.org/classes/ActionController/Base.html#M000837">filter_parameter_logging</a> method can be used to filter out sensitive information from the log. It works by replacing certain keys in the <tt>params</tt> hash with "[FILTERED]" as they are written to the log. As an example, let's see how to filter all parameters with keys that include "password":</p></div>
+<div class="para"><p>Rails keeps a log file for each environment (development, test and production) in the "log" folder. These are extremely useful when debugging what's actually going on in your application, but in a live application you may not want every bit of information to be stored in the log file. The <a href="http://api.rubyonrails.org/classes/ActionController/Base.html#M000837">filter_parameter_logging</a> method can be used to filter out sensitive information from the log. It works by replacing certain values in the <tt>params</tt> hash with "[FILTERED]" as they are written to the log. As an example, let's see how to filter all parameters with keys that include "password":</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
diff --git a/railties/doc/guides/html/form_helpers.html b/railties/doc/guides/html/form_helpers.html index 28c317411b..7ff4a13a6a 100644 --- a/railties/doc/guides/html/form_helpers.html +++ b/railties/doc/guides/html/form_helpers.html @@ -220,6 +220,16 @@ ul#navMain { </ul> </li> + <li> + <a href="#_making_select_boxes_with_ease">Making select boxes with ease</a> + <ul> + + <li><a href="#_the_select_tag_and_options">The select tag and options</a></li> + + <li><a href="#_select_boxes_for_dealing_with_models">Select boxes for dealing with models</a></li> + + </ul> + </li> </ol> </div> @@ -227,7 +237,7 @@ ul#navMain { <h1>Rails form helpers</h1> <div id="preamble">
<div class="sectionbody">
-<div class="para"><p>Forms in web applications are an essential interface for user input. They are also often considered the most complex elements of HTML. Rails deals away with these complexities by providing numerous view helpers for generating form markup. However, since they have different use-cases, developers are required to know all the differences between similar helper methods before putting them to use.</p></div>
+<div class="para"><p>Forms in web applications are an essential interface for user input. However, form markup can quickly become tedious to write and maintain because of form control naming and their numerous attributes. Rails deals away with these complexities by providing view helpers for generating form markup. However, since they have different use-cases, developers are required to know all the differences between similar helper methods before putting them to use.</p></div>
<div class="para"><p>In this guide we will:</p></div>
<div class="ilist"><ul>
<li>
@@ -392,7 +402,7 @@ a submit element. <td class="icon">
<img src="./images/icons/warning.png" alt="Warning" />
</td>
-<td class="content">Do not delimit the second hash without doing so with the first hash, otherwise your method invocation will result in an ugly <tt>expecting tASSOC</tt> syntax error.</td>
+<td class="content">Do not delimit the second hash without doing so with the first hash, otherwise your method invocation will result in an <tt>expecting tASSOC</tt> syntax error.</td>
</tr></table>
</div>
<h3 id="_checkboxes_radio_buttons_and_other_controls">1.3. Checkboxes, radio buttons and other controls</h3>
@@ -431,7 +441,7 @@ output: <td class="icon">
<img src="./images/icons/important.png" alt="Important" />
</td>
-<td class="content">Always use labels for each checkbox and radio button. They associate text with a specific option, while also providing a larger clickable region.</td>
+<td class="content">Always use labels for each checkbox and radio button. They associate text with a specific option and provide a larger clickable region.</td>
</tr></table>
</div>
<div class="para"><p>Other form controls we might mention are the text area, password input and hidden input:</p></div>
@@ -458,7 +468,7 @@ output: </div>
<h3 id="_how_do_forms_with_put_or_delete_methods_work">1.4. How do forms with PUT or DELETE methods work?</h3>
<div class="para"><p>Rails framework encourages RESTful design of your applications, which means you'll be making a lot of "PUT" and "DELETE" requests (besides "GET" and "POST"). Still, most browsers <em>don't support</em> methods other than "GET" and "POST" when it comes to submitting forms. How does this work, then?</p></div>
-<div class="para"><p>Rails works around this issue by emulating other methods over POST with a hidden input named <tt>"<em>method"</tt> that is set to reflect the _real</em> method:</p></div>
+<div class="para"><p>Rails works around this issue by emulating other methods over POST with a hidden input named <tt>"_method"</tt> that is set to reflect the wanted method:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>form_tag(search_path, :method => "put")
@@ -563,6 +573,64 @@ form_for(@article)</tt></pre> </tr></table>
</div>
</div>
+<h2 id="_making_select_boxes_with_ease">3. Making select boxes with ease</h2>
+<div class="sectionbody">
+<div class="para"><p>Select boxes in HTML require a significant amount of markup (one <tt>OPTION</tt> element for each option to choose from), therefore it makes the most sense for them to be dynamically generated from data stored in arrays or hashes.</p></div>
+<div class="para"><p>Here is what our wanted markup might look like:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><select name="city_id" id="city_id">
+ <option value="1">Lisabon</option>
+ <option value="2">Madrid</option>
+ ...
+ <option value="12">Berlin</option>
+</select></tt></pre>
+</div></div>
+<div class="para"><p>Here we have a list of cities where their names are presented to the user, but internally we want to handle just their IDs so we keep them in value attributes. Let's see how Rails can help out here.</p></div>
+<h3 id="_the_select_tag_and_options">3.1. The select tag and options</h3>
+<div class="para"><p>The most generic helper is <tt>select_tag</tt>, which — as the name implies — simply generates the <tt>SELECT</tt> tag that encapsulates the options:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><%= select_tag(:city_id, '<option value="1">Lisabon</option>...') %></tt></pre>
+</div></div>
+<div class="para"><p>This is a start, but it doesn't dynamically create our option tags. We had to pass them in as a string.</p></div>
+<div class="para"><p>We can generate option tags with the <tt>options_for_select</tt> helper:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><%= options_for_select([['Lisabon', 1], ['Madrid', 2], ...]) %>
+
+output:
+
+<option value="1">Lisabon</option>
+<option value="2">Madrid</option>
+...</tt></pre>
+</div></div>
+<div class="para"><p>For input data we used a nested array where each element has two elements: visible value (name) and internal value (ID).</p></div>
+<div class="para"><p>Now you can combine <tt>select_tag</tt> and <tt>options_for_select</tt> to achieve the desired, complete markup:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><%= select_tag(:city_id, options_for_select(...)) %></tt></pre>
+</div></div>
+<div class="para"><p>Sometimes, depending on our application's needs, we also wish a specific option to be pre-selected. The <tt>options_for_select</tt> helper supports this with an optional second argument:</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt><%= options_for_select(cities_array, 2) %>
+
+output:
+
+<option value="1">Lisabon</option>
+<option value="2" selected="selected">Madrid</option>
+...</tt></pre>
+</div></div>
+<div class="para"><p>So whenever Rails sees that the internal value of an option being generated matches this value, it will add the <tt>selected</tt> attribute to that option.</p></div>
+<h3 id="_select_boxes_for_dealing_with_models">3.2. Select boxes for dealing with models</h3>
+<div class="para"><p>Until now we've covered how to make generic select boxes, but in most cases our form controls will be tied to a specific database model. So, to continue from our previous examples, let's assume that we have a "Person" model with a <tt>city_id</tt> attribute.</p></div>
+<div class="listingblock">
+<div class="content">
+<pre><tt>...</tt></pre>
+</div></div>
+<div class="para"><p>…</p></div>
+</div>
</div> </div> diff --git a/railties/doc/guides/html/getting_started_with_rails.html b/railties/doc/guides/html/getting_started_with_rails.html index 797ae2fb3a..0f93c2bbf1 100644 --- a/railties/doc/guides/html/getting_started_with_rails.html +++ b/railties/doc/guides/html/getting_started_with_rails.html @@ -1457,51 +1457,57 @@ http://www.gnu.org/software/src-highlite --> <div class="para"><p>At this point, it’s worth looking at some of the tools that Rails provides to eliminate duplication in your code. In particular, you can use <em>partials</em> to clean up duplication in views and <em>filters</em> to help with duplication in controllers.</p></div>
<h3 id="_using_partials_to_eliminate_view_duplication">7.1. Using Partials to Eliminate View Duplication</h3>
<div class="para"><p>As you saw earlier, the scaffold-generated views for the <tt>new</tt> and <tt>edit</tt> actions are largely identical. You can pull the shared code out into a <tt>partial</tt> template. This requires editing the new and edit views, and adding a new template:</p></div>
-<div class="para"><p><tt>new.html.erb</tt>:
-[source, ruby]</p></div>
+<div class="para"><p><tt>new.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content">
-<pre><tt><h1>New post</h1>
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #FF0000"><h1></span>New post<span style="color: #FF0000"></h1></span>
-<%= render :partial => "form" %>
+<span style="color: #FF0000"><%= render :partial =></span> <span style="color: #FF0000">"form"</span> <span style="color: #990000">%></span>
-<%= link_to 'Back', posts_path %></tt></pre>
-</div></div>
-<div class="para"><p><tt>edit.html.erb</tt>:
-[source, ruby]</p></div>
+<span style="color: #FF0000"><%= link_to 'Back', posts_path %></span>
+</tt></pre></div></div>
+<div class="para"><p><tt>edit.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content">
-<pre><tt><h1>Editing post</h1>
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #FF0000"><h1></span>Editing post<span style="color: #FF0000"></h1></span>
-<%= render :partial => "form" %>
+<span style="color: #FF0000"><%= render :partial =></span> <span style="color: #FF0000">"form"</span> <span style="color: #990000">%></span>
-<%= link_to 'Show', @post %> |
-<%= link_to 'Back', posts_path %></tt></pre>
-</div></div>
-<div class="para"><p><tt>_form.html.erb</tt>:
-[source, ruby]</p></div>
+<span style="color: #FF0000"><%= link_to 'Show', @post %></span> <span style="color: #990000">|</span>
+<span style="color: #FF0000"><%= link_to 'Back', posts_path %></span>
+</tt></pre></div></div>
+<div class="para"><p><tt>_form.html.erb</tt>:</p></div>
<div class="listingblock">
-<div class="content">
-<pre><tt><% form_for(@post) do |f| %>
- <%= f.error_messages %>
-
- <p>
- <%= f.label :name %><br />
- <%= f.text_field :name %>
- </p>
- <p>
- <%= f.label :title, "title" %><br />
- <%= f.text_field :title %>
- </p>
- <p>
- <%= f.label :content %><br />
- <%= f.text_area :content %>
- </p>
- <p>
- <%= f.submit "Save" %>
- </p>
-<% end %></tt></pre>
-</div></div>
+<div class="content"><!-- Generator: GNU source-highlight 2.9
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt><span style="color: #FF0000"><% form_for(@post) do |f| %></span>
+ <span style="color: #FF0000"><%= f.error_messages %></span>
+
+ <span style="color: #FF0000"><p></span>
+ <span style="color: #FF0000"><%= f.label :name %><br /></span>
+ <span style="color: #FF0000"><%= f.text_field :name %></span>
+ <span style="color: #FF0000"></p></span>
+ <span style="color: #FF0000"><p></span>
+ <span style="color: #FF0000"><%= f.label :title, "title" %><br /></span>
+ <span style="color: #FF0000"><%= f.text_field :title %></span>
+ <span style="color: #FF0000"></p></span>
+ <span style="color: #FF0000"><p></span>
+ <span style="color: #FF0000"><%= f.label :content %><br /></span>
+ <span style="color: #FF0000"><%= f.text_area :content %></span>
+ <span style="color: #FF0000"></p></span>
+ <span style="color: #FF0000"><p></span>
+ <span style="color: #FF0000"><%= f.submit "Save" %></span>
+ <span style="color: #FF0000"></p></span>
+<span style="color: #FF0000"><% end %></span>
+</tt></pre></div></div>
<div class="para"><p>Now, when Rails renders the <tt>new</tt> or <tt>edit</tt> view, it will insert the <tt>_form</tt> partial at the indicated point. Note the naming convention for partials: if you refer to a partial named <tt>form</tt> inside of a view, the corresponding file is <tt>_form.html.erb</tt>, with a leading underscore.</p></div>
<div class="para"><p>For more information on partials, refer to the <a href="../layouts_and_rendering.html">Layouts and Rending in Rails</a> guide.</p></div>
<h3 id="_using_filters_to_eliminate_controller_duplication">7.2. Using Filters to Eliminate Controller Duplication</h3>
@@ -1721,32 +1727,32 @@ http://www.gnu.org/software/src-highlite --> </li>
<li>
<p>
-+app/helpers/comments_helper.rb - A view helper file
+<tt>app/helpers/comments_helper.rb</tt> - A view helper file
</p>
</li>
<li>
<p>
-+app/views/comments/index.html.erb - The view for the index action
+<tt>app/views/comments/index.html.erb</tt> - The view for the index action
</p>
</li>
<li>
<p>
-+app/views/comments/show.html.erb - The view for the show action
+<tt>app/views/comments/show.html.erb</tt> - The view for the show action
</p>
</li>
<li>
<p>
-+app/views/comments/new.html.erb - The view for the new action
+<tt>app/views/comments/new.html.erb</tt> - The view for the new action
</p>
</li>
<li>
<p>
-+app/views/comments/edit.html.erb - The view for the edit action
+<tt>app/views/comments/edit.html.erb</tt> - The view for the edit action
</p>
</li>
<li>
<p>
-+test/functional/comments_controller_test.rb - The functional tests for the controller
+<tt>test/functional/comments_controller_test.rb</tt> - The functional tests for the controller
</p>
</li>
</ul></div>
@@ -1984,7 +1990,7 @@ http://www.gnu.org/software/src-highlite --> <div class="ilist"><ul>
<li>
<p>
-The [http://manuals.rubyonrails.org/]Ruby On Rails guides
+The <a href="http://manuals.rubyonrails.org/">Ruby On Rails guides</a>
</p>
</li>
<li>
@@ -2010,6 +2016,11 @@ The <a href="http://wiki.rubyonrails.org/rails">Rails wiki</a> <div class="ilist"><ul>
<li>
<p>
+November 3, 2008: Formatting patch from Dave Rothlisberger
+</p>
+</li>
+<li>
+<p>
November 1, 2008: First approved version by <a href="../authors.html#mgunderloy">Mike Gunderloy</a>
</p>
</li>
diff --git a/railties/doc/guides/source/getting_started_with_rails.txt b/railties/doc/guides/source/getting_started_with_rails.txt index c5bbc9e814..49cc63d04f 100644 --- a/railties/doc/guides/source/getting_started_with_rails.txt +++ b/railties/doc/guides/source/getting_started_with_rails.txt @@ -751,6 +751,7 @@ At this point, it’s worth looking at some of the tools that Rails provides to As you saw earlier, the scaffold-generated views for the +new+ and +edit+ actions are largely identical. You can pull the shared code out into a +partial+ template. This requires editing the new and edit views, and adding a new template: +new.html.erb+: + [source, ruby] ------------------------------------------------------- <h1>New post</h1> @@ -761,6 +762,7 @@ As you saw earlier, the scaffold-generated views for the +new+ and +edit+ action ------------------------------------------------------- +edit.html.erb+: + [source, ruby] ------------------------------------------------------- <h1>Editing post</h1> @@ -772,6 +774,7 @@ As you saw earlier, the scaffold-generated views for the +new+ and +edit+ action ------------------------------------------------------- +_form.html.erb+: + [source, ruby] ------------------------------------------------------- <% form_for(@post) do |f| %> @@ -979,12 +982,12 @@ $ script/generate controller Comments index show new edit This creates seven files: * +app/controllers/comments_controller.rb+ - The controller -* +app/helpers/comments_helper.rb - A view helper file -* +app/views/comments/index.html.erb - The view for the index action -* +app/views/comments/show.html.erb - The view for the show action -* +app/views/comments/new.html.erb - The view for the new action -* +app/views/comments/edit.html.erb - The view for the edit action -* +test/functional/comments_controller_test.rb - The functional tests for the controller +* +app/helpers/comments_helper.rb+ - A view helper file +* +app/views/comments/index.html.erb+ - The view for the index action +* +app/views/comments/show.html.erb+ - The view for the show action +* +app/views/comments/new.html.erb+ - The view for the new action +* +app/views/comments/edit.html.erb+ - The view for the edit action +* +test/functional/comments_controller_test.rb+ - The functional tests for the controller The controller will be generated with empty methods for each action that you specified in the call to +script/generate controller+: @@ -1216,7 +1219,7 @@ Note that each post has its own individual comments collection, accessible as +@ Now that you've seen your first Rails application, you should feel free to update it and experiment on your own. But you don't have to do everything without help. As you need assistance getting up and running with Rails, feel free to consult these support resources: -* The [http://manuals.rubyonrails.org/]Ruby On Rails guides +* The link:http://manuals.rubyonrails.org/[Ruby On Rails guides] * The link:http://groups.google.com/group/rubyonrails-talk[Ruby on Rails mailing list] * The #rubyonrails channel on irc.freenode.net * The link:http://wiki.rubyonrails.org/rails[Rails wiki] @@ -1225,6 +1228,7 @@ Now that you've seen your first Rails application, you should feel free to updat http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/2[Lighthouse ticket] +* November 3, 2008: Formatting patch from Dave Rothlisberger * November 1, 2008: First approved version by link:../authors.html#mgunderloy[Mike Gunderloy] * October 16, 2008: Revised based on feedback from Pratik Naik by link:../authors.html#mgunderloy[Mike Gunderloy] (not yet approved for publication) * October 13, 2008: First complete draft by link:../authors.html#mgunderloy[Mike Gunderloy] (not yet approved for publication) |