diff options
Diffstat (limited to 'railties/guides')
-rw-r--r-- | railties/guides/source/api_documentation_guidelines.textile | 2 | ||||
-rw-r--r-- | railties/guides/source/form_helpers.textile | 36 | ||||
-rw-r--r-- | railties/guides/source/routing.textile | 10 |
3 files changed, 41 insertions, 7 deletions
diff --git a/railties/guides/source/api_documentation_guidelines.textile b/railties/guides/source/api_documentation_guidelines.textile index 5bac75fe8f..7433507866 100644 --- a/railties/guides/source/api_documentation_guidelines.textile +++ b/railties/guides/source/api_documentation_guidelines.textile @@ -27,7 +27,7 @@ Communicate to the reader the current way of doing things, both explicitly and i Documentation has to be concise but comprehensive. Explore and document edge cases. What happens if a module is anonymous? What if a collection is empty? What if an argument is nil? -The proper names of Rails components have a space in between the words, like "Active Support". +ActiveRecord+ is a Ruby module, whereas Active Record is an ORM. Historically there has been lack of consistency regarding this, but we checked with David when docrails started. All Rails documentation consistently refer to Rails components by their proper name, and if in your next blog post or presentation you remember this tidbit and take it into account that'd be phenomenal:). +The proper names of Rails components have a space in between the words, like "Active Support". +ActiveRecord+ is a Ruby module, whereas Active Record is an ORM. All Rails documentation should consistently refer to Rails components by their proper name, and if in your next blog post or presentation you remember this tidbit and take it into account that'd be phenomenal. Spell names correctly: Arel, Test::Unit, RSpec, HTML, MySQL, JavaScript, ERb. When in doubt, please have a look at some authoritative source like their official documentation. diff --git a/railties/guides/source/form_helpers.textile b/railties/guides/source/form_helpers.textile index 7a033a30d7..ace433e30c 100644 --- a/railties/guides/source/form_helpers.textile +++ b/railties/guides/source/form_helpers.textile @@ -9,6 +9,7 @@ In this guide you will: * Generate select boxes from multiple types of data * Understand the date and time helpers Rails provides * Learn what makes a file upload form different +* Learn some cases of building forms to external resources * Find out where to look for complex forms endprologue. @@ -763,6 +764,40 @@ As a shortcut you can append [] to the name and omit the +:index+ option. This i produces exactly the same output as the previous example. +h3. Forms to external resources + +If you need to post some data to an external resource it is still great to build your from using rails form helpers. But sometimes you need to set an +authenticity_token+ for this resource. You can do it by passing an +:authenticity_token => 'your_external_token'+ parameter to the +form_tag+ options: + +<erb> +<%= form_tag 'http://farfar.away/form', :authenticity_token => 'external_token') do %> + Form contents +<% end %> +</erb> + +Sometimes when you submit data to an external resource, like payment gateway, fields you can use in your form are limited by an external API. So you may want not to generate an +authenticity_token+ hidden field at all. For doing this just pass +false+ to the +:authenticity_token+ option: + +<erb> +<%= form_tag 'http://farfar.away/form', :authenticity_token => 'external_token') do %> + Form contents +<% end %> +</erb> + +The same technique is available for the +form_for+ too: + +<erb> +<%= form_for @invoice, :url => external_url, :authenticity_token => 'external_token' do |f| + Form contents +<% end %> +</erb> + +Or if you don't want to render an +authenticity_token+ field: + +<erb> +<%= form_for @invoice, :url => external_url, :authenticity_token => false do |f| + Form contents +<% end %> +</erb> + h3. Building Complex Forms Many apps grow beyond simple forms editing a single object. For example when creating a Person you might want to allow the user to (on the same form) create multiple address records (home, work, etc.). When later editing that person the user should be able to add, remove or amend addresses as necessary. While this guide has shown you all the pieces necessary to handle this, Rails does not yet have a standard end-to-end way of accomplishing this, but many have come up with viable approaches. These include: @@ -776,6 +811,7 @@ Many apps grow beyond simple forms editing a single object. For example when cre h3. Changelog +* February 5, 2011: Added 'Forms to external resources' section. Timothy N. Tsvetkov <timothy.tsvetkov@gmail.com> * April 6, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com h3. Authors diff --git a/railties/guides/source/routing.textile b/railties/guides/source/routing.textile index 1d81c8f95b..d214031b31 100644 --- a/railties/guides/source/routing.textile +++ b/railties/guides/source/routing.textile @@ -391,6 +391,8 @@ NOTE: You can't use +namespace+ or +:module+ with a +:controller+ path segment. match ':controller(/:action(/:id))', :controller => /admin\/[^\/]+/ </ruby> +TIP: By default dynamic segments don't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within a dynamic segment add a constraint which overrides this - for example +:id => /[^\/]+/+ allows anything except a slash. + h4. Static Segments You can specify static segments when creating a route: @@ -646,6 +648,8 @@ end NOTE: Of course, you can use the more advanced constraints available in non-resourceful routes in this context. +TIP: By default the +:id+ parameter doesn't accept dots - this is because the dot is used as a separator for formatted routes. If you need to use a dot within an +:id+ add a constraint which overrides this - for example +:id => /[^\/]+/+ allows anything except a slash. + h4. Overriding the Named Helpers The +:as+ option lets you override the normal naming for the named route helpers. For example: @@ -852,12 +856,6 @@ You can supply a +:method+ argument to specify the HTTP verb: assert_recognizes({ :controller => "photos", :action => "create" }, { :path => "photos", :method => :post }) </ruby> -You can also use the resourceful helpers to test recognition of a RESTful route: - -<ruby> -assert_recognizes new_photo_url, { :path => "photos", :method => :post } -</ruby> - h5. The +assert_routing+ Assertion The +assert_routing+ assertion checks the route both ways: it tests that the path generates the options, and that the options generate the path. Thus, it combines the functions of +assert_generates+ and +assert_recognizes+. |