Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 205 lines (184 sloc) 8.486 kb
c769ad8 @dhh Removed deprecated parameters_for_method_reference concept (legacy fr…
dhh authored
1 module ActionController
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
2 # Polymorphic URL helpers are methods for smart resolution to a named route call when
98dc582 @lifo Merge docrails.
lifo authored
3 # given an Active Record model instance. They are to be used in combination with
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
4 # ActionController::Resources.
5 #
6 # These methods are useful when you want to generate correct URL or path to a RESTful
7 # resource without having to know the exact type of the record in question.
8 #
9 # Nested resources and/or namespaces are also supported, as illustrated in the example:
10 #
11 # polymorphic_url([:admin, @article, @comment])
98dc582 @lifo Merge docrails.
lifo authored
12 #
13 # results in:
14 #
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
15 # admin_article_comment_url(@article, @comment)
16 #
17 # == Usage within the framework
18 #
19 # Polymorphic URL helpers are used in a number of places throughout the Rails framework:
20 #
21 # * <tt>url_for</tt>, so you can use it with a record as the argument, e.g.
22 # <tt>url_for(@article)</tt>;
23 # * ActionView::Helpers::FormHelper uses <tt>polymorphic_path</tt>, so you can write
64092de @fxn Improve documentation coverage and markup
fxn authored
24 # <tt>form_for(@article)</tt> without having to specify <tt>:url</tt> parameter for the form
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
25 # action;
26 # * <tt>redirect_to</tt> (which, in fact, uses <tt>url_for</tt>) so you can write
27 # <tt>redirect_to(post)</tt> in your controllers;
28 # * ActionView::Helpers::AtomFeedHelper, so you don't have to explicitly specify URLs
29 # for feed entries.
30 #
31 # == Prefixed polymorphic helpers
32 #
33 # In addition to <tt>polymorphic_url</tt> and <tt>polymorphic_path</tt> methods, a
34 # number of prefixed helpers are available as a shorthand to <tt>:action => "..."</tt>
35 # in options. Those are:
36 #
37 # * <tt>edit_polymorphic_url</tt>, <tt>edit_polymorphic_path</tt>
38 # * <tt>new_polymorphic_url</tt>, <tt>new_polymorphic_path</tt>
39 #
40 # Example usage:
41 #
98dc582 @lifo Merge docrails.
lifo authored
42 # edit_polymorphic_path(@post) # => "/posts/1/edit"
93456a2 @jeremy Deprecated formatted_polymorphic_url
jeremy authored
43 # polymorphic_path(@post, :format => :pdf) # => "/posts/1.pdf"
c769ad8 @dhh Removed deprecated parameters_for_method_reference concept (legacy fr…
dhh authored
44 module PolymorphicRoutes
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
45 # Constructs a call to a named RESTful route for the given record and returns the
46 # resulting URL string. For example:
47 #
dc4eec1 @lifo Merge docrails:
lifo authored
48 # # calls post_url(post)
49 # polymorphic_url(post) # => "http://example.com/posts/1"
bb6e8ee Fixed polymorphic_url to be able to handle singleton resources.
Tammer Saleh authored
50 # polymorphic_url([blog, post]) # => "http://example.com/blogs/1/posts/1"
51 # polymorphic_url([:admin, blog, post]) # => "http://example.com/admin/blogs/1/posts/1"
52 # polymorphic_url([user, :blog, post]) # => "http://example.com/users/1/blog/posts/1"
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
53 #
54 # ==== Options
dc4eec1 @lifo Merge docrails:
lifo authored
55 #
56 # * <tt>:action</tt> - Specifies the action prefix for the named route:
93456a2 @jeremy Deprecated formatted_polymorphic_url
jeremy authored
57 # <tt>:new</tt> or <tt>:edit</tt>. Default is no prefix.
dc4eec1 @lifo Merge docrails:
lifo authored
58 # * <tt>:routing_type</tt> - Allowed values are <tt>:path</tt> or <tt>:url</tt>.
59 # Default is <tt>:url</tt>.
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
60 #
61 # ==== Examples
62 #
63 # # an Article record
dc4eec1 @lifo Merge docrails:
lifo authored
64 # polymorphic_url(record) # same as article_url(record)
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
65 #
66 # # a Comment record
dc4eec1 @lifo Merge docrails:
lifo authored
67 # polymorphic_url(record) # same as comment_url(record)
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
68 #
69 # # it recognizes new records and maps to the collection
70 # record = Comment.new
dc4eec1 @lifo Merge docrails:
lifo authored
71 # polymorphic_url(record) # same as comments_url()
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
72 #
5dd3db8 @jeremy Resources: url_for([parent, child]) generates /parents/1/children/2 f…
jeremy authored
73 def polymorphic_url(record_or_hash_or_array, options = {})
db08329 @dhh Fixed that polymorphic routes would modify the input array (closes #1…
dhh authored
74 if record_or_hash_or_array.kind_of?(Array)
94d6716 @hiroshi Make polymorphic_url compact given array [#1317 state:committed]
hiroshi authored
75 record_or_hash_or_array = record_or_hash_or_array.compact
291d199 @hiroshi Let polymorphic_path treat an array contains single name as without a…
hiroshi authored
76 record_or_hash_or_array = record_or_hash_or_array[0] if record_or_hash_or_array.size == 1
db08329 @dhh Fixed that polymorphic routes would modify the input array (closes #1…
dhh authored
77 end
78
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
79 record = extract_record(record_or_hash_or_array)
9014bf3 * url_for now accepts a series of symbols representing the namespace …
Tobias Lütke authored
80 namespace = extract_namespace(record_or_hash_or_array)
93456a2 @jeremy Deprecated formatted_polymorphic_url
jeremy authored
81
c7df5bd @jeremy More nested polymorphic url helper fixes. Closes #6432, references #8…
jeremy authored
82 args = case record_or_hash_or_array
0ee1cb2 @jeremy Ruby 1.9 compat, consistent load paths
jeremy authored
83 when Hash; [ record_or_hash_or_array ]
84 when Array; record_or_hash_or_array.dup
20045df @dhh Temporary fix for formatted_polymorphic_urls and other polys that hav…
dhh authored
85 else [ record_or_hash_or_array ]
86 end
c7df5bd @jeremy More nested polymorphic url helper fixes. Closes #6432, references #8…
jeremy authored
87
5dd3db8 @jeremy Resources: url_for([parent, child]) generates /parents/1/children/2 f…
jeremy authored
88 inflection =
89 case
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
90 when options[:action].to_s == "new"
20045df @dhh Temporary fix for formatted_polymorphic_urls and other polys that hav…
dhh authored
91 args.pop
5dd3db8 @jeremy Resources: url_for([parent, child]) generates /parents/1/children/2 f…
jeremy authored
92 :singular
93 when record.respond_to?(:new_record?) && record.new_record?
20045df @dhh Temporary fix for formatted_polymorphic_urls and other polys that hav…
dhh authored
94 args.pop
5dd3db8 @jeremy Resources: url_for([parent, child]) generates /parents/1/children/2 f…
jeremy authored
95 :plural
96 else
97 :singular
98 end
bb6e8ee Fixed polymorphic_url to be able to handle singleton resources.
Tammer Saleh authored
99
100 args.delete_if {|arg| arg.is_a?(Symbol) || arg.is_a?(String)}
93456a2 @jeremy Deprecated formatted_polymorphic_url
jeremy authored
101
9014bf3 * url_for now accepts a series of symbols representing the namespace …
Tobias Lütke authored
102 named_route = build_named_route_call(record_or_hash_or_array, namespace, inflection, options)
98fb161 @tarmo Allow polymorphic_url helper to take url options. [#880 state:resolved]
tarmo authored
103
93456a2 @jeremy Deprecated formatted_polymorphic_url
jeremy authored
104 url_options = options.except(:action, :routing_type)
98fb161 @tarmo Allow polymorphic_url helper to take url options. [#880 state:resolved]
tarmo authored
105 unless url_options.empty?
106 args.last.kind_of?(Hash) ? args.last.merge!(url_options) : args << url_options
107 end
108
a1eb4e1 @jeremy Get rid of 'Object#send!'. It was originally added because it's in Ru…
jeremy authored
109 __send__(named_route, *args)
c769ad8 @dhh Removed deprecated parameters_for_method_reference concept (legacy fr…
dhh authored
110 end
111
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
112 # Returns the path component of a URL for the given record. It uses
113 # <tt>polymorphic_url</tt> with <tt>:routing_type => :path</tt>.
114 def polymorphic_path(record_or_hash_or_array, options = {})
115 options[:routing_type] = :path
116 polymorphic_url(record_or_hash_or_array, options)
c769ad8 @dhh Removed deprecated parameters_for_method_reference concept (legacy fr…
dhh authored
117 end
118
93456a2 @jeremy Deprecated formatted_polymorphic_url
jeremy authored
119 %w(edit new).each do |action|
1ac7cd5 @jeremy Clean up the simply_helpful merge.
jeremy authored
120 module_eval <<-EOT, __FILE__, __LINE__
a2270ef @fxn Inline code comments for class_eval/module_eval [#1657 state:resolved]
fxn authored
121 def #{action}_polymorphic_url(record_or_hash, options = {}) # def edit_polymorphic_url(record_or_hash, options = {})
122 polymorphic_url( # polymorphic_url(
123 record_or_hash, # record_or_hash,
124 options.merge(:action => "#{action}")) # options.merge(:action => "edit"))
125 end # end
126 #
127 def #{action}_polymorphic_path(record_or_hash, options = {}) # def edit_polymorphic_path(record_or_hash, options = {})
128 polymorphic_url( # polymorphic_url(
129 record_or_hash, # record_or_hash,
130 options.merge(:action => "#{action}", :routing_type => :path)) # options.merge(:action => "edit", :routing_type => :path))
131 end # end
c769ad8 @dhh Removed deprecated parameters_for_method_reference concept (legacy fr…
dhh authored
132 EOT
133 end
134
93456a2 @jeremy Deprecated formatted_polymorphic_url
jeremy authored
135 def formatted_polymorphic_url(record_or_hash, options = {})
136 ActiveSupport::Deprecation.warn("formatted_polymorphic_url has been deprecated. Please pass :format to the polymorphic_url method instead", caller)
137 options[:format] = record_or_hash.pop if Array === record_or_hash
138 polymorphic_url(record_or_hash, options)
139 end
140
141 def formatted_polymorphic_path(record_or_hash, options = {})
142 ActiveSupport::Deprecation.warn("formatted_polymorphic_path has been deprecated. Please pass :format to the polymorphic_path method instead", caller)
143 options[:format] = record_or_hash.pop if record_or_hash === Array
144 polymorphic_url(record_or_hash, options.merge(:routing_type => :path))
145 end
146
c769ad8 @dhh Removed deprecated parameters_for_method_reference concept (legacy fr…
dhh authored
147 private
148 def action_prefix(options)
93456a2 @jeremy Deprecated formatted_polymorphic_url
jeremy authored
149 options[:action] ? "#{options[:action]}_" : ''
c769ad8 @dhh Removed deprecated parameters_for_method_reference concept (legacy fr…
dhh authored
150 end
1ac7cd5 @jeremy Clean up the simply_helpful merge.
jeremy authored
151
c769ad8 @dhh Removed deprecated parameters_for_method_reference concept (legacy fr…
dhh authored
152 def routing_type(options)
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
153 options[:routing_type] || :url
5dd3db8 @jeremy Resources: url_for([parent, child]) generates /parents/1/children/2 f…
jeremy authored
154 end
155
9014bf3 * url_for now accepts a series of symbols representing the namespace …
Tobias Lütke authored
156 def build_named_route_call(records, namespace, inflection, options = {})
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
157 unless records.is_a?(Array)
158 record = extract_record(records)
159 route = ''
160 else
161 record = records.pop
162 route = records.inject("") do |string, parent|
bb6e8ee Fixed polymorphic_url to be able to handle singleton resources.
Tammer Saleh authored
163 if parent.is_a?(Symbol) || parent.is_a?(String)
164 string << "#{parent}_"
165 else
d771e7d @ffmike Handle irregular plurals in polymorphic_urls [#2212 state:resolved]
ffmike authored
166 string << "#{RecordIdentifier.__send__("plural_class_name", parent)}".singularize
167 string << "_"
bb6e8ee Fixed polymorphic_url to be able to handle singleton resources.
Tammer Saleh authored
168 end
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
169 end
5dd3db8 @jeremy Resources: url_for([parent, child]) generates /parents/1/children/2 f…
jeremy authored
170 end
171
bb6e8ee Fixed polymorphic_url to be able to handle singleton resources.
Tammer Saleh authored
172 if record.is_a?(Symbol) || record.is_a?(String)
173 route << "#{record}_"
174 else
d771e7d @ffmike Handle irregular plurals in polymorphic_urls [#2212 state:resolved]
ffmike authored
175 route << "#{RecordIdentifier.__send__("plural_class_name", record)}"
176 route = route.singularize if inflection == :singular
177 route << "_"
bb6e8ee Fixed polymorphic_url to be able to handle singleton resources.
Tammer Saleh authored
178 end
f11904a @NZKoz Add documentation for polymorphic URL helpers, make API consistent f…
NZKoz authored
179
180 action_prefix(options) + namespace + route + routing_type(options).to_s
c769ad8 @dhh Removed deprecated parameters_for_method_reference concept (legacy fr…
dhh authored
181 end
1ac7cd5 @jeremy Clean up the simply_helpful merge.
jeremy authored
182
5dd3db8 @jeremy Resources: url_for([parent, child]) generates /parents/1/children/2 f…
jeremy authored
183 def extract_record(record_or_hash_or_array)
184 case record_or_hash_or_array
0ee1cb2 @jeremy Ruby 1.9 compat, consistent load paths
jeremy authored
185 when Array; record_or_hash_or_array.last
186 when Hash; record_or_hash_or_array[:id]
5dd3db8 @jeremy Resources: url_for([parent, child]) generates /parents/1/children/2 f…
jeremy authored
187 else record_or_hash_or_array
188 end
c769ad8 @dhh Removed deprecated parameters_for_method_reference concept (legacy fr…
dhh authored
189 end
93456a2 @jeremy Deprecated formatted_polymorphic_url
jeremy authored
190
bb6e8ee Fixed polymorphic_url to be able to handle singleton resources.
Tammer Saleh authored
191 # Remove the first symbols from the array and return the url prefix
192 # implied by those symbols.
9014bf3 * url_for now accepts a series of symbols representing the namespace …
Tobias Lütke authored
193 def extract_namespace(record_or_hash_or_array)
bb6e8ee Fixed polymorphic_url to be able to handle singleton resources.
Tammer Saleh authored
194 return "" unless record_or_hash_or_array.is_a?(Array)
195
196 namespace_keys = []
197 while (key = record_or_hash_or_array.first) && key.is_a?(String) || key.is_a?(Symbol)
198 namespace_keys << record_or_hash_or_array.shift
9014bf3 * url_for now accepts a series of symbols representing the namespace …
Tobias Lütke authored
199 end
bb6e8ee Fixed polymorphic_url to be able to handle singleton resources.
Tammer Saleh authored
200
201 namespace_keys.map {|k| "#{k}_"}.join
9014bf3 * url_for now accepts a series of symbols representing the namespace …
Tobias Lütke authored
202 end
c769ad8 @dhh Removed deprecated parameters_for_method_reference concept (legacy fr…
dhh authored
203 end
0ee1cb2 @jeremy Ruby 1.9 compat, consistent load paths
jeremy authored
204 end
Something went wrong with that request. Please try again.