<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Module: ActionController::UrlWriter</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" />
<script type="text/javascript">
// <![CDATA[
function popupCode( url ) {
window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
}
function toggleCode( id ) {
if ( document.getElementById )
elem = document.getElementById( id );
else if ( document.all )
elem = eval( "document.all." + id );
else
return false;
elemStyle = elem.style;
if ( elemStyle.display != "block" ) {
elemStyle.display = "block"
} else {
elemStyle.display = "none"
}
return true;
}
// Make codeblocks hidden by default
document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
// ]]>
</script>
</head>
<body>
<div id="classHeader">
<table class="header-table">
<tr class="top-aligned-row">
<td><strong>Module</strong></td>
<td class="class-name-in-header">ActionController::UrlWriter</td>
</tr>
<tr class="top-aligned-row">
<td><strong>In:</strong></td>
<td>
<a href="../../files/lib/action_controller/url_rewriter_rb.html">
lib/action_controller/url_rewriter.rb
</a>
<br />
</td>
</tr>
</table>
</div>
<!-- banner header -->
<div id="bodyContent">
<div id="contextContent">
<div id="description">
<p>
In <b>routes.rb</b> one defines URL-to-controller mappings, but the reverse
is also possible: an URL can be generated from one of your routing
definitions. URL generation functionality is centralized in this module.
</p>
<p>
See <a href="Routing.html">ActionController::Routing</a> and <a
href="Resources.html">ActionController::Resources</a> for general
information about routing and routes.rb.
</p>
<p>
<b>Tip:</b> If you need to generate URLs from your models or some other
place, then <a href="UrlWriter.html">ActionController::UrlWriter</a> is
what you‘re looking for. Read on for an introduction.
</p>
<h2>URL generation from parameters</h2>
<p>
As you may know, some functions - such as <a
href="Base.html#M000294">ActionController::Base#url_for</a> and
ActionView::Helpers::UrlHelper#link_to, can generate URLs given a set of
parameters. For example, you‘ve probably had the chance to write code
like this in one of your views:
</p>
<pre>
<%= link_to('Click here', :controller => 'users',
:action => 'new', :message => 'Welcome!') %>
#=> Generates a link to: /users/new?message=Welcome%21
</pre>
<p>
link_to, and all other functions that require URL generation functionality,
actually use <a href="UrlWriter.html">ActionController::UrlWriter</a> under
the hood. And in particular, they use the <a
href="UrlWriter.html#M000070">ActionController::UrlWriter#url_for</a>
method. One can generate the same path as the above example by using the
following code:
</p>
<pre>
include UrlWriter
url_for(:controller => 'users',
:action => 'new',
:message => 'Welcome!',
:only_path => true)
# => "/users/new?message=Welcome%21"
</pre>
<p>
Notice the <tt>:only_path => true</tt> part. This is because <a
href="UrlWriter.html">UrlWriter</a> has no information about the website
hostname that your Rails app is serving. So if you want to include the
hostname as well, then you must also pass the <tt>:host</tt> argument:
</p>
<pre>
include UrlWriter
url_for(:controller => 'users',
:action => 'new',
:message => 'Welcome!',
:host => 'www.example.com') # Changed this.
# => "http://www.example.com/users/new?message=Welcome%21"
</pre>
<p>
By default, all controllers and views have access to a special version of
<a href="UrlWriter.html#M000070">url_for</a>, that already knows what the
current hostname is. So if you use <a
href="UrlWriter.html#M000070">url_for</a> in your controllers or your
views, then you don‘t need to explicitly pass the <tt>:host</tt>
argument.
</p>
<p>
For convenience reasons, mailers provide a shortcut for <a
href="UrlWriter.html#M000070">ActionController::UrlWriter#url_for</a>. So
within mailers, you only have to type ‘<a
href="UrlWriter.html#M000070">url_for</a>’ instead of ‘<a
href="UrlWriter.html#M000070">ActionController::UrlWriter#url_for</a>’
in full. However, mailers don‘t have hostname information, and
what‘s why you‘ll still have to specify the <tt>:host</tt>
argument when generating URLs in mailers.
</p>
<h2>URL generation for named routes</h2>
<p>
<a href="UrlWriter.html">UrlWriter</a> also allows one to access methods
that have been auto-generated from named routes. For example, suppose that
you have a ‘users’ resource in your <b>routes.rb</b>:
</p>
<pre>
map.resources :users
</pre>
<p>
This generates, among other things, the method <tt>users_path</tt>. By
default, this method is accessible from your controllers, views and
mailers. If you need to access this auto-generated method from other places
(such as a model), then you can do that in two ways.
</p>
<p>
The first way is to include <a
href="UrlWriter.html">ActionController::UrlWriter</a> in your class:
</p>
<pre>
class User < ActiveRecord::Base
include ActionController::UrlWriter # !!!
def name=(value)
write_attribute('name', value)
write_attribute('base_uri', users_path) # !!!
end
end
</pre>
<p>
The second way is to access them through <a
href="UrlWriter.html">ActionController::UrlWriter</a>. The autogenerated
named routes methods are available as class methods:
</p>
<pre>
class User < ActiveRecord::Base
def name=(value)
write_attribute('name', value)
path = ActionController::UrlWriter.users_path # !!!
write_attribute('base_uri', path) # !!!
end
end
</pre>
</div>
</div>
<div id="method-list">
<h3 class="section-bar">Methods</h3>
<div class="name-list">
<a href="#M000070">url_for</a>
</div>
</div>
</div>
<!-- if includes -->
<div id="section">
<!-- if method_list -->
<div id="methods">
<h3 class="section-bar">Public Instance methods</h3>
<div id="method-M000070" class="method-detail">
<a name="M000070"></a>
<div class="method-heading">
<a href="UrlWriter.src/M000070.html" target="Code" class="method-signature"
onclick="popupCode('UrlWriter.src/M000070.html');return false;">
<span class="method-name">url_for</span><span class="method-args">(options)</span>
</a>
</div>
<div class="method-description">
<p>
Generate a url based on the options provided, default_url_options and the
routes defined in routes.rb. The following options are supported:
</p>
<ul>
<li><tt>:only_path</tt> - If true, the relative url is returned. Defaults to
<tt>false</tt>.
</li>
<li><tt>:protocol</tt> - The protocol to connect to. Defaults to
‘http’.
</li>
<li><tt>:host</tt> - Specifies the host the link should be targetted at. If
<tt>:only_path</tt> is false, this option must be provided either
explicitly, or via <tt>default_url_options</tt>.
</li>
<li><tt>:port</tt> - Optionally specify the port to connect to.
</li>
<li><tt>:anchor</tt> - An anchor name to be appended to the path.
</li>
<li><tt>:skip_relative_url_root</tt> - If true, the url is not constructed
using the <tt>relative_url_root</tt> set in
ActionController::Base.relative_url_root.
</li>
<li><tt>:trailing_slash</tt> - If true, adds a trailing slash, as in
"/archive/2009/"
</li>
</ul>
<p>
Any other key (<tt>:controller</tt>, <tt>:action</tt>, etc.) given to
<tt><a href="UrlWriter.html#M000070">url_for</a></tt> is forwarded to the
Routes module.
</p>
<p>
Examples:
</p>
<pre>
url_for :controller => 'tasks', :action => 'testing', :host=>'somehost.org', :port=>'8080' # => 'http://somehost.org:8080/tasks/testing'
url_for :controller => 'tasks', :action => 'testing', :host=>'somehost.org', :anchor => 'ok', :only_path => true # => '/tasks/testing#ok'
url_for :controller => 'tasks', :action => 'testing', :trailing_slash=>true # => 'http://somehost.org/tasks/testing/'
url_for :controller => 'tasks', :action => 'testing', :host=>'somehost.org', :number => '33' # => 'http://somehost.org/tasks/testing?number=33'
</pre>
</div>
</div>
</div>
</div>
<div id="validator-badges">
<p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
8b99df826c3b6cf56a1caaae5f931d50
>
files
>
690
