From 93ec99c2462135cfddeed07f7c212787eebd4b15 Mon Sep 17 00:00:00 2001 From: David Heinemeier Hansson Date: Wed, 6 Jul 2005 08:27:11 +0000 Subject: Partly tuned docs for release (AP) git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@1728 5ecf4fe2-1ee6-0310-87b1-e25e094e27de --- actionpack/lib/action_controller/auto_complete.rb | 46 +++--- actionpack/lib/action_controller/base.rb | 168 +++++++++++++++++---- .../deprecated_renders_and_redirects.rb | 22 +-- actionpack/lib/action_controller/layout.rb | 2 +- 4 files changed, 174 insertions(+), 64 deletions(-) (limited to 'actionpack/lib') diff --git a/actionpack/lib/action_controller/auto_complete.rb b/actionpack/lib/action_controller/auto_complete.rb index ef2a57bdf0..3f6694fc88 100644 --- a/actionpack/lib/action_controller/auto_complete.rb +++ b/actionpack/lib/action_controller/auto_complete.rb @@ -1,30 +1,34 @@ module ActionController - # Example: - # - # # Controller - # class BlogController < ApplicationController - # auto_complete_for :post, :title - # end - # - # # View - # <%= text_field_with_auto_complete :post, title %> - # - # By default, auto_complete_for limits the results to 10 entries, - # and sorts by the given field. - # - # auto_complete_for takes a third parameter, an options hash to - # the find method used to search for the records: - # - # auto_complete_for :post, :title, :limit => 15, :order => 'created_at DESC' - # - # For help on defining text input fields with autocompletion, - # see ActionView::Helpers::JavascriptHelper. - module AutoComplete + module AutoComplete #:nodoc: def self.append_features(base) #:nodoc: super base.extend(ClassMethods) end + # Example: + # + # # Controller + # class BlogController < ApplicationController + # auto_complete_for :post, :title + # end + # + # # View + # <%= text_field_with_auto_complete :post, title %> + # + # By default, auto_complete_for limits the results to 10 entries, + # and sorts by the given field. + # + # auto_complete_for takes a third parameter, an options hash to + # the find method used to search for the records: + # + # auto_complete_for :post, :title, :limit => 15, :order => 'created_at DESC' + # + # For help on defining text input fields with autocompletion, + # see ActionView::Helpers::JavascriptHelper. + # + # For more examples, see script.aculo.us: + # * http://script.aculo.us/demos/ajax/autocompleter + # * http://script.aculo.us/demos/ajax/autocompleter_customized module ClassMethods def auto_complete_for(object, method, options = {}) define_method("auto_complete_for_#{object}_#{method}") do diff --git a/actionpack/lib/action_controller/base.rb b/actionpack/lib/action_controller/base.rb index ae988c4488..05083360aa 100755 --- a/actionpack/lib/action_controller/base.rb +++ b/actionpack/lib/action_controller/base.rb @@ -60,6 +60,9 @@ module ActionController #:nodoc: # Also note that it's the final call to process_cgi that actually initiates the action performance. It will extract # request and response objects from the CGI # + # When Action Pack is used inside of Rails, the template_root is automatically configured and you don't need to call process_cgi + # yourself. + # # == Requests # # Requests are processed by the Action Controller framework by extracting the value of the "action" key in the request parameters. @@ -67,19 +70,19 @@ module ActionController #:nodoc: # request parameters, the session (if one is available), and the full request with all the http headers are made available to # the action through instance variables. Then the action is performed. # - # The full request object is available in @request and is primarily used to query for http headers. These queries are made by - # accessing the environment hash, like this: + # The full request object is available with the request accessor and is primarily used to query for http headers. These queries + # are made by accessing the environment hash, like this: # # def hello_ip - # location = @request.env["REMOTE_IP"] + # location = request.env["REMOTE_IP"] # render_text "Hello stranger from #{location}" # end # # == Parameters # - # All request parameters whether they come from a GET or POST request, or from the URL, are available through the @params hash. + # All request parameters whether they come from a GET or POST request, or from the URL, are available through the params hash. # So an action that was performed through /weblog/list?category=All&limit=5 will include { "category" => "All", "limit" => 5 } - # in @params. + # in params. # # It's also possible to construct multi-dimensional parameter hashes by specifying keys using brackets, such as: # @@ -87,7 +90,7 @@ module ActionController #:nodoc: # # # A request stemming from a form holding these inputs will include { "post" => { "name" => "david", "address" => "hyacintvej" } }. - # If the address input had been named "post[address][street]", the @params would have included + # If the address input had been named "post[address][street]", the params would have included # { "post" => { "address" => { "street" => "hyacintvej" } } }. There's no limit to the depth of the nesting. # # == Sessions @@ -97,24 +100,17 @@ module ActionController #:nodoc: # as a User object for a system that requires login. The session should not be used, however, as a cache for objects where it's likely # they could be changed unknowingly. It's usually too much work to keep it all synchronized -- something databases already excel at. # - # You can place objects in the session by using the @session hash: + # You can place objects in the session by using the session hash accessor: # - # @session[:person] = Person.authenticate(user_name, password) + # session[:person] = Person.authenticate(user_name, password) # # And retrieved again through the same hash: # - # Hello #{@session[:person]} + # Hello #{session[:person]} # # Any object can be placed in the session (as long as it can be Marshalled). But remember that 1000 active sessions each storing a # 50kb object could lead to a 50MB memory overhead. In other words, think carefully about size and caching before resorting to the use # of the session. - # - # If you store a model in the session, you must also include a line like: - # - # model :person - # - # For that particular controller. In Rails, you can also just add it in your app/controller/application.rb file (so the model is available - # for all controllers). This lets Action Pack know to have the model definition loaded before retrieving the object from the session. # # For removing objects from the session, you can either assign a single key to nil, like @session[:person] = nil, or you can # remove the entire session with reset_session. @@ -131,7 +127,7 @@ module ActionController #:nodoc: # The controller passes objects to the view by assigning instance variables: # # def show - # @post = Post.find(@params["id"]) + # @post = Post.find(params[:id]) # end # # Which are then automatically available to the view: @@ -142,11 +138,11 @@ module ActionController #:nodoc: # the manual rendering methods: # # def search - # @results = Search.find(@params["query"]) + # @results = Search.find(params[:query]) # case @results - # when 0 then render "weblog/no_results" - # when 1 then render_action "show" - # when 2..10 then render_action "show_many" + # when 0 then render :action=> "no_results" + # when 1 then render :action=> "show" + # when 2..10 then render :action=> "show_many" # end # end # @@ -187,7 +183,7 @@ module ActionController #:nodoc: # # def do_something # redirect_to :action => "elsewhere" - # render_action "overthere" + # render :action => "overthere" # end # # Only the redirect happens. The rendering call is simply ignored. @@ -448,14 +444,121 @@ module ActionController #:nodoc: end protected - # Renders the template specified by template_name, which defaults to the name of the current controller and action. - # So calling +render+ in WeblogController#show will attempt to render "#{template_root}/weblog/show.rhtml" or - # "#{template_root}/weblog/show.rxml" (in that order). The template_root is set on the ActionController::Base class and is - # shared by all controllers. It's also possible to pass a status code using the second parameter. This defaults to "200 OK", - # but can be changed, such as by calling render("weblog/error", "500 Error"). - - # A unified replacement for the individual renders (work-in-progress). - def render(options = {}, deprecated_status = nil) + # Renders the content that'll be returned to the browser as the response body. This can just be as regular text, but is + # more often the compilation of a template. + # + # === Rendering an action + # + # Action rendering is the most common form and the type used automatically by Action Controller when nothing else is + # specified. By default, actions are rendered within the current layout (if one exists). + # + # # Renders the template for the action "goal" within the current controller + # render :action => "goal" + # + # # Renders the template for the action "explosion" from the ErrorsController + # render :action => "errors/explosion", :status => 500 + # + # # Renders the template for the action "short_goal" within the current controller, + # # but without the current active layout + # render :action => "short_goal", :layout => false + # + # # Renders the template for the action "long_goal" within the current controller, + # # but with a custom layout + # render :action => "short_goal", :layout => "spectacular" + # + # _Deprecation_ _notice_: This used to have the signatures render_action("action", status = 200), + # render_without_layout("controller/action", status = 200), and + # render_with_layout("controller/action", status = 200, layout). + # + # === Rendering partials + # + # Partial rendering is most commonly used together with Ajax calls that only updates one or a few elements on a page + # without reloading. Rendering of partials from the controller makes it possible to use the same partial template in + # both the full-page rendering (by calling it from within the template) and when sub-page updates happen (from the + # controller action responding to Ajax calls). By default, the current layout is not used. + # + # # Renders the partial located at app/views/controller/_win.r(html|xml) + # render :partial => "win" + # + # # Renders the partial with a status code of 500 (internal error) + # render :partial => "broken", :status => 500 + # + # # Renders the same partial but also makes a local variable available to it + # render :partial => "win", :locals => { :name => "david" } + # + # # Renders a collection of the same partial by making each element of @wins available through + # # the local variable "win" as it builds the complete response + # render :partial => "win", :collection => @wins + # + # # Renders the same collection of partials, but also renders the win_divider partial in between + # # each win partial. + # render :partial => "win", :collection => @wins, :spacer_template => "win_divider" + # + # _Deprecation_ _notice_: This used to have the signatures + # render_partial(partial_path = default_template_name, object = nil, local_assigns = {}) and + # render_partial_collection(partial_name, collection, partial_spacer_template = nil, local_assigns = {}). + # + # === Rendering a file + # + # File rendering works just like action rendering except that it takes a complete path to the template intended + # for rendering and that the current layout is not applied automatically. + # + # # Renders the template located in /path/to/some/template.r(html|xml) + # render :file => "/path/to/some/template" + # + # # Renders the same template within the current layout, but with a 404 status code + # render :file => "/path/to/some/template", :layout => true, :status => 404 + # + # _Deprecation_ _notice_: This used to have the signature render_file(path, status = 200) + # + # === Rendering text + # + # Rendering of text is usually used for tests or for rendering prepared content, such as a cache. By default, text + # rendering is not done within the active layout. + # + # # Renders the clear text "hello world" with status code 200 + # render :text => "hello world!" + # + # # Renders the clear text "Explosion!" with status code 500 + # render :text => "Explosion!", :status => 500 + # + # # Renders the clear text "Hi there!" within the current active layout (if one exists) + # render :text => "Explosion!", :layout => true + # + # # Renders the clear text "Hi there!" within the the layout + # # placed in "app/views/layouts/special.r(html|xml)" + # render :text => "Explosion!", :layout => "special" + # + # _Deprecation_ _notice_: This used to have the signature render_text("text", status = 200) + # + # === Rendering an inline template + # + # Rendering of an inline template works as a cross between text and action rendering where the source for the template + # is supplied inline, like text, but its interpreted with ERb or Builder, like action. By default, ERb is used for rendering + # and the current layout is not used. + # + # # Renders "hello, hello, hello, again" + # render :inline => "<%= 'hello, ' * 3 + 'again' %>" + # + # # Renders "

