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

Changeset 1728

Show
Ignore:
Timestamp:
07/06/05 08:27:11 (3 years ago)
Author:
david
Message:

Partly tuned docs for release (AP)

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/actionpack/CHANGELOG

    r1714 r1728  
    1 *SVN* 
     1*1.9.0* (6 July, 2005) 
     2 
     3* Fixed that a SessionRestoreError was thrown if a model object was placed in the session that wasn't available to all controllers 
    24 
    35* Added logging of the request URI in the benchmark statement (makes it easy to grep for slow actions) 

  • trunk/actionpack/lib/action_controller/auto_complete.rb

    r1606 r1728  
    11module ActionController 
    2   # Example: 
    3   # 
    4   #   # Controller 
    5   #   class BlogController < ApplicationController 
    6   #     auto_complete_for :post, :title 
    7   #   end 
    8   # 
    9   #   # View 
    10   #   <%= text_field_with_auto_complete :post, title %> 
    11   # 
    12   # By default, auto_complete_for limits the results to 10 entries, 
    13   # and sorts by the given field. 
    14   #  
    15   # auto_complete_for takes a third parameter, an options hash to 
    16   # the find method used to search for the records: 
    17   # 
    18   #   auto_complete_for :post, :title, :limit => 15, :order => 'created_at DESC' 
    19   # 
    20   # For help on defining text input fields with autocompletion,  
    21   # see ActionView::Helpers::JavascriptHelper. 
    22   module AutoComplete 
     2  module AutoComplete #:nodoc: 
    233    def self.append_features(base) #:nodoc: 
    244      super 
    …… 
    266    end 
    277 
     8    # Example: 
     9    # 
     10    #   # Controller 
     11    #   class BlogController < ApplicationController 
     12    #     auto_complete_for :post, :title 
     13    #   end 
     14    # 
     15    #   # View 
     16    #   <%= text_field_with_auto_complete :post, title %> 
     17    # 
     18    # By default, auto_complete_for limits the results to 10 entries, 
     19    # and sorts by the given field. 
     20    #  
     21    # auto_complete_for takes a third parameter, an options hash to 
     22    # the find method used to search for the records: 
     23    # 
     24    #   auto_complete_for :post, :title, :limit => 15, :order => 'created_at DESC' 
     25    # 
     26    # For help on defining text input fields with autocompletion,  
     27    # see ActionView::Helpers::JavascriptHelper. 
     28    # 
     29    # For more examples, see script.aculo.us: 
     30    # * http://script.aculo.us/demos/ajax/autocompleter 
     31    # * http://script.aculo.us/demos/ajax/autocompleter_customized 
    2832    module ClassMethods 
    2933      def auto_complete_for(object, method, options = {}) 

  • trunk/actionpack/lib/action_controller/base.rb

    r1714 r1728  
    6161  # request and response objects from the CGI 
    6262  # 
     63  # When Action Pack is used inside of Rails, the template_root is automatically configured and you don't need to call process_cgi 
     64  # yourself. 
     65  # 
    6366  # == Requests 
    6467  # 
    …… 
    6871  # the action through instance variables. Then the action is performed. 
    6972  # 
    70   # The full request object is available in @request and is primarily used to query for http headers. These queries are made by 
    71   # accessing the environment hash, like this: 
     73  # The full request object is available with the request accessor and is primarily used to query for http headers. These queries 
     74  # are made by accessing the environment hash, like this: 
    7275  # 
    7376  #   def hello_ip 
    74   #     location = @request.env["REMOTE_IP"] 
     77  #     location = request.env["REMOTE_IP"] 
    7578  #     render_text "Hello stranger from #{location}" 
    7679  #   end 
    …… 
    7881  # == Parameters 
    7982  # 
    80   # All request parameters whether they come from a GET or POST request, or from the URL, are available through the @params hash. 
     83  # All request parameters whether they come from a GET or POST request, or from the URL, are available through the params hash. 
    8184  # So an action that was performed through /weblog/list?category=All&limit=5 will include { "category" => "All", "limit" => 5 } 
    82   # in @params. 
     85  # in params. 
    8386  # 
    8487  # It's also possible to construct multi-dimensional parameter hashes by specifying keys using brackets, such as: 
    …… 
    8891  # 
    8992  # A request stemming from a form holding these inputs will include <tt>{ "post" => { "name" => "david", "address" => "hyacintvej" } }</tt>. 
    90   # If the address input had been named "post[address][street]", the @params would have included  
     93  # If the address input had been named "post[address][street]", the params would have included  
    9194  # <tt>{ "post" => { "address" => { "street" => "hyacintvej" } } }</tt>. There's no limit to the depth of the nesting. 
    9295  # 
    …… 
    98101  # they could be changed unknowingly. It's usually too much work to keep it all synchronized -- something databases already excel at. 
    99102  # 
    100   # You can place objects in the session by using the <tt>@session</tt> hash: 
    101   # 
    102   #   @session[:person] = Person.authenticate(user_name, password) 
     103  # You can place objects in the session by using the <tt>session</tt> hash accessor: 
     104  # 
     105  #   session[:person] = Person.authenticate(user_name, password) 
    103106  # 
    104107  # And retrieved again through the same hash: 
    105108  # 
    106   #   Hello #{@session[:person]} 
     109  #   Hello #{session[:person]} 
    107110  # 
    108111  # Any object can be placed in the session (as long as it can be Marshalled). But remember that 1000 active sessions each storing a 
    109112  # 50kb object could lead to a 50MB memory overhead. In other words, think carefully about size and caching before resorting to the use 
    110113  # of the session. 
    111   #  
    112   # If you store a model in the session, you must also include a line like: 
    113   # 
    114   #   model :person 
    115   # 
    116   # For that particular controller. In Rails, you can also just add it in your app/controller/application.rb file (so the model is available 
    117   # for all controllers). This lets Action Pack know to have the model definition loaded before retrieving the object from the session. 
    118114  # 
    119115  # For removing objects from the session, you can either assign a single key to nil, like <tt>@session[:person] = nil</tt>, or you can 
    …… 
    132128  # 
    133129  #   def show 
    134   #     @post = Post.find(@params["id"]) 
     130  #     @post = Post.find(params[:id]) 
    135131  #   end 
    136132  # 
    …… 
    143139  # 
    144140  #   def search 
    145   #     @results = Search.find(@params["query"]) 
     141  #     @results = Search.find(params[:query]) 
    146142  #     case @results 
    147   #       when 0 then render "weblog/no_results" 
    148   #       when 1 then render_action "show" 
    149   #       when 2..10 then render_action "show_many" 
     143  #       when 0 then render :action=> "no_results" 
     144  #       when 1 then render :action=> "show" 
     145  #       when 2..10 then render :action=> "show_many" 
    150146  #     end 
    151147  #   end 
    …… 
    188184  #   def do_something 
    189185  #     redirect_to :action => "elsewhere" 
    190   #     render_action "overthere" 
     186  #     render :action => "overthere" 
    191187  #   end 
    192188  # 
    …… 
    449445 
    450446    protected 
    451       # Renders the template specified by <tt>template_name</tt>, which defaults to the name of the current controller and action. 
    452       # So calling +render+ in WeblogController#show will attempt to render "#{template_root}/weblog/show.rhtml" or  
    453       # "#{template_root}/weblog/show.rxml" (in that order). The template_root is set on the ActionController::Base class and is  
    454       # shared by all controllers. It's also possible to pass a status code using the second parameter. This defaults to "200 OK",  
    455       # but can be changed, such as by calling <tt>render("weblog/error", "500 Error")</tt>. 
    456  
    457       # A unified replacement for the individual renders (work-in-progress). 
    458       def render(options = {}, deprecated_status = nil) 
     447      # Renders the content that'll be returned to the browser as the response body. This can just be as regular text, but is 
     448      # more often the compilation of a template. 
     449      # 
     450      # === Rendering an action 
     451      #  
     452      # Action rendering is the most common form and the type used automatically by Action Controller when nothing else is 
     453      # specified. By default, actions are rendered within the current layout (if one exists). 
     454      # 
     455      #   # Renders the template for the action "goal" within the current controller 
     456      #   render :action => "goal" 
     457      # 
     458      #   # Renders the template for the action "explosion" from the ErrorsController 
     459      #   render :action => "errors/explosion", :status => 500  
     460      # 
     461      #   # Renders the template for the action "short_goal" within the current controller, 
     462      #   # but without the current active layout 
     463      #   render :action => "short_goal", :layout => false 
     464      # 
     465      #   # Renders the template for the action "long_goal" within the current controller, 
     466      #   # but with a custom layout 
     467      #   render :action => "short_goal", :layout => "spectacular" 
     468      # 
     469      # _Deprecation_ _notice_: This used to have the signatures <tt>render_action("action", status = 200)</tt>, 
     470      # <tt>render_without_layout("controller/action", status = 200)</tt>, and  
     471      # <tt>render_with_layout("controller/action", status = 200, layout)</tt>. 
     472      # 
     473      # === Rendering partials 
     474      #  
     475      # Partial rendering is most commonly used together with Ajax calls that only updates one or a few elements on a page 
     476      # without reloading. Rendering of partials from the controller makes it possible to use the same partial template in 
     477      # both the full-page rendering (by calling it from within the template) and when sub-page updates happen (from the 
     478      # controller action responding to Ajax calls). By default, the current layout is not used. 
     479      # 
     480      #   # Renders the partial located at app/views/controller/_win.r(html|xml) 
     481      #   render :partial => "win" 
     482      # 
     483      #   # Renders the partial with a status code of 500 (internal error) 
     484      #   render :partial => "broken", :status => 500 
     485      # 
     486      #   # Renders the same partial but also makes a local variable available to it 
     487      #   render :partial => "win", :locals => { :name => "david" } 
     488      # 
     489      #   # Renders a collection of the same partial by making each element of @wins available through  
     490      #   # the local variable "win" as it builds the complete response 
     491      #   render :partial => "win", :collection => @wins 
     492      # 
     493      #   # Renders the same collection of partials, but also renders the win_divider partial in between 
     494      #   # each win partial. 
     495      #   render :partial => "win", :collection => @wins, :spacer_template => "win_divider" 
     496      # 
     497      # _Deprecation_ _notice_: This used to have the signatures  
     498      # <tt>render_partial(partial_path = default_template_name, object = nil, local_assigns = {})</tt> and 
     499      # <tt>render_partial_collection(partial_name, collection, partial_spacer_template = nil, local_assigns = {})</tt>. 
     500      # 
     501      # === Rendering a file 
     502      #  
     503      # File rendering works just like action rendering except that it takes a complete path to the template intended 
     504      # for rendering and that the current layout is not applied automatically. 
     505      # 
     506      #   # Renders the template located in /path/to/some/template.r(html|xml) 
     507      #   render :file => "/path/to/some/template" 
     508      # 
     509      #   # Renders the same template within the current layout, but with a 404 status code 
     510      #   render :file => "/path/to/some/template", :layout => true, :status => 404 
     511      # 
     512      # _Deprecation_ _notice_: This used to have the signature <tt>render_file(path, status = 200)</tt> 
     513      # 
     514      # === Rendering text 
     515      #  
     516      # Rendering of text is usually used for tests or for rendering prepared content, such as a cache. By default, text 
     517      # rendering is not done within the active layout. 
     518      # 
     519      #   # Renders the clear text "hello world" with status code 200 
     520      #   render :text => "hello world!" 
     521      # 
     522      #   # Renders the clear text "Explosion!"  with status code 500 
     523      #   render :text => "Explosion!", :status => 500  
     524      # 
     525      #   # Renders the clear text "Hi there!" within the current active layout (if one exists) 
     526      #   render :text => "Explosion!", :layout => true 
     527      # 
     528      #   # Renders the clear text "Hi there!" within the the layout  
     529      #   # placed in "app/views/layouts/special.r(html|xml)" 
     530      #   render :text => "Explosion!", :layout => "special" 
     531      # 
     532      # _Deprecation_ _notice_: This used to have the signature <tt>render_text("text", status = 200)</tt> 
     533      # 
     534      # === Rendering an inline template 
     535      # 
     536      # Rendering of an inline template works as a cross between text and action rendering where the source for the template 
     537      # is supplied inline, like text, but its interpreted with ERb or Builder, like action. By default, ERb is used for rendering 
     538      # and the current layout is not used. 
     539      # 
     540      #   # Renders "hello, hello, hello, again" 
     541      #   render :inline => "<%= 'hello, ' * 3 + 'again' %>"  
     542      # 
     543      #   # Renders "<p>Good seeing you!</p>" using Builder 
     544      #   render :inline => "xml.p { 'Good seeing you!' }", :type => :rxml 
     545      # 
     546      #   # Renders "hello david" 
     547      #   render :inline => "<%= 'hello ' + name %>", :locals => { :name => "david" } 
     548      # 
     549      # _Deprecation_ _notice_: This used to have the signature <tt>render_template(template, status = 200, type = :rhtml)</tt> 
     550      # 
     551      # === Rendering nothing 
     552      # 
     553      # Rendering nothing is often convenient in combination with Ajax calls that perform their effect client-side or 
     554      # when you just want to communicate a status code. 
     555      # 
     556      #   # Renders an empty response with status code 200 
     557      #   render :nothing => true 
     558      # 
     559      #   # Renders an empty response with status code 401 (access denied) 
     560      #   render :nothing => true, :status => 401 
     561      def render(options = {}, deprecated_status = nil) #:doc: 
    459562        # puts "Rendering: #{options.inspect}" 
    460563        raise DoubleRenderError, "Can only render or redirect once per action" if performed? 
    …… 
    518621      end 
    519622 
    520       # Returns the result of the render as a string. 
     623      # Renders according to the same rules as <tt>render</tt>, but returns the result in a string instead 
     624      # of sending it as the response body to the browser. 
    521625      def render_to_string(options = {}) #:doc: 
    522626        result = render(options) 
    …… 
    525629      end 
    526630       
     631 
    527632      # Clears the rendered results, allowing for another render to be performed. 
    528633      def erase_render_results #:nodoc: 
    …… 
    543648      end 
    544649 
     650 
    545651      def rewrite_options(options) 
    546652        if defaults = default_url_options(options) 

  • trunk/actionpack/lib/action_controller/deprecated_renders_and_redirects.rb

    r1351 r1728  
    55      # <tt>render_action "show_many"</tt> in WeblogController#display will render "#{template_root}/weblog/show_many.rhtml" or  
    66      # "#{template_root}/weblog/show_many.rxml". 
    7       def render_action(action_name, status = nil) #:doc: 
     7      def render_action(action_name, status = nil) 
    88        render :action => action_name, :status => status 
    99      end 
    …… 
    1212      # used like <tt>render_file "/Users/david/Code/Ruby/template"</tt> to render "/Users/david/Code/Ruby/template.rhtml" or 
    1313      # "/Users/david/Code/Ruby/template.rxml". 
    14       def render_file(template_path, status = nil, use_full_path = false) #:doc: 
     14      def render_file(template_path, status = nil, use_full_path = false) 
    1515        render :file => template_path, :status => status, :use_full_path => use_full_path 
    1616      end 
    …… 
    1919      # you'd call <tt>render_template "Hello, <%= @user.name %>"</tt> to greet the current user. Or if you want to render as Builder 
    2020      # template, you could do <tt>render_template "xml.h1 @user.name", nil, "rxml"</tt>. 
    21       def render_template(template, status = nil, type = "rhtml") #:doc: 
     21      def render_template(template, status = nil, type = "rhtml") 
    2222        render :inline => template, :status => status, :type => type 
    2323      end 
    …… 
    2626      # considerably faster than rendering through the template engine. 
    2727      # Use block for response body if provided (useful for deferred rendering or streaming output). 
    28       def render_text(text = nil, status = nil) #:doc: 
     28      def render_text(text = nil, status = nil) 
    2929        render :text => text, :status => status 
    3030      end 
    …… 
    3232      # Renders an empty response that can be used when the request is only interested in triggering an effect. Do note that good 
    3333      # HTTP manners mandate that you don't use GET requests to trigger data changes. 
    34       def render_nothing(status = nil) #:doc: 
     34      def render_nothing(status = nil) 
    3535        render :nothing => true, :status => status 
    3636      end 
    …… 
    4343      #     end 
    4444      #   end 
    45       def render_partial(partial_path = default_template_name, object = nil, local_assigns = {}) #:doc: 
     45      def render_partial(partial_path = default_template_name, object = nil, local_assigns = {}) 
    4646        render :partial => partial_path, :object => object, :locals => local_assigns 
    4747      end 
    4848 
    4949      # Renders a collection of partials using <tt>partial_name</tt> to iterate over the +collection+. 
    50       def render_partial_collection(partial_name, collection, partial_spacer_template = nil, local_assigns = {})#:doc: 
     50      def render_partial_collection(partial_name, collection, partial_spacer_template = nil, local_assigns = {}) 
    5151        render :partial => partial_name, :collection => collection, :spacer_template => partial_spacer_template, :locals => local_assigns 
    5252      end 
    5353 
    54       def render_with_layout(template_name = default_template_name, status = nil, layout = nil) #:nodoc: 
     54      def render_with_layout(template_name = default_template_name, status = nil, layout = nil) 
    5555        render :template => template_name, :status => status, :layout => layout 
    5656      end 
    5757 
    58       def render_without_layout(template_name = default_template_name, status = nil) #:nodoc: 
     58      def render_without_layout(template_name = default_template_name, status = nil) 
    5959        render :template => template_name, :status => status, :layout => false 
    6060      end 
    …… 
    6262 
    6363      # Deprecated in favor of calling redirect_to directly with the path. 
    64       def redirect_to_path(path) #:doc: 
     64      def redirect_to_path(path) 
    6565        redirect_to(path) 
    6666      end 
    …… 
    6969      # true as the second parameter and the browser will get "301 Moved Permanently" instead of "302 Found". This can also be done through 
    7070      # just setting the headers["Status"] to "301 Moved Permanently" before using the redirect_to. 
    71       def redirect_to_url(url, permanently = false) #:doc: 
     71      def redirect_to_url(url, permanently = false) 
    7272        headers["Status"] = "301 Moved Permanently" if permanently 
    7373        redirect_to(url) 

  • trunk/actionpack/lib/action_controller/layout.rb

    r1424 r1728  
    150150    #   class WeblogController < ActionController::Base 
    151151    #     def help 
    152     #       render :file => "help/index", :layout => "layouts/help" 
     152    #       render :action => "help/index", :layout => "help" 
    153153    #     end 
    154154    #   end 

  • trunk/actionpack/README

    r1561 r1728  
    4444        @customer.save ?  
    4545          redirect_to(:action => "display") :  
    46           render("customer/edit") 
     46          render(:action => "edit") 
    4747      end 
    4848       
    …… 
    169169 
    170170 
    171 * JavaScript and Ajax integration. 
     171* Javascript and Ajax integration. 
    172172 
    173173    link_to_function "Greeting", "alert('Hello world!')" 
    …… 
    175175                   :url => { :action => "destroy", :id => post.id } 
    176176   
    177   {Learn more}[link:classes/ActionView/Helpers/JavaScriptHelper.html] 
     177  {Learn more}[link:classes/ActionView/Helpers/JavascriptHelper.html] 
    178178 
    179179 

  • trunk/actionpack/test/controller/new_render_test.rb

    r1717 r1728  
    222222  end 
    223223 
    224   def test_partials_list 
    225     get :partials_list 
    226     assert_equal "goodbyeHello: davidHello: marygoodbye\n", @response.body 
    227   end 
     224  # def test_partials_list 
     225  #   get :partials_list 
     226  #   assert_equal "goodbyeHello: davidHello: marygoodbye\n", @response.body 
     227  # end 
    228228 
    229229  def test_partial_only 

  • trunk/actionpack/test/controller/render_test.rb

    r1718 r1728  
    174174  end 
    175175 
    176   def test_partials_list 
    177     @request.action = "partials_list" 
    178     assert_equal "goodbyeHello: davidHello: marygoodbye\n", process_request.body 
    179   end 
     176  # def test_partials_list 
     177  #   @request.action = "partials_list" 
     178  #   assert_equal "goodbyeHello: davidHello: marygoodbye\n", process_request.body 
     179  # end 
    180180 
    181181  def test_partial_only