rails 4.2.6.rc1 → 5.2.8.1

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of rails might be problematic. Click here for more details.

Files changed (218) hide show
  1. checksums.yaml +5 -5
  2. data/README.md +24 -12
  3. metadata +54 -248
  4. data/guides/CHANGELOG.md +0 -73
  5. data/guides/Rakefile +0 -79
  6. data/guides/assets/images/akshaysurve.jpg +0 -0
  7. data/guides/assets/images/belongs_to.png +0 -0
  8. data/guides/assets/images/book_icon.gif +0 -0
  9. data/guides/assets/images/bullet.gif +0 -0
  10. data/guides/assets/images/chapters_icon.gif +0 -0
  11. data/guides/assets/images/check_bullet.gif +0 -0
  12. data/guides/assets/images/credits_pic_blank.gif +0 -0
  13. data/guides/assets/images/csrf.png +0 -0
  14. data/guides/assets/images/edge_badge.png +0 -0
  15. data/guides/assets/images/favicon.ico +0 -0
  16. data/guides/assets/images/feature_tile.gif +0 -0
  17. data/guides/assets/images/footer_tile.gif +0 -0
  18. data/guides/assets/images/fxn.png +0 -0
  19. data/guides/assets/images/getting_started/article_with_comments.png +0 -0
  20. data/guides/assets/images/getting_started/challenge.png +0 -0
  21. data/guides/assets/images/getting_started/confirm_dialog.png +0 -0
  22. data/guides/assets/images/getting_started/forbidden_attributes_for_new_article.png +0 -0
  23. data/guides/assets/images/getting_started/form_with_errors.png +0 -0
  24. data/guides/assets/images/getting_started/index_action_with_edit_link.png +0 -0
  25. data/guides/assets/images/getting_started/new_article.png +0 -0
  26. data/guides/assets/images/getting_started/rails_welcome.png +0 -0
  27. data/guides/assets/images/getting_started/routing_error_no_controller.png +0 -0
  28. data/guides/assets/images/getting_started/routing_error_no_route_matches.png +0 -0
  29. data/guides/assets/images/getting_started/show_action_for_articles.png +0 -0
  30. data/guides/assets/images/getting_started/template_is_missing_articles_new.png +0 -0
  31. data/guides/assets/images/getting_started/unknown_action_create_for_articles.png +0 -0
  32. data/guides/assets/images/getting_started/unknown_action_new_for_articles.png +0 -0
  33. data/guides/assets/images/grey_bullet.gif +0 -0
  34. data/guides/assets/images/habtm.png +0 -0
  35. data/guides/assets/images/has_many.png +0 -0
  36. data/guides/assets/images/has_many_through.png +0 -0
  37. data/guides/assets/images/has_one.png +0 -0
  38. data/guides/assets/images/has_one_through.png +0 -0
  39. data/guides/assets/images/header_backdrop.png +0 -0
  40. data/guides/assets/images/header_tile.gif +0 -0
  41. data/guides/assets/images/i18n/demo_html_safe.png +0 -0
  42. data/guides/assets/images/i18n/demo_localized_pirate.png +0 -0
  43. data/guides/assets/images/i18n/demo_translated_en.png +0 -0
  44. data/guides/assets/images/i18n/demo_translated_pirate.png +0 -0
  45. data/guides/assets/images/i18n/demo_translation_missing.png +0 -0
  46. data/guides/assets/images/i18n/demo_untranslated.png +0 -0
  47. data/guides/assets/images/icons/README +0 -5
  48. data/guides/assets/images/icons/callouts/1.png +0 -0
  49. data/guides/assets/images/icons/callouts/10.png +0 -0
  50. data/guides/assets/images/icons/callouts/11.png +0 -0
  51. data/guides/assets/images/icons/callouts/12.png +0 -0
  52. data/guides/assets/images/icons/callouts/13.png +0 -0
  53. data/guides/assets/images/icons/callouts/14.png +0 -0
  54. data/guides/assets/images/icons/callouts/15.png +0 -0
  55. data/guides/assets/images/icons/callouts/2.png +0 -0
  56. data/guides/assets/images/icons/callouts/3.png +0 -0
  57. data/guides/assets/images/icons/callouts/4.png +0 -0
  58. data/guides/assets/images/icons/callouts/5.png +0 -0
  59. data/guides/assets/images/icons/callouts/6.png +0 -0
  60. data/guides/assets/images/icons/callouts/7.png +0 -0
  61. data/guides/assets/images/icons/callouts/8.png +0 -0
  62. data/guides/assets/images/icons/callouts/9.png +0 -0
  63. data/guides/assets/images/icons/caution.png +0 -0
  64. data/guides/assets/images/icons/example.png +0 -0
  65. data/guides/assets/images/icons/home.png +0 -0
  66. data/guides/assets/images/icons/important.png +0 -0
  67. data/guides/assets/images/icons/next.png +0 -0
  68. data/guides/assets/images/icons/note.png +0 -0
  69. data/guides/assets/images/icons/prev.png +0 -0
  70. data/guides/assets/images/icons/tip.png +0 -0
  71. data/guides/assets/images/icons/up.png +0 -0
  72. data/guides/assets/images/icons/warning.png +0 -0
  73. data/guides/assets/images/nav_arrow.gif +0 -0
  74. data/guides/assets/images/oscardelben.jpg +0 -0
  75. data/guides/assets/images/polymorphic.png +0 -0
  76. data/guides/assets/images/radar.png +0 -0
  77. data/guides/assets/images/rails4_features.png +0 -0
  78. data/guides/assets/images/rails_guides_kindle_cover.jpg +0 -0
  79. data/guides/assets/images/rails_guides_logo.gif +0 -0
  80. data/guides/assets/images/rails_logo_remix.gif +0 -0
  81. data/guides/assets/images/session_fixation.png +0 -0
  82. data/guides/assets/images/tab_grey.gif +0 -0
  83. data/guides/assets/images/tab_info.gif +0 -0
  84. data/guides/assets/images/tab_note.gif +0 -0
  85. data/guides/assets/images/tab_red.gif +0 -0
  86. data/guides/assets/images/tab_yellow.gif +0 -0
  87. data/guides/assets/images/tab_yellow.png +0 -0
  88. data/guides/assets/images/vijaydev.jpg +0 -0
  89. data/guides/assets/javascripts/guides.js +0 -59
  90. data/guides/assets/javascripts/jquery.min.js +0 -4
  91. data/guides/assets/javascripts/responsive-tables.js +0 -43
  92. data/guides/assets/javascripts/syntaxhighlighter/shBrushAS3.js +0 -59
  93. data/guides/assets/javascripts/syntaxhighlighter/shBrushAppleScript.js +0 -75
  94. data/guides/assets/javascripts/syntaxhighlighter/shBrushBash.js +0 -59
  95. data/guides/assets/javascripts/syntaxhighlighter/shBrushCSharp.js +0 -65
  96. data/guides/assets/javascripts/syntaxhighlighter/shBrushColdFusion.js +0 -100
  97. data/guides/assets/javascripts/syntaxhighlighter/shBrushCpp.js +0 -97
  98. data/guides/assets/javascripts/syntaxhighlighter/shBrushCss.js +0 -91
  99. data/guides/assets/javascripts/syntaxhighlighter/shBrushDelphi.js +0 -55
  100. data/guides/assets/javascripts/syntaxhighlighter/shBrushDiff.js +0 -41
  101. data/guides/assets/javascripts/syntaxhighlighter/shBrushErlang.js +0 -52
  102. data/guides/assets/javascripts/syntaxhighlighter/shBrushGroovy.js +0 -67
  103. data/guides/assets/javascripts/syntaxhighlighter/shBrushJScript.js +0 -52
  104. data/guides/assets/javascripts/syntaxhighlighter/shBrushJava.js +0 -57
  105. data/guides/assets/javascripts/syntaxhighlighter/shBrushJavaFX.js +0 -58
  106. data/guides/assets/javascripts/syntaxhighlighter/shBrushPerl.js +0 -72
  107. data/guides/assets/javascripts/syntaxhighlighter/shBrushPhp.js +0 -88
  108. data/guides/assets/javascripts/syntaxhighlighter/shBrushPlain.js +0 -33
  109. data/guides/assets/javascripts/syntaxhighlighter/shBrushPowerShell.js +0 -74
  110. data/guides/assets/javascripts/syntaxhighlighter/shBrushPython.js +0 -64
  111. data/guides/assets/javascripts/syntaxhighlighter/shBrushRuby.js +0 -55
  112. data/guides/assets/javascripts/syntaxhighlighter/shBrushSass.js +0 -94
  113. data/guides/assets/javascripts/syntaxhighlighter/shBrushScala.js +0 -51
  114. data/guides/assets/javascripts/syntaxhighlighter/shBrushSql.js +0 -66
  115. data/guides/assets/javascripts/syntaxhighlighter/shBrushVb.js +0 -56
  116. data/guides/assets/javascripts/syntaxhighlighter/shBrushXml.js +0 -69
  117. data/guides/assets/javascripts/syntaxhighlighter/shCore.js +0 -17
  118. data/guides/assets/stylesheets/fixes.css +0 -16
  119. data/guides/assets/stylesheets/kindle.css +0 -11
  120. data/guides/assets/stylesheets/main.css +0 -713
  121. data/guides/assets/stylesheets/print.css +0 -52
  122. data/guides/assets/stylesheets/reset.css +0 -43
  123. data/guides/assets/stylesheets/responsive-tables.css +0 -50
  124. data/guides/assets/stylesheets/style.css +0 -13
  125. data/guides/assets/stylesheets/syntaxhighlighter/shCore.css +0 -226
  126. data/guides/assets/stylesheets/syntaxhighlighter/shCoreDefault.css +0 -328
  127. data/guides/assets/stylesheets/syntaxhighlighter/shCoreDjango.css +0 -331
  128. data/guides/assets/stylesheets/syntaxhighlighter/shCoreEclipse.css +0 -339
  129. data/guides/assets/stylesheets/syntaxhighlighter/shCoreEmacs.css +0 -324
  130. data/guides/assets/stylesheets/syntaxhighlighter/shCoreFadeToGrey.css +0 -328
  131. data/guides/assets/stylesheets/syntaxhighlighter/shCoreMDUltra.css +0 -324
  132. data/guides/assets/stylesheets/syntaxhighlighter/shCoreMidnight.css +0 -324
  133. data/guides/assets/stylesheets/syntaxhighlighter/shCoreRDark.css +0 -324
  134. data/guides/assets/stylesheets/syntaxhighlighter/shThemeDefault.css +0 -117
  135. data/guides/assets/stylesheets/syntaxhighlighter/shThemeDjango.css +0 -120
  136. data/guides/assets/stylesheets/syntaxhighlighter/shThemeEclipse.css +0 -128
  137. data/guides/assets/stylesheets/syntaxhighlighter/shThemeEmacs.css +0 -113
  138. data/guides/assets/stylesheets/syntaxhighlighter/shThemeFadeToGrey.css +0 -117
  139. data/guides/assets/stylesheets/syntaxhighlighter/shThemeMDUltra.css +0 -113
  140. data/guides/assets/stylesheets/syntaxhighlighter/shThemeMidnight.css +0 -113
  141. data/guides/assets/stylesheets/syntaxhighlighter/shThemeRDark.css +0 -113
  142. data/guides/assets/stylesheets/syntaxhighlighter/shThemeRailsGuides.css +0 -116
  143. data/guides/bug_report_templates/action_controller_gem.rb +0 -47
  144. data/guides/bug_report_templates/action_controller_master.rb +0 -54
  145. data/guides/bug_report_templates/active_record_gem.rb +0 -40
  146. data/guides/bug_report_templates/active_record_master.rb +0 -49
  147. data/guides/bug_report_templates/generic_gem.rb +0 -15
  148. data/guides/bug_report_templates/generic_master.rb +0 -26
  149. data/guides/rails_guides/generator.rb +0 -248
  150. data/guides/rails_guides/helpers.rb +0 -53
  151. data/guides/rails_guides/indexer.rb +0 -68
  152. data/guides/rails_guides/kindle.rb +0 -119
  153. data/guides/rails_guides/levenshtein.rb +0 -37
  154. data/guides/rails_guides/markdown/renderer.rb +0 -82
  155. data/guides/rails_guides/markdown.rb +0 -167
  156. data/guides/rails_guides.rb +0 -63
  157. data/guides/source/2_2_release_notes.md +0 -435
  158. data/guides/source/2_3_release_notes.md +0 -621
  159. data/guides/source/3_0_release_notes.md +0 -611
  160. data/guides/source/3_1_release_notes.md +0 -559
  161. data/guides/source/3_2_release_notes.md +0 -568
  162. data/guides/source/4_0_release_notes.md +0 -279
  163. data/guides/source/4_1_release_notes.md +0 -730
  164. data/guides/source/4_2_release_notes.md +0 -877
  165. data/guides/source/_license.html.erb +0 -2
  166. data/guides/source/_welcome.html.erb +0 -23
  167. data/guides/source/action_controller_overview.md +0 -1192
  168. data/guides/source/action_mailer_basics.md +0 -757
  169. data/guides/source/action_view_overview.md +0 -1561
  170. data/guides/source/active_job_basics.md +0 -339
  171. data/guides/source/active_model_basics.md +0 -554
  172. data/guides/source/active_record_basics.md +0 -374
  173. data/guides/source/active_record_callbacks.md +0 -413
  174. data/guides/source/active_record_migrations.md +0 -1018
  175. data/guides/source/active_record_postgresql.md +0 -433
  176. data/guides/source/active_record_querying.md +0 -1781
  177. data/guides/source/active_record_validations.md +0 -1179
  178. data/guides/source/active_support_core_extensions.md +0 -3857
  179. data/guides/source/active_support_instrumentation.md +0 -488
  180. data/guides/source/api_documentation_guidelines.md +0 -361
  181. data/guides/source/asset_pipeline.md +0 -1304
  182. data/guides/source/association_basics.md +0 -2245
  183. data/guides/source/autoloading_and_reloading_constants.md +0 -1311
  184. data/guides/source/caching_with_rails.md +0 -379
  185. data/guides/source/command_line.md +0 -625
  186. data/guides/source/configuring.md +0 -1072
  187. data/guides/source/contributing_to_ruby_on_rails.md +0 -628
  188. data/guides/source/credits.html.erb +0 -80
  189. data/guides/source/debugging_rails_applications.md +0 -861
  190. data/guides/source/development_dependencies_install.md +0 -289
  191. data/guides/source/documents.yaml +0 -205
  192. data/guides/source/engines.md +0 -1412
  193. data/guides/source/form_helpers.md +0 -1024
  194. data/guides/source/generators.md +0 -676
  195. data/guides/source/getting_started.md +0 -2086
  196. data/guides/source/i18n.md +0 -1087
  197. data/guides/source/index.html.erb +0 -28
  198. data/guides/source/initialization.md +0 -704
  199. data/guides/source/kindle/copyright.html.erb +0 -1
  200. data/guides/source/kindle/layout.html.erb +0 -27
  201. data/guides/source/kindle/rails_guides.opf.erb +0 -52
  202. data/guides/source/kindle/toc.html.erb +0 -24
  203. data/guides/source/kindle/toc.ncx.erb +0 -64
  204. data/guides/source/kindle/welcome.html.erb +0 -5
  205. data/guides/source/layout.html.erb +0 -140
  206. data/guides/source/layouts_and_rendering.md +0 -1227
  207. data/guides/source/maintenance_policy.md +0 -78
  208. data/guides/source/nested_model_forms.md +0 -228
  209. data/guides/source/plugins.md +0 -444
  210. data/guides/source/rails_application_templates.md +0 -266
  211. data/guides/source/rails_on_rack.md +0 -336
  212. data/guides/source/routing.md +0 -1155
  213. data/guides/source/ruby_on_rails_guides_guidelines.md +0 -127
  214. data/guides/source/security.md +0 -1024
  215. data/guides/source/testing.md +0 -1132
  216. data/guides/source/upgrading_ruby_on_rails.md +0 -1186
  217. data/guides/source/working_with_javascript_in_rails.md +0 -407
  218. data/guides/w3c_validator.rb +0 -97
