Ruby on Rails | Screencasts | Download | Documentation | Weblog | Community | Source

Changeset 8472

Show
Ignore:
Timestamp:
12/21/07 21:42:27 (5 months ago)
Author:
bitsweat
Message:

Document custom methods. Closes #10589.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/activeresource/CHANGELOG

    r8462 r8472  
    11*SVN* 
     2 
     3* Document custom methods.  #10589 [Cheah Chu Yeow] 
    24 
    35* Ruby 1.9 compatibility.  [Jeremy Kemper] 

  • trunk/activeresource/lib/active_resource/base.rb

    r8364 r8472  
    66  # ActiveResource::Base is the main class for mapping RESTful resources as models in a Rails application. 
    77  # 
    8   # For an outline of what Active Resource is capable of, see link:files/README.html. 
     8  # For an outline of what Active Resource is capable of, see link:files/vendor/rails/activeresource/README.html. 
    99  # 
    1010  # == Automated mapping 
    …… 
    3434  #  
    3535  #   ryan = Person.find(1) 
    36   #   # => Resource holding our newly create Person object 
     36  #   # => Resource holding our newly created Person object 
    3737  #  
    3838  #   ryan.first = 'Rizzle' 
    …… 
    4747  # 
    4848  # Since simple CRUD/lifecycle methods can't accomplish every task, Active Resource also supports 
    49   # defining your own custom REST methods. 
    50   #  
    51   #   Person.new(:name => 'Ryan).post(:register) 
     49  # defining your own custom REST methods. To invoke them, Active Resource provides the <tt>get</tt>, 
     50  # <tt>post</tt>, <tt>post</tt> and <tt>put</tt> methods where you can specify a custom REST method 
     51  # name to invoke. 
     52  # 
     53  #   # POST to the custom 'register' REST method, i.e. POST /people/new/register.xml. 
     54  #   Person.new(:name => 'Ryan').post(:register) 
    5255  #   # => { :id => 1, :name => 'Ryan', :position => 'Clerk' } 
    5356  # 
     57  #   # PUT an update by invoking the 'promote' REST method, i.e. PUT /people/1/promote.xml?position=Manager. 
    5458  #   Person.find(1).put(:promote, :position => 'Manager') 
    5559  #   # => { :id => 1, :name => 'Ryan', :position => 'Manager' } 
    56   #  
    57   # For more information on creating and using custom REST methods, see the  
     60  # 
     61  #   # GET all the positions available, i.e. GET /people/positions.xml. 
     62  #   Person.get(:positions) 
     63  #   # => [{:name => 'Manager'}, {:name => 'Clerk'}] 
     64  # 
     65  #   # DELETE to 'fire' a person, i.e. DELETE /people/1/fire.xml. 
     66  #   Person.find(1).delete(:fire) 
     67  #  
     68  # For more information on using custom REST methods, see the 
    5869  # ActiveResource::CustomMethods documentation. 
    5970  # 
    …… 
    8899  # 
    89100  # Error handling and validation is handled in much the same manner as you're used to seeing in 
    90   # Active Record.  Both the response code in the Http response and the body of the response are used to 
     101  # Active Record.  Both the response code in the HTTP response and the body of the response are used to 
    91102  # indicate that an error occurred. 
    92103  #  
    93104  # === Resource errors 
    94105  #  
    95   # When a get is requested for a resource that does not exist, the HTTP +404+ (Resource Not Found) 
     106  # When a GET is requested for a resource that does not exist, the HTTP <tt>404</tt> (Resource Not Found) 
    96107  # response code will be returned from the server which will raise an ActiveResource::ResourceNotFound 
    97108  # exception. 
    …… 
    101112  #   # => Response = 404 
    102113  #  
    103   # +404+ is just one of the HTTP error response codes that ActiveResource will handle with its own exception. The  
     114  # <tt>404</tt> is just one of the HTTP error response codes that ActiveResource will handle with its own exception. The 
    104115  # following HTTP response codes will also result in these exceptions: 
    105116  #  
    …… 
    126137  # Active Resource supports validations on resources and will return errors if any these validations fail 
    127138  # (e.g., "First name can not be blank" and so on).  These types of errors are denoted in the response by  
    128   # a response code of +422+ and an XML representation of the validation errors.  The save operation will  
    129   # then fail (with a +false+ return value) and the validation errors can be accessed on the resource in question. 
     139  # a response code of <tt>422</tt> and an XML representation of the validation errors.  The save operation will 
     140  # then fail (with a <tt>false</tt> return value) and the validation errors can be accessed on the resource in question. 
    130141  #  
    131142  #   ryan = Person.find(1) 
    …… 
    192203      # An instance of ActiveResource::Connection that is the base connection to the remote service. 
    193204      # The +refresh+ parameter toggles whether or not the connection is refreshed at every request 
    194       # or not (defaults to +false+). 
     205      # or not (defaults to <tt>false</tt>). 
    195206      def connection(refresh = false) 
    196207        if defined?(@connection) || superclass == Object 
    …… 
    372383      #   Person.find(:one, :from => :leader)                     
    373384      #   # => GET /people/leader.xml 
     385      # 
     386      #   Person.find(:all, :from => :developers, :params => { :language => 'ruby' }) 
     387      #   # => GET /people/developers.xml?language=ruby 
    374388      # 
    375389      #   Person.find(:one, :from => "/companies/1/manager.xml")  
    …… 
    688702    # indent:: Set the indent level for the XML output (default is +2+). 
    689703    # dasherize:: Boolean option to determine whether or not element names should 
    690     #             replace underscores with dashes (default is +false+). 
     704    #             replace underscores with dashes (default is <tt>false</tt>). 
    691705    # skip_instruct::  Toggle skipping the +instruct!+ call on the XML builder  
    692     #                  that generates the XML declaration (default is +false+). 
     706    #                  that generates the XML declaration (default is <tt>false</tt>). 
    693707    # 
    694708    # ==== Examples 
    …… 
    770784 
    771785    # A method to determine if an object responds to a message (e.g., a method call). In Active Resource, a +Person+ object with a 
    772     # +name+ attribute can answer +true+ to +my_person.respond_to?("name")+, +my_person.respond_to?("name=")+, and 
    773     # +my_person.respond_to?("name?")+. 
     786    # +name+ attribute can answer <tt>true</tt> to <tt>my_person.respond_to?("name")</tt>, <tt>my_person.respond_to?("name=")</tt>, and 
     787    # <tt>my_person.respond_to?("name?")</tt>. 
    774788    def respond_to?(method, include_priv = false) 
    775789      method_name = method.to_s 

  • trunk/activeresource/lib/active_resource/custom_methods.rb

    r7719 r8472  
    1 # A module to support custom REST methods and sub-resources, allowing you to break out 
    2 # of the "default" REST methods with your own custom resource requests.  For example,  
    3 # say you use Rails to expose a REST service and configure your routes with: 
    4 # 
    5 #    map.resources :people, :new => { :register => :post }, 
    6 #                           :element => { :promote => :put, :deactivate => :delete } 
    7 #                           :collection => { :active => :get } 
    8 # 
    9 #  This route set creates routes for the following http requests: 
    10 # 
    11 #    POST    /people/new/register.xml #=> PeopleController.register 
    12 #    PUT     /people/1/promote.xml    #=> PeopleController.promote with :id => 1 
    13 #    DELETE  /people/1/deactivate.xml #=> PeopleController.deactivate with :id => 1 
    14 #    GET     /people/active.xml       #=> PeopleController.active 
    15 # 
    16 # Using this module, Active Resource can use these custom REST methods just like the 
    17 # standard methods. 
    18 # 
    19 #   class Person < ActiveResource::Base 
    20 #     self.site = "http://37s.sunrise.i:3000" 
    21 #   end 
    22 # 
    23 #   Person.new(:name => 'Ryan).post(:register)  # POST /people/new/register.xml 
    24 #   # => { :id => 1, :name => 'Ryan' } 
    25 # 
    26 #   Person.find(1).put(:promote, :position => 'Manager') # PUT /people/1/promote.xml 
    27 #   Person.find(1).delete(:deactivate) # DELETE /people/1/deactivate.xml 
    28 # 
    29 #   Person.get(:active)  # GET /people/active.xml  
    30 #   # => [{:id => 1, :name => 'Ryan'}, {:id => 2, :name => 'Joe'}] 
    31 # 
    321module 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  #                           :element => { :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  # 
    3333  module CustomMethods  
    34     def self.included(within) 
    35       within.class_eval do 
     34    def self.included(base) 
     35      base.class_eval do 
    3636        extend ActiveResource::CustomMethods::ClassMethods 
    3737        include ActiveResource::CustomMethods::InstanceMethods 
    …… 
    4040          alias :orig_delete :delete 
    4141 
    42           def get(method_name, options = {}) 
    43             connection.get(custom_method_collection_url(method_name, options), headers) 
     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 instances - they are ordinary Hashes. If you are expecting 
     52          # ActiveResource 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) 
    4458          end 
    4559 
    46           def post(method_name, options = {}, body = '') 
    47             connection.post(custom_method_collection_url(method_name, options), body, headers) 
     60          def post(custom_method_name, options = {}, body = '') 
     61            connection.post(custom_method_collection_url(custom_method_name, options), body, headers) 
    4862          end 
    4963 
    50           def put(method_name, options = {}, body = '') 
    51             connection.put(custom_method_collection_url(method_name, options), body, headers) 
     64          def put(custom_method_name, options = {}, body = '') 
     65            connection.put(custom_method_collection_url(custom_method_name, options), body, headers) 
    5266          end 
    5367 
    54           # Need to jump through some hoops to retain the original class 'delete' method 
    5568          def delete(custom_method_name, options = {}) 
    56             if (custom_method_name.is_a?(Symbol)) 
     69            # Need to jump through some hoops to retain the original class 'delete' method 
     70            if custom_method_name.is_a?(Symbol) 
    5771              connection.delete(custom_method_collection_url(custom_method_name, options), headers) 
    5872            else