28722c93ca5d6c198c4fd286cb2485a19e1cbd39
[depot.git] / polymorphic_routes.rb
1 module ActionController
2 # Polymorphic URL helpers are methods for smart resolution to a named route call when
3 # given an Active Record model instance. They are to be used in combination with
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])
12 #
13 # results in:
14 #
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
24 # <tt>form_for(@article)</tt> without having to specify <tt>:url</tt> parameter for the form
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 # * <tt>formatted_polymorphic_url</tt>, <tt>formatted_polymorphic_path</tt>
40 #
41 # Example usage:
42 #
43 # edit_polymorphic_path(@post) # => "/posts/1/edit"
44 # formatted_polymorphic_path([@post, :pdf]) # => "/posts/1.pdf"
45 module PolymorphicRoutes
46 # Constructs a call to a named RESTful route for the given record and returns the
47 # resulting URL string. For example:
48 #
49 # # calls post_url(post)
50 # polymorphic_url(post) # => "http://example.com/posts/1"
51 # polymorphic_url([blog, post]) # => "http://example.com/blogs/1/posts/1"
52 # polymorphic_url([:admin, blog, post]) # => "http://example.com/admin/blogs/1/posts/1"
53 # polymorphic_url([user, :blog, post]) # => "http://example.com/users/1/blog/posts/1"
54 #
55 # ==== Options
56 #
57 # * <tt>:action</tt> - Specifies the action prefix for the named route:
58 # <tt>:new</tt>, <tt>:edit</tt>, or <tt>:formatted</tt>. Default is no prefix.
59 # * <tt>:routing_type</tt> - Allowed values are <tt>:path</tt> or <tt>:url</tt>.
60 # Default is <tt>:url</tt>.
61 #
62 # ==== Examples
63 #
64 # # an Article record
65 # polymorphic_url(record) # same as article_url(record)
66 #
67 # # a Comment record
68 # polymorphic_url(record) # same as comment_url(record)
69 #
70 # # it recognizes new records and maps to the collection
71 # record = Comment.new
72 # polymorphic_url(record) # same as comments_url()
73 #
74 def polymorphic_url(record_or_hash_or_array, options = {})
75 if record_or_hash_or_array.kind_of?(Array)
76 record_or_hash_or_array = record_or_hash_or_array.compact
77 record_or_hash_or_array = record_or_hash_or_array[0] if record_or_hash_or_array.size == 1
78 end
79
80 record = extract_record(record_or_hash_or_array)
81 format = extract_format(record_or_hash_or_array, options)
82 namespace = extract_namespace(record_or_hash_or_array)
83
84 args = case record_or_hash_or_array
85 when Hash; [ record_or_hash_or_array ]
86 when Array; record_or_hash_or_array.dup
87 else [ record_or_hash_or_array ]
88 end
89
90 inflection =
91 case
92 when options[:action].to_s == "new"
93 args.pop
94 :singular
95 when record.respond_to?(:new_record?) && record.new_record?
96 args.pop
97 :plural
98 else
99 :singular
100 end
101
102 args.delete_if {|arg| arg.is_a?(Symbol) || arg.is_a?(String)}
103 args << format if format
104
105 named_route = build_named_route_call(record_or_hash_or_array, namespace, inflection, options)
106
107 url_options = options.except(:action, :routing_type, :format)
108 unless url_options.empty?
109 args.last.kind_of?(Hash) ? args.last.merge!(url_options) : args << url_options
110 end
111
112 __send__(named_route, *args)
113 end
114
115 # Returns the path component of a URL for the given record. It uses
116 # <tt>polymorphic_url</tt> with <tt>:routing_type => :path</tt>.
117 def polymorphic_path(record_or_hash_or_array, options = {})
118 options[:routing_type] = :path
119 polymorphic_url(record_or_hash_or_array, options)
120 end
121
122 %w(edit new formatted).each do |action|
123 module_eval <<-EOT, __FILE__, __LINE__
124 def #{action}_polymorphic_url(record_or_hash, options = {})
125 polymorphic_url(record_or_hash, options.merge(:action => "#{action}"))
126 end
127
128 def #{action}_polymorphic_path(record_or_hash, options = {})
129 polymorphic_url(record_or_hash, options.merge(:action => "#{action}", :routing_type => :path))
130 end
131 EOT
132 end
133
134 private
135 def action_prefix(options)
136 options[:action] ? "#{options[:action]}_" : options[:format] ? "formatted_" : ""
137 end
138
139 def routing_type(options)
140 options[:routing_type] || :url
141 end
142
143 def build_named_route_call(records, namespace, inflection, options = {})
144 unless records.is_a?(Array)
145 record = extract_record(records)
146 route = ''
147 else
148 record = records.pop
149 route = records.inject("") do |string, parent|
150 if parent.is_a?(Symbol) || parent.is_a?(String)
151 string << "#{parent}_"
152 else
153 string << "#{RecordIdentifier.__send__("singular_class_name", parent)}_"
154 end
155 end
156 end
157
158 if record.is_a?(Symbol) || record.is_a?(String)
159 route << "#{record}_"
160 else
161 route << "#{RecordIdentifier.__send__("#{inflection}_class_name", record)}_"
162 end
163
164 action_prefix(options) + namespace + route + routing_type(options).to_s
165 end
166
167 def extract_record(record_or_hash_or_array)
168 case record_or_hash_or_array
169 when Array; record_or_hash_or_array.last
170 when Hash; record_or_hash_or_array[:id]
171 else record_or_hash_or_array
172 end
173 end
174
175 def extract_format(record_or_hash_or_array, options)
176 if options[:action].to_s == "formatted" && record_or_hash_or_array.is_a?(Array)
177 record_or_hash_or_array.pop
178 elsif options[:format]
179 options[:format]
180 else
181 nil
182 end
183 end
184
185 # Remove the first symbols from the array and return the url prefix
186 # implied by those symbols.
187 def extract_namespace(record_or_hash_or_array)
188 return "" unless record_or_hash_or_array.is_a?(Array)
189
190 namespace_keys = []
191 while (key = record_or_hash_or_array.first) && key.is_a?(String) || key.is_a?(Symbol)
192 namespace_keys << record_or_hash_or_array.shift
193 end
194
195 namespace_keys.map {|k| "#{k}_"}.join
196 end
197 end
198 end