0
@@ -1,19 +1,96 @@
0
 module ActionController
0
-  # Write URLs from arbitrary places in your codebase, such as your mailers.
0
+  # In <b>routes.rb</b> one defines URL-to-controller mappings, but the reverse
0
+  # is also possible: an URL can be generated from one of your routing definitions.
0
+  # URL generation functionality is centralized in this module.
0
   #
0
-  # Example:
0
+  # See ActionController::Routing and ActionController::Resources for general
0
+  # information about routing and routes.rb.
0
   #
0
-  #   class MyMailer
0
-  #     include ActionController::UrlWriter
0
-  #     default_url_options[:host] = 'www.basecamphq.com'
0
+  # <b>Tip:</b> If you need to generate URLs from your models or some other place,
0
+  # then ActionController::UrlWriter is what you're looking for. Read on for
0
+  # an introduction.
0
   #
0
-  #     def signup_url(token)
0
-  #       url_for(:controller => 'signup', action => 'index', :token => token)
0
+  # == URL generation from parameters
0
+  #
0
+  # As you may know, some functions - such as ActionController::Base#url_for
0
+  # and ActionView::Helpers::UrlHelper#link_to, can generate URLs given a set
0
+  # of parameters. For example, you've probably had the chance to write code
0
+  # like this in one of your views:
0
+  #
0
+  #   <%= link_to('Click here', :controller => 'users',
0
+  #           :action => 'new', :message => 'Welcome!') %>
0
+  #   
0
+  #   #=> Generates a link to: /users/new?message=Welcome%21
0
+  #
0
+  # link_to, and all other functions that require URL generation functionality,
0
+  # actually use ActionController::UrlWriter under the hood. And in particular,
0
+  # they use the ActionController::UrlWriter#url_for method. One can generate
0
+  # the same path as the above example by using the following code:
0
+  #
0
+  #   include UrlWriter
0
+  #   url_for(:controller => 'users',
0
+  #           :action => 'new',
0
+  #           :message => 'Welcome!',
0
+  #           :only_path => true)
0
+  #   # => "/users/new?message=Welcome%21"
0
+  #
0
+  # Notice the <tt>:only_path => true</tt> part. This is because UrlWriter has no
0
+  # information about the website hostname that your Rails app is serving. So if you
0
+  # want to include the hostname as well, then you must also pass the <tt>:host</tt>
0
+  # argument:
0
+  #
0
+  #   include UrlWriter
0
+  #   url_for(:controller => 'users',
0
+  #           :action => 'new',
0
+  #           :message => 'Welcome!',
0
+  #           :host => 'www.example.com')        # Changed this.
0
+  #   # => "http://www.example.com/users/new?message=Welcome%21"
0
+  #
0
+  # By default, all controllers and views have access to a special version of url_for,
0
+  # that already knows what the current hostname is. So if you use url_for in your
0
+  # controllers or your views, then you don't need to explicitly pass the <tt>:host</tt>
0
+  # argument.
0
+  #
0
+  # For convenience reasons, mailers provide a shortcut for ActionController::UrlWriter#url_for.
0
+  # So within mailers, you only have to type 'url_for' instead of 'ActionController::UrlWriter#url_for'
0
+  # in full. However, mailers don't have hostname information, and what's why you'll still
0
+  # have to specify the <tt>:host</tt> argument when generating URLs in mailers.
0
+  #
0
+  #
0
+  # == URL generation for named routes
0
+  #
0
+  # UrlWriter also allows one to access methods that have been auto-generated from
0
+  # named routes. For example, suppose that you have a 'users' resource in your
0
+  # <b>routes.rb</b>:
0
+  #
0
+  #   map.resources :users
0
+  #
0
+  # This generates, among other things, the method <tt>users_path</tt>. By default,
0
+  # this method is accessible from your controllers, views and mailers. If you need
0
+  # to access this auto-generated method from other places (such as a model), then
0
+  # you can do that in two ways.
0
+  #
0
+  # The first way is to include ActionController::UrlWriter in your class:
0
+  #
0
+  #   class User < ActiveRecord::Base
0
+  #     include ActionController::UrlWriter         # !!!
0
+  #     
0
+  #     def name=(value)
0
+  #       write_attribute('name', value)
0
+  #       write_attribute('base_uri', users_path)   # !!!
0
   #     end
0
-  #  end
0
+  #   end
0
   #
0
-  # In addition to providing +url_for+, named routes are also accessible after
0
-  # including UrlWriter.
0
+  # The second way is to access them through ActionController::UrlWriter.
0
+  # The autogenerated named routes methods are available as class methods:
0
+  #
0
+  #   class User < ActiveRecord::Base
0
+  #     def name=(value)
0
+  #       write_attribute('name', value)
0
+  #       path = ActionController::UrlWriter.users_path   # !!!
0
+  #       write_attribute('base_uri', path)               # !!!
0
+  #     end
0
+  #   end
0
   module UrlWriter
0
     # The default options for urls written by this writer. Typically a <tt>:host</tt>
0
     # pair is provided.