diff options
author | Michael Koziarski <michael@koziarski.com> | 2007-08-28 23:16:15 +0000 |
---|---|---|
committer | Michael Koziarski <michael@koziarski.com> | 2007-08-28 23:16:15 +0000 |
commit | 43ef688d7405628972d72d4aa127b9d016feacaa (patch) | |
tree | a2f2b5292f84c84da4c9a67764c31fc663ae5952 /actionpack/lib/action_controller/helpers.rb | |
parent | 5cbc782ecef16f256f543fa444dc1380925cefc0 (diff) | |
download | rails-43ef688d7405628972d72d4aa127b9d016feacaa.tar.gz rails-43ef688d7405628972d72d4aa127b9d016feacaa.tar.bz2 rails-43ef688d7405628972d72d4aa127b9d016feacaa.zip |
Improve documentation for ActionController::Helpers [jardeon] Closes #9359
git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@7363 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
Diffstat (limited to 'actionpack/lib/action_controller/helpers.rb')
-rw-r--r-- | actionpack/lib/action_controller/helpers.rb | 99 |
1 files changed, 73 insertions, 26 deletions
diff --git a/actionpack/lib/action_controller/helpers.rb b/actionpack/lib/action_controller/helpers.rb index 3867329e29..66a88fc07f 100644 --- a/actionpack/lib/action_controller/helpers.rb +++ b/actionpack/lib/action_controller/helpers.rb @@ -18,27 +18,51 @@ module ActionController #:nodoc: end end - # The template helpers serve to relieve the templates from including the same inline code again and again. It's a - # set of standardized methods for working with forms (FormHelper), dates (DateHelper), texts (TextHelper), and - # Active Records (ActiveRecordHelper) that's available to all templates by default. + # The Rails framework provides a large number of helpers for working with +assets+, +dates+, +forms+, + # +numbers+ and <tt>Active Record objects</tt>, to name a few. These helpers are available to all templates + # by default. # - # It's also really easy to make your own helpers and it's much encouraged to keep the template files free - # from complicated logic. It's even encouraged to bundle common compositions of methods from other helpers - # (often the common helpers) as they're used by the specific application. + # In addition to using the standard template helpers provided in the Rails framework, creating custom helpers to + # extract complicated logic or reusable functionality is strongly encouraged. By default, the controller will + # include a helper whose name matches that of the controller, e.g., <tt>MyController</tt> will automatically + # include <tt>MyHelper</tt>. + # + # Additional helpers can be specified using the +helper+ class method in <tt>ActionController::Base</tt> or any + # controller which inherits from it. # - # module MyHelper - # def hello_world() "hello world" end + # ==== Examples + # The +to_s+ method from the +Time+ class can be wrapped in a helper method to display a custom message if + # the Time object is blank: + # + # module FormattedTimeHelper + # def format_time(time, format=:long, blank_message=" ") + # time.blank? ? blank_message : time.to_s(format) + # end # end # - # MyHelper can now be included in a controller, like this: + # +FormattedTimeHelper+ can now be included in a controller, using the +helper+ class method: # - # class MyController < ActionController::Base - # helper :my_helper + # class EventsController < ActionController::Base + # helper FormattedTimeHelper + # def index + # @events = Event.find(:all) + # end # end # - # ...and, same as above, used in any template rendered from MyController, like this: + # Then, in any view rendered by <tt>EventController</tt>, the <tt>format_time</tt> method can be called: + # + # <% @events.each do |event| -%> + # <p> + # <% format_time(event.time, :short, "N/A") %> | <%= event.name %> + # </p> + # <% end -%> + # + # Finally, assuming we have two event instances, one which has a time and one which does not, + # the output might look like this: + # + # 23 Aug 11:30 | Carolina Railhawks Soccer Match + # N/A | Carolina Railhaws Training Workshop # - # Let's hear what the helper has to say: <tt><%= hello_world %></tt> 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 @@ -47,22 +71,41 @@ module ActionController #:nodoc: master_helper_module.send(:include, helper_module) end - # Declare a helper: + # The +helper+ class method can take a series of helper module names, a block, or both. # - # helper :foo - # requires 'foo_helper' and includes FooHelper in the template class. + # * <tt>*args</tt>: One or more +Modules+, +Strings+ or +Symbols+, or the special symbol <tt>:all</tt>. + # * <tt>&block</tt>: A block defining helper methods. + # + # ==== Examples + # When the argument is a +String+ or +Symbol+, the method will provide the "_helper" suffix, require the file + # and include the module in the template class. The second form illustrates how to include custom helpers + # when working with namespaced controllers, or other cases where the file containing the helper definition is not + # in one of Rails' standard load paths: + # helper :foo # => requires 'foo_helper' and includes FooHelper + # helper 'resources/foo' # => requires 'resources/foo_helper' and includes Resources::FooHelper # - # helper FooHelper - # includes FooHelper in the template class. + # When the argument is a +Module+, it will be included directly in the template class. + # helper FooHelper # => includes FooHelper # - # helper { def foo() "#{bar} is the very best" end } - # evaluates the block in the template class, adding method #foo. + # When the argument is the symbol <tt>:all</tt>, the controller will includes all helpers from + # <tt>app/views/helpers/**/*.rb</tt> under RAILS_ROOT + # helper :all # + # Additionally, the +helper+ class method can receive and evaluate a block, making the methods defined available + # to the template. + # # One line + # helper { def hello() "Hello, world!" end } + # # Multi-line + # helper do + # def foo(bar) + # "#{bar} is the very best" + # end + # end + # + # Finally, all the above styles can be mixed together, and the helper method can be invokved with a mix of + # +symbols+, +strings+, +modules+ and blocks. # helper(:three, BlindHelper) { def mice() 'mice' end } - # does all three. # - # helper :all - # includes all helpers from app/views/helpers/**/*.rb under RAILS_ROOT def helper(*args, &block) args.flatten.each do |arg| case arg @@ -97,9 +140,13 @@ module ActionController #:nodoc: end # Declare a controller method as a helper. For example, - # helper_method :link_to - # def link_to(name, options) ... end - # makes the link_to controller method available in the view. + # class ApplicationController < ActionController::Base + # helper_method :current_user + # def current_user + # @current_user ||= User.find(session[:user]) + # end + # end + # makes the +current_user+ controller method available in the view. def helper_method(*methods) methods.flatten.each do |method| master_helper_module.module_eval <<-end_eval |