Good seeing you!

" using Builder + # render :inline => "xml.p { 'Good seeing you!' }", :type => :rxml + # + # # Renders "hello david" + # render :inline => "<%= 'hello ' + name %>", :locals => { :name => "david" } + # + # _Deprecation_ _notice_: This used to have the signature render_template(template, status = 200, type = :rhtml) + # + # === Rendering nothing + # + # Rendering nothing is often convenient in combination with Ajax calls that perform their effect client-side or + # when you just want to communicate a status code. + # + # # Renders an empty response with status code 200 + # render :nothing => true + # + # # Renders an empty response with status code 401 (access denied) + # render :nothing => true, :status => 401 + def render(options = {}, deprecated_status = nil) #:doc: # puts "Rendering: #{options.inspect}" raise DoubleRenderError, "Can only render or redirect once per action" if performed? @@ -517,13 +620,15 @@ module ActionController #:nodoc: end end - # Returns the result of the render as a string. + # Renders according to the same rules as render, but returns the result in a string instead + # of sending it as the response body to the browser. def render_to_string(options = {}) #:doc: result = render(options) erase_render_results return result end + # Clears the rendered results, allowing for another render to be performed. def erase_render_results #:nodoc: @response.body = nil @@ -542,6 +647,7 @@ module ActionController #:nodoc: response.headers.delete('location') end + def rewrite_options(options) if defaults = default_url_options(options) defaults.merge(options) diff --git a/actionpack/lib/action_controller/deprecated_renders_and_redirects.rb b/actionpack/lib/action_controller/deprecated_renders_and_redirects.rb index c38d489a4e..44715d9cae 100644 --- a/actionpack/lib/action_controller/deprecated_renders_and_redirects.rb +++ b/actionpack/lib/action_controller/deprecated_renders_and_redirects.rb @@ -4,34 +4,34 @@ module ActionController # Works like render, but instead of requiring a full template name, you can get by with specifying the action name. So calling # render_action "show_many" in WeblogController#display will render "#{template_root}/weblog/show_many.rhtml" or # "#{template_root}/weblog/show_many.rxml". - def render_action(action_name, status = nil) #:doc: + def render_action(action_name, status = nil) render :action => action_name, :status => status end # Works like render, but disregards the template_root and requires a full path to the template that needs to be rendered. Can be # used like render_file "/Users/david/Code/Ruby/template" to render "/Users/david/Code/Ruby/template.rhtml" or # "/Users/david/Code/Ruby/template.rxml". - def render_file(template_path, status = nil, use_full_path = false) #:doc: + def render_file(template_path, status = nil, use_full_path = false) render :file => template_path, :status => status, :use_full_path => use_full_path end # Renders the +template+ string, which is useful for rendering short templates you don't want to bother having a file for. So # you'd call render_template "Hello, <%= @user.name %>" to greet the current user. Or if you want to render as Builder # template, you could do render_template "xml.h1 @user.name", nil, "rxml". - def render_template(template, status = nil, type = "rhtml") #:doc: + def render_template(template, status = nil, type = "rhtml") render :inline => template, :status => status, :type => type end # Renders the +text+ string without parsing it through any template engine. Useful for rendering static information as it's # considerably faster than rendering through the template engine. # Use block for response body if provided (useful for deferred rendering or streaming output). - def render_text(text = nil, status = nil) #:doc: + def render_text(text = nil, status = nil) render :text => text, :status => status end # Renders an empty response that can be used when the request is only interested in triggering an effect. Do note that good # HTTP manners mandate that you don't use GET requests to trigger data changes. - def render_nothing(status = nil) #:doc: + def render_nothing(status = nil) render :nothing => true, :status => status end @@ -42,33 +42,33 @@ module ActionController # render_partial # renders "weblog/_show.r(xml|html)" # end # end - def render_partial(partial_path = default_template_name, object = nil, local_assigns = {}) #:doc: + def render_partial(partial_path = default_template_name, object = nil, local_assigns = {}) render :partial => partial_path, :object => object, :locals => local_assigns end # Renders a collection of partials using partial_name to iterate over the +collection+. - def render_partial_collection(partial_name, collection, partial_spacer_template = nil, local_assigns = {})#:doc: + def render_partial_collection(partial_name, collection, partial_spacer_template = nil, local_assigns = {}) render :partial => partial_name, :collection => collection, :spacer_template => partial_spacer_template, :locals => local_assigns end - def render_with_layout(template_name = default_template_name, status = nil, layout = nil) #:nodoc: + def render_with_layout(template_name = default_template_name, status = nil, layout = nil) render :template => template_name, :status => status, :layout => layout end - def render_without_layout(template_name = default_template_name, status = nil) #:nodoc: + def render_without_layout(template_name = default_template_name, status = nil) render :template => template_name, :status => status, :layout => false end # Deprecated in favor of calling redirect_to directly with the path. - def redirect_to_path(path) #:doc: + def redirect_to_path(path) redirect_to(path) end # Deprecated in favor of calling redirect_to directly with the url. If the resource has moved permanently, it's possible to pass # true as the second parameter and the browser will get "301 Moved Permanently" instead of "302 Found". This can also be done through # just setting the headers["Status"] to "301 Moved Permanently" before using the redirect_to. - def redirect_to_url(url, permanently = false) #:doc: + def redirect_to_url(url, permanently = false) headers["Status"] = "301 Moved Permanently" if permanently redirect_to(url) end diff --git a/actionpack/lib/action_controller/layout.rb b/actionpack/lib/action_controller/layout.rb index 0494ebc456..07c02f0de3 100644 --- a/actionpack/lib/action_controller/layout.rb +++ b/actionpack/lib/action_controller/layout.rb @@ -149,7 +149,7 @@ module ActionController #:nodoc: # # class WeblogController < ActionController::Base # def help - # render :file => "help/index", :layout => "layouts/help" + # render :action => "help/index", :layout => "help" # end # end # -- cgit v1.2.3