Permalink
Browse files

Updated documentation

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@194 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
1 parent f389a8f commit 0b554201bb2deb6bbb23de9b00aebd53b134921b @dhh dhh committed Dec 16, 2004
@@ -58,7 +58,7 @@ class UnknownAction < ActionControllerError #:nodoc:
# accessing the environment hash, like this:
#
# def hello_ip
- # location = @request.env["REMOTE_ADDRESS"]
+ # location = @request.env["REMOTE_IP"]
# render_text "Hello stranger from #{location}"
# end
#
@@ -10,15 +10,19 @@ module ActionController #:nodoc:
#
# cookies["user_name"] # => "david"
# cookies.size # => 2
+ #
+ # Example for deleting:
+ #
+ # cookies.delete "user_name"
#
# All the option symbols for setting cookies are:
#
- # value:: the cookie's value or list of values (as an array).
- # path:: the path for which this cookie applies. Defaults to the root of the application.
- # domain:: the domain for which this cookie applies.
- # expires:: the time at which this cookie expires, as a +Time+ object.
- # secure:: whether this cookie is a secure cookie or not (default to false).
- # Secure cookies are only transmitted to HTTPS servers.
+ # * <tt>value</tt> - the cookie's value or list of values (as an array).
+ # * <tt>path</tt> - the path for which this cookie applies. Defaults to the root of the application.
+ # * <tt>domain</tt> - the domain for which this cookie applies.
+ # * <tt>expires</tt> - the time at which this cookie expires, as a +Time+ object.
+ # * <tt>secure</tt> - whether this cookie is a secure cookie or not (default to false).
+ # Secure cookies are only transmitted to HTTPS servers.
module Cookies
# Returns the cookie container, which operates as described above.
def cookies
@@ -20,33 +20,60 @@ def self.append_features(base)
base.extend(ClassMethods)
end
+ # Dependencies control what classes are needed for the controller to run its course. This is an alternative to doing explicit
+ # +require+ statements that bring a number of benefits. It's more succinct, communicates what type of dependency we're talking about,
+ # can trigger special behavior (as in the case of +observer+), and enables Rails to be clever about reloading in cached environments
+ # like FCGI. Example:
+ #
+ # class ApplicationController < ActionController::Base
+ # model :account, :company, :person, :project, :category
+ # helper :access_control
+ # service :notifications, :billings
+ # observer :project_change_observer
+ # end
+ #
+ # Please note that a controller like ApplicationController will automatically attempt to require_dependency on a model of its name and a helper
+ # of its name. If nothing is found, no error is raised. This is especially useful for concrete controllers like PostController:
+ #
+ # class PostController < ApplicationController
+ # # model :post (already required)
+ # # helper :post (already required)
+ # end
module ClassMethods
# Loads the <tt>file_name</tt> if reload_dependencies is true or requires if it's false.
def require_dependency(file_name)
reload_dependencies ? silence_warnings { load("#{file_name}.rb") } : require(file_name)
end
+ # Specifies a variable number of models that this controller depends on. Models are normally Active Record classes or a similar
+ # backend for modelling entity classes.
def model(*models)
require_dependencies(:model, models)
depend_on(:model, models)
end
+ # Specifies a variable number of services that this controller depends on. Services are normally singletons or factories, like
+ # Action Mailer service or a Payment Gateway service.
def service(*services)
require_dependencies(:service, services)
depend_on(:service, services)
end
+ # Specifies a variable number of observers that are to govern when this controller is handling actions. The observers will
+ # automatically have .instance called on them to make them active on assignment.
def observer(*observers)
require_dependencies(:observer, observers)
depend_on(:observer, observers)
instantiate_observers(observers)
end
- def dependencies_on(layer) # :nodoc:
+ # Returns an array of symbols that specify the dependencies on a given layer. For the example at the top, calling
+ # <tt>ApplicationController.dependencies_on(:model)</tt> would return <tt>[:account, :company, :person, :project, :category]</tt>
+ def dependencies_on(layer)
read_inheritable_attribute("#{layer}_dependencies")
end
- def depend_on(layer, dependencies)
+ def depend_on(layer, dependencies) #:nodoc:
write_inheritable_array("#{layer}_dependencies", dependencies)
end
@@ -31,7 +31,7 @@ module ClassMethods
# Makes all the (instance) methods in the helper module available to templates rendered through this controller.
# See ActionView::Helpers (link:classes/ActionView/Helpers.html) for more about making your own helper modules
# available to the templates.
- def add_template_helper(helper_module)
+ def add_template_helper(helper_module) #:nodoc:
template_class.class_eval "include #{helper_module}"
end
@@ -15,7 +15,7 @@ def self.append_features(base) #:nodoc:
end
end
- module ClassMethods
+ module ClassMethods #:nodoc:
def process_with_exception(request, response, exception)
new.process(request, response, :rescue_action, exception)
end
@@ -187,25 +187,28 @@ def delete() @attributes = {} end
end
end
-class Test::Unit::TestCase #:nodoc:
- private
- # execute the request and set/volley the response
- def process(action, parameters = nil, session = nil)
- @request.env['REQUEST_METHOD'] ||= "GET"
- @request.action = action.to_s
- @request.parameters.update(parameters) unless parameters.nil?
- @request.session = ActionController::TestSession.new(session) unless session.nil?
- @controller.process(@request, @response)
- end
+module Test
+ module Unit
+ class TestCase #:nodoc:
+ private
+ # execute the request and set/volley the response
+ def process(action, parameters = nil, session = nil)
+ @request.env['REQUEST_METHOD'] ||= "GET"
+ @request.action = action.to_s
+ @request.parameters.update(parameters) unless parameters.nil?
+ @request.session = ActionController::TestSession.new(session) unless session.nil?
+ @controller.process(@request, @response)
+ end
- # execute the request simulating a specific http method and set/volley the response
- %w( get post put delete head ).each do |method|
- class_eval <<-EOV
- def #{method}(action, parameters = nil, session = nil)
- @request.env['REQUEST_METHOD'] = "#{method.upcase}"
- process(action, parameters, session)
+ # execute the request simulating a specific http method and set/volley the response
+ %w( get post put delete head ).each do |method|
+ class_eval <<-EOV
+ def #{method}(action, parameters = nil, session = nil)
+ @request.env['REQUEST_METHOD'] = "#{method.upcase}"
+ process(action, parameters, session)
+ end
+ EOV
end
- EOV
end
-
+ end
end
@@ -28,15 +28,6 @@
# RubyGems is not available, use included Builder
$:.unshift(File.dirname(__FILE__) + "/action_view/vendor")
require 'action_view/vendor/builder'
-ensure
- # Temporary patch until it's in Builder 1.2.2
- class BlankSlate
- class << self
- def hide(name)
- undef_method name if instance_methods.include?(name) and name !~ /^(__|instance_eval)/
- end
- end
- end
end
require 'action_view/base'
@@ -141,7 +141,7 @@ def self.load_helpers(helper_dir)#:nodoc:
end
end
- def self.controller_delegate(*methods)
+ def self.controller_delegate(*methods)#:nodoc:
methods.flatten.each do |method|
class_eval <<-end_eval
def #{method}(*args, &block)
@@ -83,9 +83,9 @@ def error_message_on(object, method, prepend_text = "", append_text = "", css_cl
# Returns a string with a div containing all the error messages for the object located as an instance variable by the name
# of <tt>object_name</tt>. This div can be tailored by the following options:
#
- # ::header_tag: Used for the header of the error div (default: h2)
- # ::id: The id of the error div (default: errorExplanation)
- # ::class: The class of the error div (default: errorExplanation)
+ # * <tt>header_tag</tt> - Used for the header of the error div (default: h2)
+ # * <tt>id</tt> - The id of the error div (default: errorExplanation)
+ # * <tt>class</tt> - The class of the error div (default: errorExplanation)
def error_messages_for(object_name, options={})
object = instance_eval "@#{object_name}"
unless object.errors.empty?
@@ -91,11 +91,13 @@ def text_area(object, method, options = {})
#
# Example (call, result). Imagine that @post.validated? returns 1:
# check_box("post", "validated")
- # <input type="checkbox" id="post_validate" name="post[validated] value="1" checked="checked" /><input name="post[validated]" type="hidden" value="0" />
+ # <input type="checkbox" id="post_validate" name="post[validated] value="1" checked="checked" />
+ # <input name="post[validated]" type="hidden" value="0" />
#
# Example (call, result). Imagine that @puppy.gooddog returns no:
# check_box("puppy", "gooddog", {}, "yes", "no")
- # <input type="checkbox" id="puppy_gooddog" name="puppy[gooddog] value="yes" /><input name="puppy[gooddog]" type="hidden" value="no" />
+ # <input type="checkbox" id="puppy_gooddog" name="puppy[gooddog] value="yes" />
+ # <input name="puppy[gooddog]" type="hidden" value="no" />
def check_box(object, method, options = {}, checked_value = "1", unchecked_value = "0")
InstanceTag.new(object, method, self).to_check_box_tag(options, checked_value, unchecked_value)
end
@@ -7,16 +7,16 @@ module TagHelper
include ERB::Util
# Examples:
- # * tag("br") => <br />
- # * tag("input", { "type" => "text"}) => <input type="text" />
+ # * <tt>tag("br") => <br /></tt>
+ # * <tt>tag("input", { "type" => "text"}) => <input type="text" /></tt>
def tag(name, options = {}, open = false)
"<#{name}#{tag_options(options)}" + (open ? ">" : " />")
end
# Examples:
- # * content_tag("p", "Hello world!") => <p>Hello world!</p>
- # * content_tag("div", content_tag("p", "Hello world!"), "class" => "strong") =>
- # <div class="strong"><p>Hello world!</p></div>
+ # * <tt>content_tag("p", "Hello world!") => <p>Hello world!</p></tt>
+ # * <tt>content_tag("div", content_tag("p", "Hello world!"), "class" => "strong") => </tt>
+ # <tt><div class="strong"><p>Hello world!</p></div></tt>
def content_tag(name, content, options = {})
"<#{name}#{tag_options(options)}>#{content}</#{name}>"
end
@@ -30,10 +30,10 @@ def link_to(name, options = {}, html_options = {}, *parameters_for_method_refere
# get a link tag that just points without consideration. The <tt>html_options</tt> works jointly for the image and ahref tag by
# letting the following special values enter the options on the image and the rest goes to the ahref:
#
- # ::alt: If no alt text is given, the file name part of the +src+ is used (capitalized and without the extension)
- # ::size: Supplied as "XxY", so "30x45" becomes width="30" and height="45"
- # ::border: Is set to 0 by default
- # ::align: Sets the alignment, no special features
+ # * <tt>alt</tt> - If no alt text is given, the file name part of the +src+ is used (capitalized and without the extension)
+ # * <tt>size</tt> - Supplied as "XxY", so "30x45" becomes width="30" and height="45"
+ # * <tt>border</tt> - Is set to 0 by default
+ # * <tt>align</tt> - Sets the alignment, no special features
#
# The +src+ can be supplied as a...
# * full path, like "/my_images/image.gif"

0 comments on commit 0b55420

Please sign in to comment.