Functional tests now work properly, bearing in mind whether a user is logged in or...
[depot.git] / vendor / rails / activeresource / lib / active_resource / custom_methods.rb
1 module ActiveResource
2 # A module to support custom REST methods and sub-resources, allowing you to break out
3 # of the "default" REST methods with your own custom resource requests. For example,
4 # say you use Rails to expose a REST service and configure your routes with:
5 #
6 # map.resources :people, :new => { :register => :post },
7 # :member => { :promote => :put, :deactivate => :delete }
8 # :collection => { :active => :get }
9 #
10 # This route set creates routes for the following HTTP requests:
11 #
12 # POST /people/new/register.xml # PeopleController.register
13 # PUT /people/1/promote.xml # PeopleController.promote with :id => 1
14 # DELETE /people/1/deactivate.xml # PeopleController.deactivate with :id => 1
15 # GET /people/active.xml # PeopleController.active
16 #
17 # Using this module, Active Resource can use these custom REST methods just like the
18 # standard methods.
19 #
20 # class Person < ActiveResource::Base
21 # self.site = "http://37s.sunrise.i:3000"
22 # end
23 #
24 # Person.new(:name => 'Ryan).post(:register) # POST /people/new/register.xml
25 # # => { :id => 1, :name => 'Ryan' }
26 #
27 # Person.find(1).put(:promote, :position => 'Manager') # PUT /people/1/promote.xml
28 # Person.find(1).delete(:deactivate) # DELETE /people/1/deactivate.xml
29 #
30 # Person.get(:active) # GET /people/active.xml
31 # # => [{:id => 1, :name => 'Ryan'}, {:id => 2, :name => 'Joe'}]
32 #
33 module CustomMethods
34 def self.included(base)
35 base.class_eval do
36 extend ActiveResource::CustomMethods::ClassMethods
37 include ActiveResource::CustomMethods::InstanceMethods
38
39 class << self
40 alias :orig_delete :delete
41
42 # Invokes a GET to a given custom REST method. For example:
43 #
44 # Person.get(:active) # GET /people/active.xml
45 # # => [{:id => 1, :name => 'Ryan'}, {:id => 2, :name => 'Joe'}]
46 #
47 # Person.get(:active, :awesome => true) # GET /people/active.xml?awesome=true
48 # # => [{:id => 1, :name => 'Ryan'}]
49 #
50 # Note: the objects returned from this method are not automatically converted
51 # into ActiveResource::Base instances - they are ordinary Hashes. If you are expecting
52 # ActiveResource::Base instances, use the <tt>find</tt> class method with the
53 # <tt>:from</tt> option. For example:
54 #
55 # Person.find(:all, :from => :active)
56 def get(custom_method_name, options = {})
57 connection.get(custom_method_collection_url(custom_method_name, options), headers)
58 end
59
60 def post(custom_method_name, options = {}, body = '')
61 connection.post(custom_method_collection_url(custom_method_name, options), body, headers)
62 end
63
64 def put(custom_method_name, options = {}, body = '')
65 connection.put(custom_method_collection_url(custom_method_name, options), body, headers)
66 end
67
68 def delete(custom_method_name, options = {})
69 # Need to jump through some hoops to retain the original class 'delete' method
70 if custom_method_name.is_a?(Symbol)
71 connection.delete(custom_method_collection_url(custom_method_name, options), headers)
72 else
73 orig_delete(custom_method_name, options)
74 end
75 end
76 end
77 end
78 end
79
80 module ClassMethods
81 def custom_method_collection_url(method_name, options = {})
82 prefix_options, query_options = split_options(options)
83 "#{prefix(prefix_options)}#{collection_name}/#{method_name}.#{format.extension}#{query_string(query_options)}"
84 end
85 end
86
87 module InstanceMethods
88 def get(method_name, options = {})
89 connection.get(custom_method_element_url(method_name, options), self.class.headers)
90 end
91
92 def post(method_name, options = {}, body = nil)
93 request_body = body.blank? ? encode : body
94 if new?
95 connection.post(custom_method_new_element_url(method_name, options), request_body, self.class.headers)
96 else
97 connection.post(custom_method_element_url(method_name, options), request_body, self.class.headers)
98 end
99 end
100
101 def put(method_name, options = {}, body = '')
102 connection.put(custom_method_element_url(method_name, options), body, self.class.headers)
103 end
104
105 def delete(method_name, options = {})
106 connection.delete(custom_method_element_url(method_name, options), self.class.headers)
107 end
108
109
110 private
111 def custom_method_element_url(method_name, options = {})
112 "#{self.class.prefix(prefix_options)}#{self.class.collection_name}/#{id}/#{method_name}.#{self.class.format.extension}#{self.class.__send__(:query_string, options)}"
113 end
114
115 def custom_method_new_element_url(method_name, options = {})
116 "#{self.class.prefix(prefix_options)}#{self.class.collection_name}/new/#{method_name}.#{self.class.format.extension}#{self.class.__send__(:query_string, options)}"
117 end
118 end
119 end
120 end