@@ -1,1561 +0,0 @@
1
- Action View Overview
2
- ====================
3
-
4
- After reading this guide, you will know:
5
-
6
- * What Action View is and how to use it with Rails.
7
- * How best to use templates, partials, and layouts.
8
- * What helpers are provided by Action View and how to make your own.
9
- * How to use localized views.
10
-
11
- --------------------------------------------------------------------------------
12
-
13
- What is Action View?
14
- --------------------
15
-
16
- Action View and Action Controller are the two major components of Action Pack. In Rails, web requests are handled by Action Pack, which splits the work into a controller part (performing the logic) and a view part (rendering a template). Typically, Action Controller will be concerned with communicating with the database and performing CRUD actions where necessary. Action View is then responsible for compiling the response.
17
-
18
- Action View templates are written using embedded Ruby in tags mingled with HTML. To avoid cluttering the templates with boilerplate code, a number of helper classes provide common behavior for forms, dates, and strings. It's also easy to add new helpers to your application as it evolves.
19
-
20
- NOTE: Some features of Action View are tied to Active Record, but that doesn't mean Action View depends on Active Record. Action View is an independent package that can be used with any sort of Ruby libraries.
21
-
22
- Using Action View with Rails
23
- ----------------------------
24
-
25
- For each controller there is an associated directory in the `app/views` directory which holds the template files that make up the views associated with that controller. These files are used to display the view that results from each controller action.
26
-
27
- Let's take a look at what Rails does by default when creating a new resource using the scaffold generator:
28
-
29
- ```bash
30
- $ bin/rails generate scaffold article
31
- [...]
32
- invoke scaffold_controller
33
- create app/controllers/articles_controller.rb
34
- invoke erb
35
- create app/views/articles
36
- create app/views/articles/index.html.erb
37
- create app/views/articles/edit.html.erb
38
- create app/views/articles/show.html.erb
39
- create app/views/articles/new.html.erb
40
- create app/views/articles/_form.html.erb
41
- [...]
42
- ```
43
-
44
- There is a naming convention for views in Rails. Typically, the views share their name with the associated controller action, as you can see above.
45
- For example, the index controller action of the `articles_controller.rb` will use the `index.html.erb` view file in the `app/views/articles` directory.
46
- The complete HTML returned to the client is composed of a combination of this ERB file, a layout template that wraps it, and all the partials that the view may reference. Within this guide you will find more detailed documentation about each of these three components.
47
-
48
-
49
- Templates, Partials and Layouts
50
- -------------------------------
51
-
52
- As mentioned, the final HTML output is a composition of three Rails elements: `Templates`, `Partials` and `Layouts`.
53
- Below is a brief overview of each of them.
54
-
55
- ### Templates
56
-
57
- Action View templates can be written in several ways. If the template file has a `.erb` extension then it uses a mixture of ERB (Embedded Ruby) and HTML. If the template file has a `.builder` extension then the `Builder::XmlMarkup` library is used.
58
-
59
- Rails supports multiple template systems and uses a file extension to distinguish amongst them. For example, an HTML file using the ERB template system will have `.html.erb` as a file extension.
60
-
61
- #### ERB
62
-
63
- Within an ERB template, Ruby code can be included using both `<% %>` and `<%= %>` tags. The `<% %>` tags are used to execute Ruby code that does not return anything, such as conditions, loops or blocks, and the `<%= %>` tags are used when you want output.
64
-
65
- Consider the following loop for names:
66
-
67
- ```html+erb
68
- <h1>Names of all the people</h1>
69
- <% @people.each do |person| %>
70
- Name: <%= person.name %><br>
71
- <% end %>
72
- ```
73
-
74
- The loop is set up using regular embedding tags (`<% %>`) and the name is inserted using the output embedding tags (`<%= %>`). Note that this is not just a usage suggestion: regular output functions such as `print` and `puts` won't be rendered to the view with ERB templates. So this would be wrong:
75
-
76
- ```html+erb
77
- <%# WRONG %>
78
- Hi, Mr. <% puts "Frodo" %>
79
- ```
80
-
81
- To suppress leading and trailing whitespaces, you can use `<%-` `-%>` interchangeably with `<%` and `%>`.
82
-
83
- #### Builder
84
-
85
- Builder templates are a more programmatic alternative to ERB. They are especially useful for generating XML content. An XmlMarkup object named `xml` is automatically made available to templates with a `.builder` extension.
86
-
87
- Here are some basic examples:
88
-
89
- ```ruby
90
- xml.em("emphasized")
91
- xml.em { xml.b("emph & bold") }
92
- xml.a("A Link", "href" => "http://rubyonrails.org")
93
- xml.target("name" => "compile", "option" => "fast")
94
- ```
95
-
96
- which would produce:
97
-
98
- ```html
99
- <em>emphasized</em>
100
- <em><b>emph &amp; bold</b></em>
101
- <a href="http://rubyonrails.org">A link</a>
102
- <target option="fast" name="compile" />
103
- ```
104
-
105
- Any method with a block will be treated as an XML markup tag with nested markup in the block. For example, the following:
106
-
107
- ```ruby
108
- xml.div {
109
- xml.h1(@person.name)
110
- xml.p(@person.bio)
111
- }
112
- ```
113
-
114
- would produce something like:
115
-
116
- ```html
117
- <div>
118
- <h1>David Heinemeier Hansson</h1>
119
- <p>A product of Danish Design during the Winter of '79...</p>
120
- </div>
121
- ```
122
-
123
- Below is a full-length RSS example actually used on Basecamp:
124
-
125
- ```ruby
126
- xml.rss("version" => "2.0", "xmlns:dc" => "http://purl.org/dc/elements/1.1/") do
127
- xml.channel do
128
- xml.title(@feed_title)
129
- xml.link(@url)
130
- xml.description "Basecamp: Recent items"
131
- xml.language "en-us"
132
- xml.ttl "40"
133
-
134
- for item in @recent_items
135
- xml.item do
136
- xml.title(item_title(item))
137
- xml.description(item_description(item)) if item_description(item)
138
- xml.pubDate(item_pubDate(item))
139
- xml.guid(@person.firm.account.url + @recent_items.url(item))
140
- xml.link(@person.firm.account.url + @recent_items.url(item))
141
- xml.tag!("dc:creator", item.author_name) if item_has_creator?(item)
142
- end
143
- end
144
- end
145
- end
146
- ```
147
-
148
- #### Template Caching
149
-
150
- By default, Rails will compile each template to a method in order to render it. When you alter a template, Rails will check the file's modification time and recompile it in development mode.
151
-
152
- ### Partials
153
-
154
- Partial templates - usually just called "partials" - are another device for breaking the rendering process into more manageable chunks. With partials, you can extract pieces of code from your templates to separate files and also reuse them throughout your templates.
155
-
156
- #### Naming Partials
157
-
158
- To render a partial as part of a view, you use the `render` method within the view:
159
-
160
- ```erb
161
- <%= render "menu" %>
162
- ```
163
-
164
- This will render a file named `_menu.html.erb` at that point within the view that is being rendered. Note the leading underscore character: partials are named with a leading underscore to distinguish them from regular views, even though they are referred to without the underscore. This holds true even when you're pulling in a partial from another folder:
165
-
166
- ```erb
167
- <%= render "shared/menu" %>
168
- ```
169
-
170
- That code will pull in the partial from `app/views/shared/_menu.html.erb`.
171
-
172
- #### Using Partials to simplify Views
173
-
174
- One way to use partials is to treat them as the equivalent of subroutines; a way to move details out of a view so that you can grasp what's going on more easily. For example, you might have a view that looks like this:
175
-
176
- ```html+erb
177
- <%= render "shared/ad_banner" %>
178
-
179
- <h1>Products</h1>
180
-
181
- <p>Here are a few of our fine products:</p>
182
- <% @products.each do |product| %>
183
- <%= render partial: "product", locals: {product: product} %>
184
- <% end %>
185
-
186
- <%= render "shared/footer" %>
187
- ```
188
-
189
- Here, the `_ad_banner.html.erb` and `_footer.html.erb` partials could contain content that is shared among many pages in your application. You don't need to see the details of these sections when you're concentrating on a particular page.
190
-
191
- #### The `as` and `object` options
192
-
193
- By default `ActionView::Partials::PartialRenderer` has its object in a local variable with the same name as the template. So, given:
194
-
195
- ```erb
196
- <%= render partial: "product" %>
197
- ```
198
-
199
- within product we'll get `@product` in the local variable `product`, as if we had written:
200
-
201
- ```erb
202
- <%= render partial: "product", locals: {product: @product} %>
203
- ```
204
-
205
- With the `as` option we can specify a different name for the local variable. For example, if we wanted it to be `item` instead of `product` we would do:
206
-
207
- ```erb
208
- <%= render partial: "product", as: "item" %>
209
- ```
210
-
211
- The `object` option can be used to directly specify which object is rendered into the partial; useful when the template's object is elsewhere (eg. in a different instance variable or in a local variable).
212
-
213
- For example, instead of:
214
-
215
- ```erb
216
- <%= render partial: "product", locals: {product: @item} %>
217
- ```
218
-
219
- we would do:
220
-
221
- ```erb
222
- <%= render partial: "product", object: @item %>
223
- ```
224
-
225
- The `object` and `as` options can also be used together:
226
-
227
- ```erb
228
- <%= render partial: "product", object: @item, as: "item" %>
229
- ```
230
-
231
- #### Rendering Collections
232
-
233
- It is very common that a template will need to iterate over a collection and render a sub-template for each of the elements. This pattern has been implemented as a single method that accepts an array and renders a partial for each one of the elements in the array.
234
-
235
- So this example for rendering all the products:
236
-
237
- ```erb
238
- <% @products.each do |product| %>
239
- <%= render partial: "product", locals: { product: product } %>
240
- <% end %>
241
- ```
242
-
243
- can be rewritten in a single line:
244
-
245
- ```erb
246
- <%= render partial: "product", collection: @products %>
247
- ```
248
-
249
- When a partial is called with a collection, the individual instances of the partial have access to the member of the collection being rendered via a variable named after the partial. In this case, the partial is `_product`, and within it you can refer to `product` to get the collection member that is being rendered.
250
-
251
- You can use a shorthand syntax for rendering collections. Assuming `@products` is a collection of `Product` instances, you can simply write the following to produce the same result:
252
-
253
- ```erb
254
- <%= render @products %>
255
- ```
256
-
257
- Rails determines the name of the partial to use by looking at the model name in the collection, `Product` in this case. In fact, you can even render a collection made up of instances of different models using this shorthand, and Rails will choose the proper partial for each member of the collection.
258
-
259
- #### Spacer Templates
260
-
261
- You can also specify a second partial to be rendered between instances of the main partial by using the `:spacer_template` option:
262
-
263
- ```erb
264
- <%= render partial: @products, spacer_template: "product_ruler" %>
265
- ```
266
-
267
- Rails will render the `_product_ruler` partial (with no data passed to it) between each pair of `_product` partials.
268
-
269
- ### Layouts
270
-
271
- Layouts can be used to render a common view template around the results of Rails controller actions. Typically, a Rails application will have a couple of layouts that pages will be rendered within. For example, a site might have one layout for a logged in user and another for the marketing or sales side of the site. The logged in user layout might include top-level navigation that should be present across many controller actions. The sales layout for a SaaS app might include top-level navigation for things like "Pricing" and "Contact Us" pages. You would expect each layout to have a different look and feel. You can read about layouts in more detail in the [Layouts and Rendering in Rails](layouts_and_rendering.html) guide.
272
-
273
- Partial Layouts
274
- ---------------
275
-
276
- Partials can have their own layouts applied to them. These layouts are different from those applied to a controller action, but they work in a similar fashion.
277
-
278
- Let's say we're displaying an article on a page which should be wrapped in a `div` for display purposes. Firstly, we'll create a new `Article`:
279
-
280
- ```ruby
281
- Article.create(body: 'Partial Layouts are cool!')
282
- ```
283
-
284
- In the `show` template, we'll render the `_article` partial wrapped in the `box` layout:
285
-
286
- **articles/show.html.erb**
287
-
288
- ```erb
289
- <%= render partial: 'article', layout: 'box', locals: {article: @article} %>
290
- ```
291
-
292
- The `box` layout simply wraps the `_article` partial in a `div`:
293
-
294
- **articles/_box.html.erb**
295
-
296
- ```html+erb
297
- <div class='box'>
298
- <%= yield %>
299
- </div>
300
- ```
301
-
302
- The `_article` partial wraps the article's `body` in a `div` with the `id` of the article using the `div_for` helper:
303
-
304
- **articles/_article.html.erb**
305
-
306
- ```html+erb
307
- <%= div_for(article) do %>
308
- <p><%= article.body %></p>
309
- <% end %>
310
- ```
311
-
312
- this would output the following:
313
-
314
- ```html
315
- <div class='box'>
316
- <div id='article_1'>
317
- <p>Partial Layouts are cool!</p>
318
- </div>
319
- </div>
320
- ```
321
-
322
- Note that the partial layout has access to the local `article` variable that was passed into the `render` call. However, unlike application-wide layouts, partial layouts still have the underscore prefix.
323
-
324
- You can also render a block of code within a partial layout instead of calling `yield`. For example, if we didn't have the `_article` partial, we could do this instead:
325
-
326
- **articles/show.html.erb**
327
-
328
- ```html+erb
329
- <% render(layout: 'box', locals: {article: @article}) do %>
330
- <%= div_for(article) do %>
331
- <p><%= article.body %></p>
332
- <% end %>
333
- <% end %>
334
- ```
335
-
336
- Supposing we use the same `_box` partial from above, this would produce the same output as the previous example.
337
-
338
- View Paths
339
- ----------
340
-
341
- TODO...
342
-
343
- Overview of helpers provided by Action View
344
- -------------------------------------------
345
-
346
- WIP: Not all the helpers are listed here. For a full list see the [API documentation](http://api.rubyonrails.org/classes/ActionView/Helpers.html)
347
-
348
- The following is only a brief overview summary of the helpers available in Action View. It's recommended that you review the [API Documentation](http://api.rubyonrails.org/classes/ActionView/Helpers.html), which covers all of the helpers in more detail, but this should serve as a good starting point.
349
-
350
- ### RecordTagHelper
351
-
352
- This module provides methods for generating container tags, such as `div`, for your record. This is the recommended way of creating a container for render your Active Record object, as it adds an appropriate class and id attributes to that container. You can then refer to those containers easily by following the convention, instead of having to think about which class or id attribute you should use.
353
-
354
- #### content_tag_for
355
-
356
- Renders a container tag that relates to your Active Record Object.
357
-
358
- For example, given `@article` is the object of `Article` class, you can do:
359
-
360
- ```html+erb
361
- <%= content_tag_for(:tr, @article) do %>
362
- <td><%= @article.title %></td>
363
- <% end %>
364
- ```
365
-
366
- This will generate this HTML output:
367
-
368
- ```html
369
- <tr id="article_1234" class="article">
370
- <td>Hello World!</td>
371
- </tr>
372
- ```
373
-
374
- You can also supply HTML attributes as an additional option hash. For example:
375
-
376
- ```html+erb
377
- <%= content_tag_for(:tr, @article, class: "frontpage") do %>
378
- <td><%= @article.title %></td>
379
- <% end %>
380
- ```
381
-
382
- Will generate this HTML output:
383
-
384
- ```html
385
- <tr id="article_1234" class="article frontpage">
386
- <td>Hello World!</td>
387
- </tr>
388
- ```
389
-
390
- You can pass a collection of Active Record objects. This method will loop through your objects and create a container for each of them. For example, given `@articles` is an array of two `Article` objects:
391
-
392
- ```html+erb
393
- <%= content_tag_for(:tr, @articles) do |article| %>
394
- <td><%= article.title %></td>
395
- <% end %>
396
- ```
397
-
398
- Will generate this HTML output:
399
-
400
- ```html
401
- <tr id="article_1234" class="article">
402
- <td>Hello World!</td>
403
- </tr>
404
- <tr id="article_1235" class="article">
405
- <td>Ruby on Rails Rocks!</td>
406
- </tr>
407
- ```
408
-
409
- #### div_for
410
-
411
- This is actually a convenient method which calls `content_tag_for` internally with `:div` as the tag name. You can pass either an Active Record object or a collection of objects. For example:
412
-
413
- ```html+erb
414
- <%= div_for(@article, class: "frontpage") do %>
415
- <td><%= @article.title %></td>
416
- <% end %>
417
- ```
418
-
419
- Will generate this HTML output:
420
-
421
- ```html
422
- <div id="article_1234" class="article frontpage">
423
- <td>Hello World!</td>
424
- </div>
425
- ```
426
-
427
- ### AssetTagHelper
428
-
429
- This module provides methods for generating HTML that links views to assets such as images, JavaScript files, stylesheets, and feeds.
430
-
431
- 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 `config.action_controller.asset_host` in the application configuration, typically in `config/environments/production.rb`. For example, let's say your asset host is `assets.example.com`:
432
-
433
- ```ruby
434
- config.action_controller.asset_host = "assets.example.com"
435
- image_tag("rails.png") # => <img src="http://assets.example.com/images/rails.png" alt="Rails" />
436
- ```
437
-
438
- #### auto_discovery_link_tag
439
-
440
- Returns a link tag that browsers and feed readers can use to auto-detect an RSS or Atom feed.
441
-
442
- ```ruby
443
- auto_discovery_link_tag(:rss, "http://www.example.com/feed.rss", { title: "RSS Feed" }) # =>
444
- <link rel="alternate" type="application/rss+xml" title="RSS Feed" href="http://www.example.com/feed.rss" />
445
- ```
446
-
447
- #### image_path
448
-
449
- Computes the path to an image asset in the `app/assets/images` directory. Full paths from the document root will be passed through. Used internally by `image_tag` to build the image path.
450
-
451
- ```ruby
452
- image_path("edit.png") # => /assets/edit.png
453
- ```
454
-
455
- Fingerprint will be added to the filename if config.assets.digest is set to true.
456
-
457
- ```ruby
458
- image_path("edit.png") # => /assets/edit-2d1a2db63fc738690021fedb5a65b68e.png
459
- ```
460
-
461
- #### image_url
462
-
463
- Computes the url to an image asset in the `app/assets/images` directory. This will call `image_path` internally and merge with your current host or your asset host.
464
-
465
- ```ruby
466
- image_url("edit.png") # => http://www.example.com/assets/edit.png
467
- ```
468
-
469
- #### image_tag
470
-
471
- Returns an HTML image tag for the source. The source can be a full path or a file that exists in your `app/assets/images` directory.
472
-
473
- ```ruby
474
- image_tag("icon.png") # => <img src="/assets/icon.png" alt="Icon" />
475
- ```
476
-
477
- #### javascript_include_tag
478
-
479
- 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 `app/assets/javascripts` directory for inclusion into the current page or you can pass the full path relative to your document root.
480
-
481
- ```ruby
482
- javascript_include_tag "common" # => <script src="/assets/common.js"></script>
483
- ```
484
-
485
- If the application does not use the asset pipeline, to include the jQuery JavaScript library in your application, pass `:defaults` as the source. When using `:defaults`, if an `application.js` file exists in your `app/assets/javascripts` directory, it will be included as well.
486
-
487
- ```ruby
488
- javascript_include_tag :defaults
489
- ```
490
-
491
- You can also include all JavaScript files in the `app/assets/javascripts` directory using `:all` as the source.
492
-
493
- ```ruby
494
- javascript_include_tag :all
495
- ```
496
-
497
- You can also cache multiple JavaScript files 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).
498
-
499
- ```ruby
500
- javascript_include_tag :all, cache: true # =>
501
- <script src="/javascripts/all.js"></script>
502
- ```
503
-
504
- #### javascript_path
505
-
506
- Computes the path to a JavaScript asset in the `app/assets/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.
507
-
508
- ```ruby
509
- javascript_path "common" # => /assets/common.js
510
- ```
511
-
512
- #### javascript_url
513
-
514
- Computes the url to a JavaScript asset in the `app/assets/javascripts` directory. This will call `javascript_path` internally and merge with your current host or your asset host.
515
-
516
- ```ruby
517
- javascript_url "common" # => http://www.example.com/assets/common.js
518
- ```
519
-
520
- #### stylesheet_link_tag
521
-
522
- Returns a stylesheet link tag for the sources specified as arguments. If you don't specify an extension, `.css` will be appended automatically.
523
-
524
- ```ruby
525
- stylesheet_link_tag "application" # => <link href="/assets/application.css" media="screen" rel="stylesheet" />
526
- ```
527
-
528
- You can also include all styles in the stylesheet directory using :all as the source:
529
-
530
- ```ruby
531
- stylesheet_link_tag :all
532
- ```
533
-
534
- 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).
535
-
536
- ```ruby
537
- stylesheet_link_tag :all, cache: true
538
- # => <link href="/assets/all.css" media="screen" rel="stylesheet" />
539
- ```
540
-
541
- #### stylesheet_path
542
-
543
- Computes the path to a stylesheet asset in the `app/assets/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.
544
-
545
- ```ruby
546
- stylesheet_path "application" # => /assets/application.css
547
- ```
548
-
549
- #### stylesheet_url
550
-
551
- Computes the url to a stylesheet asset in the `app/assets/stylesheets` directory. This will call `stylesheet_path` internally and merge with your current host or your asset host.
552
-
553
- ```ruby
554
- stylesheet_url "application" # => http://www.example.com/assets/application.css
555
- ```
556
-
557
- ### AtomFeedHelper
558
-
559
- #### atom_feed
560
-
561
- This helper makes building an Atom feed easy. Here's a full usage example:
562
-
563
- **config/routes.rb**
564
-
565
- ```ruby
566
- resources :articles
567
- ```
568
-
569
- **app/controllers/articles_controller.rb**
570
-
571
- ```ruby
572
- def index
573
- @articles = Article.all
574
-
575
- respond_to do |format|
576
- format.html
577
- format.atom
578
- end
579
- end
580
- ```
581
-
582
- **app/views/articles/index.atom.builder**
583
-
584
- ```ruby
585
- atom_feed do |feed|
586
- feed.title("Articles Index")
587
- feed.updated((@articles.first.created_at))
588
-
589
- @articles.each do |article|
590
- feed.entry(article) do |entry|
591
- entry.title(article.title)
592
- entry.content(article.body, type: 'html')
593
-
594
- entry.author do |author|
595
- author.name(article.author_name)
596
- end
597
- end
598
- end
599
- end
600
- ```
601
-
602
- ### BenchmarkHelper
603
-
604
- #### benchmark
605
-
606
- 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.
607
-
608
- ```html+erb
609
- <% benchmark "Process data files" do %>
610
- <%= expensive_files_operation %>
611
- <% end %>
612
- ```
613
-
614
- 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.
615
-
616
- ### CacheHelper
617
-
618
- #### cache
619
-
620
- 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.
621
-
622
- ```erb
623
- <% cache do %>
624
- <%= render "shared/footer" %>
625
- <% end %>
626
- ```
627
-
628
- ### CaptureHelper
629
-
630
- #### capture
631
-
632
- 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.
633
-
634
- ```html+erb
635
- <% @greeting = capture do %>
636
- <p>Welcome! The date and time is <%= Time.now %></p>
637
- <% end %>
638
- ```
639
-
640
- The captured variable can then be used anywhere else.
641
-
642
- ```html+erb
643
- <html>
644
- <head>
645
- <title>Welcome!</title>
646
- </head>
647
- <body>
648
- <%= @greeting %>
649
- </body>
650
- </html>
651
- ```
652
-
653
- #### content_for
654
-
655
- 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`.
656
-
657
- 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.
658
-
659
- **app/views/layouts/application.html.erb**
660
-
661
- ```html+erb
662
- <html>
663
- <head>
664
- <title>Welcome!</title>
665
- <%= yield :special_script %>
666
- </head>
667
- <body>
668
- <p>Welcome! The date and time is <%= Time.now %></p>
669
- </body>
670
- </html>
671
- ```
672
-
673
- **app/views/articles/special.html.erb**
674
-
675
- ```html+erb
676
- <p>This is a special page.</p>
677
-
678
- <% content_for :special_script do %>
679
- <script>alert('Hello!')</script>
680
- <% end %>
681
- ```
682
-
683
- ### DateHelper
684
-
685
- #### date_select
686
-
687
- Returns a set of select tags (one for year, month, and day) pre-selected for accessing a specified date-based attribute.
688
-
689
- ```ruby
690
- date_select("article", "published_on")
691
- ```
692
-
693
- #### datetime_select
694
-
695
- Returns a set of select tags (one for year, month, day, hour, and minute) pre-selected for accessing a specified datetime-based attribute.
696
-
697
- ```ruby
698
- datetime_select("article", "published_on")
699
- ```
700
-
701
- #### distance_of_time_in_words
702
-
703
- Reports the approximate distance in time between two Time or Date objects or integers as seconds. Set `include_seconds` to true if you want more detailed approximations.
704
-
705
- ```ruby
706
- distance_of_time_in_words(Time.now, Time.now + 15.seconds) # => less than a minute
707
- distance_of_time_in_words(Time.now, Time.now + 15.seconds, include_seconds: true) # => less than 20 seconds
708
- ```
709
-
710
- #### select_date
711
-
712
- Returns a set of HTML select-tags (one for year, month, and day) pre-selected with the `date` provided.
713
-
714
- ```ruby
715
- # Generates a date select that defaults to the date provided (six days after today)
716
- select_date(Time.today + 6.days)
717
-
718
- # Generates a date select that defaults to today (no specified date)
719
- select_date()
720
- ```
721
-
722
- #### select_datetime
723
-
724
- Returns a set of HTML select-tags (one for year, month, day, hour, and minute) pre-selected with the `datetime` provided.
725
-
726
- ```ruby
727
- # Generates a datetime select that defaults to the datetime provided (four days after today)
728
- select_datetime(Time.now + 4.days)
729
-
730
- # Generates a datetime select that defaults to today (no specified datetime)
731
- select_datetime()
732
- ```
733
-
734
- #### select_day
735
-
736
- Returns a select tag with options for each of the days 1 through 31 with the current day selected.
737
-
738
- ```ruby
739
- # Generates a select field for days that defaults to the day for the date provided
740
- select_day(Time.today + 2.days)
741
-
742
- # Generates a select field for days that defaults to the number given
743
- select_day(5)
744
- ```
745
-
746
- #### select_hour
747
-
748
- Returns a select tag with options for each of the hours 0 through 23 with the current hour selected.
749
-
750
- ```ruby
751
- # Generates a select field for hours that defaults to the hours for the time provided
752
- select_hour(Time.now + 6.hours)
753
- ```
754
-
755
- #### select_minute
756
-
757
- Returns a select tag with options for each of the minutes 0 through 59 with the current minute selected.
758
-
759
- ```ruby
760
- # Generates a select field for minutes that defaults to the minutes for the time provided.
761
- select_minute(Time.now + 6.hours)
762
- ```
763
-
764
- #### select_month
765
-
766
- Returns a select tag with options for each of the months January through December with the current month selected.
767
-
768
- ```ruby
769
- # Generates a select field for months that defaults to the current month
770
- select_month(Date.today)
771
- ```
772
-
773
- #### select_second
774
-
775
- Returns a select tag with options for each of the seconds 0 through 59 with the current second selected.
776
-
777
- ```ruby
778
- # Generates a select field for seconds that defaults to the seconds for the time provided
779
- select_second(Time.now + 16.minutes)
780
- ```
781
-
782
- #### select_time
783
-
784
- Returns a set of HTML select-tags (one for hour and minute).
785
-
786
- ```ruby
787
- # Generates a time select that defaults to the time provided
788
- select_time(Time.now)
789
- ```
790
-
791
- #### select_year
792
-
793
- Returns a select tag with options for each of the five years on each side of the current, which is selected. The five year radius can be changed using the `:start_year` and `:end_year` keys in the `options`.
794
-
795
- ```ruby
796
- # Generates a select field for five years on either side of Date.today that defaults to the current year
797
- select_year(Date.today)
798
-
799
- # Generates a select field from 1900 to 2009 that defaults to the current year
800
- select_year(Date.today, start_year: 1900, end_year: 2009)
801
- ```
802
-
803
- #### time_ago_in_words
804
-
805
- Like `distance_of_time_in_words`, but where `to_time` is fixed to `Time.now`.
806
-
807
- ```ruby
808
- time_ago_in_words(3.minutes.from_now) # => 3 minutes
809
- ```
810
-
811
- #### time_select
812
-
813
- Returns a set of select tags (one for hour, minute and optionally second) pre-selected for accessing a specified time-based attribute. The selects are prepared for multi-parameter assignment to an Active Record object.
814
-
815
- ```ruby
816
- # Creates a time select tag that, when POSTed, will be stored in the order variable in the submitted attribute
817
- time_select("order", "submitted")
818
- ```
819
-
820
- ### DebugHelper
821
-
822
- Returns a `pre` tag that has object dumped by YAML. This creates a very readable way to inspect an object.
823
-
824
- ```ruby
825
- my_hash = {'first' => 1, 'second' => 'two', 'third' => [1,2,3]}
826
- debug(my_hash)
827
- ```
828
-
829
- ```html
830
- <pre class='debug_dump'>---
831
- first: 1
832
- second: two
833
- third:
834
- - 1
835
- - 2
836
- - 3
837
- </pre>
838
- ```
839
-
840
- ### FormHelper
841
-
842
- Form helpers are designed to make working with models much easier compared to using just standard HTML elements by providing a set of methods for creating forms based on your models. This helper generates the HTML for forms, providing a method for each sort of input (e.g., text, password, select, and so on). When the form is submitted (i.e., when the user hits the submit button or form.submit is called via JavaScript), the form inputs will be bundled into the params object and passed back to the controller.
843
-
844
- There are two types of form helpers: those that specifically work with model attributes and those that don't. This helper deals with those that work with model attributes; to see an example of form helpers that don't work with model attributes, check the ActionView::Helpers::FormTagHelper documentation.
845
-
846
- The core method of this helper, form_for, gives you the ability to create a form for a model instance; for example, let's say that you have a model Person and want to create a new instance of it:
847
-
848
- ```html+erb
849
- # Note: a @person variable will have been created in the controller (e.g. @person = Person.new)
850
- <%= form_for @person, url: {action: "create"} do |f| %>
851
- <%= f.text_field :first_name %>
852
- <%= f.text_field :last_name %>
853
- <%= submit_tag 'Create' %>
854
- <% end %>
855
- ```
856
-
857
- The HTML generated for this would be:
858
-
859
- ```html
860
- <form action="/people/create" method="post">
861
- <input id="person_first_name" name="person[first_name]" type="text" />
862
- <input id="person_last_name" name="person[last_name]" type="text" />
863
- <input name="commit" type="submit" value="Create" />
864
- </form>
865
- ```
866
-
867
- The params object created when this form is submitted would look like:
868
-
869
- ```ruby
870
- {"action" => "create", "controller" => "people", "person" => {"first_name" => "William", "last_name" => "Smith"}}
871
- ```
872
-
873
- The params hash has a nested person value, which can therefore be accessed with params[:person] in the controller.
874
-
875
- #### check_box
876
-
877
- Returns a checkbox tag tailored for accessing a specified attribute.
878
-
879
- ```ruby
880
- # Let's say that @article.validated? is 1:
881
- check_box("article", "validated")
882
- # => <input type="checkbox" id="article_validated" name="article[validated]" value="1" />
883
- # <input name="article[validated]" type="hidden" value="0" />
884
- ```
885
-
886
- #### fields_for
887
-
888
- Creates a scope around a specific model object like form_for, but doesn't create the form tags themselves. This makes fields_for suitable for specifying additional model objects in the same form:
889
-
890
- ```html+erb
891
- <%= form_for @person, url: {action: "update"} do |person_form| %>
892
- First name: <%= person_form.text_field :first_name %>
893
- Last name : <%= person_form.text_field :last_name %>
894
-
895
- <%= fields_for @person.permission do |permission_fields| %>
896
- Admin? : <%= permission_fields.check_box :admin %>
897
- <% end %>
898
- <% end %>
899
- ```
900
-
901
- #### file_field
902
-
903
- Returns a file upload input tag tailored for accessing a specified attribute.
904
-
905
- ```ruby
906
- file_field(:user, :avatar)
907
- # => <input type="file" id="user_avatar" name="user[avatar]" />
908
- ```
909
-
910
- #### form_for
911
-
912
- Creates a form and a scope around a specific model object that is used as a base for questioning about values for the fields.
913
-
914
- ```html+erb
915
- <%= form_for @article do |f| %>
916
- <%= f.label :title, 'Title' %>:
917
- <%= f.text_field :title %><br>
918
- <%= f.label :body, 'Body' %>:
919
- <%= f.text_area :body %><br>
920
- <% end %>
921
- ```
922
-
923
- #### hidden_field
924
-
925
- Returns a hidden input tag tailored for accessing a specified attribute.
926
-
927
- ```ruby
928
- hidden_field(:user, :token)
929
- # => <input type="hidden" id="user_token" name="user[token]" value="#{@user.token}" />
930
- ```
931
-
932
- #### label
933
-
934
- Returns a label tag tailored for labelling an input field for a specified attribute.
935
-
936
- ```ruby
937
- label(:article, :title)
938
- # => <label for="article_title">Title</label>
939
- ```
940
-
941
- #### password_field
942
-
943
- Returns an input tag of the "password" type tailored for accessing a specified attribute.
944
-
945
- ```ruby
946
- password_field(:login, :pass)
947
- # => <input type="text" id="login_pass" name="login[pass]" value="#{@login.pass}" />
948
- ```
949
-
950
- #### radio_button
951
-
952
- Returns a radio button tag for accessing a specified attribute.
953
-
954
- ```ruby
955
- # Let's say that @article.category returns "rails":
956
- radio_button("article", "category", "rails")
957
- radio_button("article", "category", "java")
958
- # => <input type="radio" id="article_category_rails" name="article[category]" value="rails" checked="checked" />
959
- # <input type="radio" id="article_category_java" name="article[category]" value="java" />
960
- ```
961
-
962
- #### text_area
963
-
964
- Returns a textarea opening and closing tag set tailored for accessing a specified attribute.
965
-
966
- ```ruby
967
- text_area(:comment, :text, size: "20x30")
968
- # => <textarea cols="20" rows="30" id="comment_text" name="comment[text]">
969
- # #{@comment.text}
970
- # </textarea>
971
- ```
972
-
973
- #### text_field
974
-
975
- Returns an input tag of the "text" type tailored for accessing a specified attribute.
976
-
977
- ```ruby
978
- text_field(:article, :title)
979
- # => <input type="text" id="article_title" name="article[title]" value="#{@article.title}" />
980
- ```
981
-
982
- #### email_field
983
-
984
- Returns an input tag of the "email" type tailored for accessing a specified attribute.
985
-
986
- ```ruby
987
- email_field(:user, :email)
988
- # => <input type="email" id="user_email" name="user[email]" value="#{@user.email}" />
989
- ```
990
-
991
- #### url_field
992
-
993
- Returns an input tag of the "url" type tailored for accessing a specified attribute.
994
-
995
- ```ruby
996
- url_field(:user, :url)
997
- # => <input type="url" id="user_url" name="user[url]" value="#{@user.url}" />
998
- ```
999
-
1000
- ### FormOptionsHelper
1001
-
1002
- Provides a number of methods for turning different kinds of containers into a set of option tags.
1003
-
1004
- #### collection_select
1005
-
1006
- Returns `select` and `option` tags for the collection of existing return values of `method` for `object`'s class.
1007
-
1008
- Example object structure for use with this method:
1009
-
1010
- ```ruby
1011
- class Article < ActiveRecord::Base
1012
- belongs_to :author
1013
- end
1014
-
1015
- class Author < ActiveRecord::Base
1016
- has_many :articles
1017
- def name_with_initial
1018
- "#{first_name.first}. #{last_name}"
1019
- end
1020
- end
1021
- ```
1022
-
1023
- Sample usage (selecting the associated Author for an instance of Article, `@article`):
1024
-
1025
- ```ruby
1026
- collection_select(:article, :author_id, Author.all, :id, :name_with_initial, {prompt: true})
1027
- ```
1028
-
1029
- If `@article.author_id` is 1, this would return:
1030
-
1031
- ```html
1032
- <select name="article[author_id]">
1033
- <option value="">Please select</option>
1034
- <option value="1" selected="selected">D. Heinemeier Hansson</option>
1035
- <option value="2">D. Thomas</option>
1036
- <option value="3">M. Clark</option>
1037
- </select>
1038
- ```
1039
-
1040
- #### collection_radio_buttons
1041
-
1042
- Returns `radio_button` tags for the collection of existing return values of `method` for `object`'s class.
1043
-
1044
- Example object structure for use with this method:
1045
-
1046
- ```ruby
1047
- class Article < ActiveRecord::Base
1048
- belongs_to :author
1049
- end
1050
-
1051
- class Author < ActiveRecord::Base
1052
- has_many :articles
1053
- def name_with_initial
1054
- "#{first_name.first}. #{last_name}"
1055
- end
1056
- end
1057
- ```
1058
-
1059
- Sample usage (selecting the associated Author for an instance of Article, `@article`):
1060
-
1061
- ```ruby
1062
- collection_radio_buttons(:article, :author_id, Author.all, :id, :name_with_initial)
1063
- ```
1064
-
1065
- If `@article.author_id` is 1, this would return:
1066
-
1067
- ```html
1068
- <input id="article_author_id_1" name="article[author_id]" type="radio" value="1" checked="checked" />
1069
- <label for="article_author_id_1">D. Heinemeier Hansson</label>
1070
- <input id="article_author_id_2" name="article[author_id]" type="radio" value="2" />
1071
- <label for="article_author_id_2">D. Thomas</label>
1072
- <input id="article_author_id_3" name="article[author_id]" type="radio" value="3" />
1073
- <label for="article_author_id_3">M. Clark</label>
1074
- ```
1075
-
1076
- #### collection_check_boxes
1077
-
1078
- Returns `check_box` tags for the collection of existing return values of `method` for `object`'s class.
1079
-
1080
- Example object structure for use with this method:
1081
-
1082
- ```ruby
1083
- class Article < ActiveRecord::Base
1084
- has_and_belongs_to_many :authors
1085
- end
1086
-
1087
- class Author < ActiveRecord::Base
1088
- has_and_belongs_to_many :articles
1089
- def name_with_initial
1090
- "#{first_name.first}. #{last_name}"
1091
- end
1092
- end
1093
- ```
1094
-
1095
- Sample usage (selecting the associated Authors for an instance of Article, `@article`):
1096
-
1097
- ```ruby
1098
- collection_check_boxes(:article, :author_ids, Author.all, :id, :name_with_initial)
1099
- ```
1100
-
1101
- If `@article.author_ids` is [1], this would return:
1102
-
1103
- ```html
1104
- <input id="article_author_ids_1" name="article[author_ids][]" type="checkbox" value="1" checked="checked" />
1105
- <label for="article_author_ids_1">D. Heinemeier Hansson</label>
1106
- <input id="article_author_ids_2" name="article[author_ids][]" type="checkbox" value="2" />
1107
- <label for="article_author_ids_2">D. Thomas</label>
1108
- <input id="article_author_ids_3" name="article[author_ids][]" type="checkbox" value="3" />
1109
- <label for="article_author_ids_3">M. Clark</label>
1110
- <input name="article[author_ids][]" type="hidden" value="" />
1111
- ```
1112
-
1113
- #### option_groups_from_collection_for_select
1114
-
1115
- Returns a string of `option` tags, like `options_from_collection_for_select`, but groups them by `optgroup` tags based on the object relationships of the arguments.
1116
-
1117
- Example object structure for use with this method:
1118
-
1119
- ```ruby
1120
- class Continent < ActiveRecord::Base
1121
- has_many :countries
1122
- # attribs: id, name
1123
- end
1124
-
1125
- class Country < ActiveRecord::Base
1126
- belongs_to :continent
1127
- # attribs: id, name, continent_id
1128
- end
1129
- ```
1130
-
1131
- Sample usage:
1132
-
1133
- ```ruby
1134
- option_groups_from_collection_for_select(@continents, :countries, :name, :id, :name, 3)
1135
- ```
1136
-
1137
- Possible output:
1138
-
1139
- ```html
1140
- <optgroup label="Africa">
1141
- <option value="1">Egypt</option>
1142
- <option value="4">Rwanda</option>
1143
- ...
1144
- </optgroup>
1145
- <optgroup label="Asia">
1146
- <option value="3" selected="selected">China</option>
1147
- <option value="12">India</option>
1148
- <option value="5">Japan</option>
1149
- ...
1150
- </optgroup>
1151
- ```
1152
-
1153
- Note: Only the `optgroup` and `option` tags are returned, so you still have to wrap the output in an appropriate `select` tag.
1154
-
1155
- #### options_for_select
1156
-
1157
- Accepts a container (hash, array, enumerable, your type) and returns a string of option tags.
1158
-
1159
- ```ruby
1160
- options_for_select([ "VISA", "MasterCard" ])
1161
- # => <option>VISA</option> <option>MasterCard</option>
1162
- ```
1163
-
1164
- Note: Only the `option` tags are returned, you have to wrap this call in a regular HTML `select` tag.
1165
-
1166
- #### options_from_collection_for_select
1167
-
1168
- Returns a string of option tags that have been compiled by iterating over the `collection` and assigning the result of a call to the `value_method` as the option value and the `text_method` as the option text.
1169
-
1170
- ```ruby
1171
- # options_from_collection_for_select(collection, value_method, text_method, selected = nil)
1172
- ```
1173
-
1174
- For example, imagine a loop iterating over each person in @project.people to generate an input tag:
1175
-
1176
- ```ruby
1177
- options_from_collection_for_select(@project.people, "id", "name")
1178
- # => <option value="#{person.id}">#{person.name}</option>
1179
- ```
1180
-
1181
- Note: Only the `option` tags are returned, you have to wrap this call in a regular HTML `select` tag.
1182
-
1183
- #### select
1184
-
1185
- Create a select tag and a series of contained option tags for the provided object and method.
1186
-
1187
- Example:
1188
-
1189
- ```ruby
1190
- select("article", "person_id", Person.all.collect {|p| [ p.name, p.id ] }, {include_blank: true})
1191
- ```
1192
-
1193
- If `@article.person_id` is 1, this would become:
1194
-
1195
- ```html
1196
- <select name="article[person_id]">
1197
- <option value=""></option>
1198
- <option value="1" selected="selected">David</option>
1199
- <option value="2">Sam</option>
1200
- <option value="3">Tobias</option>
1201
- </select>
1202
- ```
1203
-
1204
- #### time_zone_options_for_select
1205
-
1206
- Returns a string of option tags for pretty much any time zone in the world.
1207
-
1208
- #### time_zone_select
1209
-
1210
- Returns select and option tags for the given object and method, using `time_zone_options_for_select` to generate the list of option tags.
1211
-
1212
- ```ruby
1213
- time_zone_select( "user", "time_zone")
1214
- ```
1215
-
1216
- #### date_field
1217
-
1218
- Returns an input tag of the "date" type tailored for accessing a specified attribute.
1219
-
1220
- ```ruby
1221
- date_field("user", "dob")
1222
- ```
1223
-
1224
- ### FormTagHelper
1225
-
1226
- Provides a number of methods for creating form tags that don't rely on an Active Record object assigned to the template like FormHelper does. Instead, you provide the names and values manually.
1227
-
1228
- #### check_box_tag
1229
-
1230
- Creates a check box form input tag.
1231
-
1232
- ```ruby
1233
- check_box_tag 'accept'
1234
- # => <input id="accept" name="accept" type="checkbox" value="1" />
1235
- ```
1236
-
1237
- #### field_set_tag
1238
-
1239
- Creates a field set for grouping HTML form elements.
1240
-
1241
- ```html+erb
1242
- <%= field_set_tag do %>
1243
- <p><%= text_field_tag 'name' %></p>
1244
- <% end %>
1245
- # => <fieldset><p><input id="name" name="name" type="text" /></p></fieldset>
1246
- ```
1247
-
1248
- #### file_field_tag
1249
-
1250
- Creates a file upload field.
1251
-
1252
- ```html+erb
1253
- <%= form_tag({action:"post"}, multipart: true) do %>
1254
- <label for="file">File to Upload</label> <%= file_field_tag "file" %>
1255
- <%= submit_tag %>
1256
- <% end %>
1257
- ```
1258
-
1259
- Example output:
1260
-
1261
- ```ruby
1262
- file_field_tag 'attachment'
1263
- # => <input id="attachment" name="attachment" type="file" />
1264
- ```
1265
-
1266
- #### form_tag
1267
-
1268
- Starts a form tag that points the action to an url configured with `url_for_options` just like `ActionController::Base#url_for`.
1269
-
1270
- ```html+erb
1271
- <%= form_tag '/articles' do %>
1272
- <div><%= submit_tag 'Save' %></div>
1273
- <% end %>
1274
- # => <form action="/articles" method="post"><div><input type="submit" name="submit" value="Save" /></div></form>
1275
- ```
1276
-
1277
- #### hidden_field_tag
1278
-
1279
- Creates a hidden form input field used to transmit data that would be lost due to HTTP's statelessness or data that should be hidden from the user.
1280
-
1281
- ```ruby
1282
- hidden_field_tag 'token', 'VUBJKB23UIVI1UU1VOBVI@'
1283
- # => <input id="token" name="token" type="hidden" value="VUBJKB23UIVI1UU1VOBVI@" />
1284
- ```
1285
-
1286
- #### image_submit_tag
1287
-
1288
- Displays an image which when clicked will submit the form.
1289
-
1290
- ```ruby
1291
- image_submit_tag("login.png")
1292
- # => <input src="/images/login.png" type="image" />
1293
- ```
1294
-
1295
- #### label_tag
1296
-
1297
- Creates a label field.
1298
-
1299
- ```ruby
1300
- label_tag 'name'
1301
- # => <label for="name">Name</label>
1302
- ```
1303
-
1304
- #### password_field_tag
1305
-
1306
- Creates a password field, a masked text field that will hide the users input behind a mask character.
1307
-
1308
- ```ruby
1309
- password_field_tag 'pass'
1310
- # => <input id="pass" name="pass" type="password" />
1311
- ```
1312
-
1313
- #### radio_button_tag
1314
-
1315
- Creates a radio button; use groups of radio buttons named the same to allow users to select from a group of options.
1316
-
1317
- ```ruby
1318
- radio_button_tag 'gender', 'male'
1319
- # => <input id="gender_male" name="gender" type="radio" value="male" />
1320
- ```
1321
-
1322
- #### select_tag
1323
-
1324
- Creates a dropdown selection box.
1325
-
1326
- ```ruby
1327
- select_tag "people", "<option>David</option>"
1328
- # => <select id="people" name="people"><option>David</option></select>
1329
- ```
1330
-
1331
- #### submit_tag
1332
-
1333
- Creates a submit button with the text provided as the caption.
1334
-
1335
- ```ruby
1336
- submit_tag "Publish this article"
1337
- # => <input name="commit" type="submit" value="Publish this article" />
1338
- ```
1339
-
1340
- #### text_area_tag
1341
-
1342
- Creates a text input area; use a textarea for longer text inputs such as blog posts or descriptions.
1343
-
1344
- ```ruby
1345
- text_area_tag 'article'
1346
- # => <textarea id="article" name="article"></textarea>
1347
- ```
1348
-
1349
- #### text_field_tag
1350
-
1351
- Creates a standard text field; use these text fields to input smaller chunks of text like a username or a search query.
1352
-
1353
- ```ruby
1354
- text_field_tag 'name'
1355
- # => <input id="name" name="name" type="text" />
1356
- ```
1357
-
1358
- #### email_field_tag
1359
-
1360
- Creates a standard input field of email type.
1361
-
1362
- ```ruby
1363
- email_field_tag 'email'
1364
- # => <input id="email" name="email" type="email" />
1365
- ```
1366
-
1367
- #### url_field_tag
1368
-
1369
- Creates a standard input field of url type.
1370
-
1371
- ```ruby
1372
- url_field_tag 'url'
1373
- # => <input id="url" name="url" type="url" />
1374
- ```
1375
-
1376
- #### date_field_tag
1377
-
1378
- Creates a standard input field of date type.
1379
-
1380
- ```ruby
1381
- date_field_tag "dob"
1382
- # => <input id="dob" name="dob" type="date" />
1383
- ```
1384
-
1385
- ### JavaScriptHelper
1386
-
1387
- Provides functionality for working with JavaScript in your views.
1388
-
1389
- #### escape_javascript
1390
-
1391
- Escape carrier returns and single and double quotes for JavaScript segments.
1392
-
1393
- #### javascript_tag
1394
-
1395
- Returns a JavaScript tag wrapping the provided code.
1396
-
1397
- ```ruby
1398
- javascript_tag "alert('All is good')"
1399
- ```
1400
-
1401
- ```html
1402
- <script>
1403
- //<![CDATA[
1404
- alert('All is good')
1405
- //]]>
1406
- </script>
1407
- ```
1408
-
1409
- ### NumberHelper
1410
-
1411
- Provides methods for converting numbers into formatted strings. Methods are provided for phone numbers, currency, percentage, precision, positional notation, and file size.
1412
-
1413
- #### number_to_currency
1414
-
1415
- Formats a number into a currency string (e.g., $13.65).
1416
-
1417
- ```ruby
1418
- number_to_currency(1234567890.50) # => $1,234,567,890.50
1419
- ```
1420
-
1421
- #### number_to_human_size
1422
-
1423
- Formats the bytes in size into a more understandable representation; useful for reporting file sizes to users.
1424
-
1425
- ```ruby
1426
- number_to_human_size(1234) # => 1.2 KB
1427
- number_to_human_size(1234567) # => 1.2 MB
1428
- ```
1429
-
1430
- #### number_to_percentage
1431
-
1432
- Formats a number as a percentage string.
1433
-
1434
- ```ruby
1435
- number_to_percentage(100, precision: 0) # => 100%
1436
- ```
1437
-
1438
- #### number_to_phone
1439
-
1440
- Formats a number into a US phone number.
1441
-
1442
- ```ruby
1443
- number_to_phone(1235551234) # => 123-555-1234
1444
- ```
1445
-
1446
- #### number_with_delimiter
1447
-
1448
- Formats a number with grouped thousands using a delimiter.
1449
-
1450
- ```ruby
1451
- number_with_delimiter(12345678) # => 12,345,678
1452
- ```
1453
-
1454
- #### number_with_precision
1455
-
1456
- Formats a number with the specified level of `precision`, which defaults to 3.
1457
-
1458
- ```ruby
1459
- number_with_precision(111.2345) # => 111.235
1460
- number_with_precision(111.2345, 2) # => 111.23
1461
- ```
1462
-
1463
- ### SanitizeHelper
1464
-
1465
- The SanitizeHelper module provides a set of methods for scrubbing text of undesired HTML elements.
1466
-
1467
- #### sanitize
1468
-
1469
- This sanitize helper will HTML encode all tags and strip all attributes that aren't specifically allowed.
1470
-
1471
- ```ruby
1472
- sanitize @article.body
1473
- ```
1474
-
1475
- If either the :attributes or :tags options are passed, only the mentioned tags and attributes are allowed and nothing else.
1476
-
1477
- ```ruby
1478
- sanitize @article.body, tags: %w(table tr td), attributes: %w(id class style)
1479
- ```
1480
-
1481
- To change defaults for multiple uses, for example adding table tags to the default:
1482
-
1483
- ```ruby
1484
- class Application < Rails::Application
1485
- config.action_view.sanitized_allowed_tags = 'table', 'tr', 'td'
1486
- end
1487
- ```
1488
-
1489
- #### sanitize_css(style)
1490
-
1491
- Sanitizes a block of CSS code.
1492
-
1493
- #### strip_links(html)
1494
- Strips all link tags from text leaving just the link text.
1495
-
1496
- ```ruby
1497
- strip_links("<a href="http://rubyonrails.org">Ruby on Rails</a>")
1498
- # => Ruby on Rails
1499
- ```
1500
-
1501
- ```ruby
1502
- strip_links("emails to <a href="mailto:me@email.com">me@email.com</a>.")
1503
- # => emails to me@email.com.
1504
- ```
1505
-
1506
- ```ruby
1507
- strip_links('Blog: <a href="http://myblog.com/">Visit</a>.')
1508
- # => Blog: Visit.
1509
- ```
1510
-
1511
- #### strip_tags(html)
1512
-
1513
- Strips all HTML tags from the html, including comments.
1514
- This uses the html-scanner tokenizer and so its HTML parsing ability is limited by that of html-scanner.
1515
-
1516
- ```ruby
1517
- strip_tags("Strip <i>these</i> tags!")
1518
- # => Strip these tags!
1519
- ```
1520
-
1521
- ```ruby
1522
- strip_tags("<b>Bold</b> no more! <a href='more.html'>See more</a>")
1523
- # => Bold no more! See more
1524
- ```
1525
-
1526
- NB: The output may still contain unescaped '<', '>', '&' characters and confuse browsers.
1527
-
1528
- ### CsrfHelper
1529
-
1530
- Returns meta tags "csrf-param" and "csrf-token" with the name of the cross-site
1531
- request forgery protection parameter and token, respectively.
1532
-
1533
- ```html
1534
- <%= csrf_meta_tags %>
1535
- ```
1536
-
1537
- NOTE: Regular forms generate hidden fields so they do not use these tags. More
1538
- details can be found in the [Rails Security Guide](security.html#cross-site-request-forgery-csrf).
1539
-
1540
- Localized Views
1541
- ---------------
1542
-
1543
- Action View has the ability render different templates depending on the current locale.
1544
-
1545
- For example, suppose you have a `ArticlesController` with a show action. By default, calling this action will render `app/views/articles/show.html.erb`. But if you set `I18n.locale = :de`, then `app/views/articles/show.de.html.erb` will be rendered instead. If the localized template isn't present, the undecorated version will be used. This means you're not required to provide localized views for all cases, but they will be preferred and used if available.
1546
-
1547
- You can use the same technique to localize the rescue files in your public directory. For example, setting `I18n.locale = :de` and creating `public/500.de.html` and `public/404.de.html` would allow you to have localized rescue pages.
1548
-
1549
- Since Rails doesn't restrict the symbols that you use to set I18n.locale, you can leverage this system to display different content depending on anything you like. For example, suppose you have some "expert" users that should see different pages from "normal" users. You could add the following to `app/controllers/application.rb`:
1550
-
1551
- ```ruby
1552
- before_action :set_expert_locale
1553
-
1554
- def set_expert_locale
1555
- I18n.locale = :expert if current_user.expert?
1556
- end
1557
- ```
1558
-
1559
- Then you could create special views like `app/views/articles/show.expert.html.erb` that would only be displayed to expert users.
1560
-
1561
- You can read more about the Rails Internationalization (I18n) API [here](i18n.html).