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

Changeset 7363

Show
Ignore:
Timestamp:
08/28/07 23:16:15 (3 years ago)
Author:
nzkoz
Message:

Improve documentation for ActionController::Helpers [jardeon] Closes #9359

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

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

    r6914 r7363  
    1919    end 
    2020 
    21     # The template helpers serve to relieve the templates from including the same inline code again and again. It's a 
    22     # set of standardized methods for working with forms (FormHelper), dates (DateHelper), texts (TextHelper), and 
    23     # Active Records (ActiveRecordHelper) that's available to all templates by default. 
    24     # 
    25     # It's also really easy to make your own helpers and it's much encouraged to keep the template files free 
    26     # from complicated logic. It's even encouraged to bundle common compositions of methods from other helpers 
    27     # (often the common helpers) as they're used by the specific application. 
    28     # 
    29     #   module MyHelper 
    30     #     def hello_world() "hello world" end 
     21    # The Rails framework provides a large number of helpers for working with +assets+, +dates+, +forms+,  
     22    # +numbers+ and <tt>Active Record objects</tt>, to name a few.  These helpers are available to all templates 
     23    # by default. 
     24    # 
     25    # In addition to using the standard template helpers provided in the Rails framework, creating custom helpers to 
     26    # extract complicated logic or reusable functionality is strongly encouraged.  By default, the controller will  
     27    # include a helper whose name matches that of the controller, e.g., <tt>MyController</tt> will automatically 
     28    # include <tt>MyHelper</tt>.   
     29    #  
     30    # Additional helpers can be specified using the +helper+ class method in <tt>ActionController::Base</tt> or any 
     31    # controller which inherits from it.   
     32    # 
     33    # ==== Examples 
     34    # The +to_s+ method from the +Time+ class can be wrapped in a helper method to display a custom message if  
     35    # the Time object is blank: 
     36    # 
     37    #   module FormattedTimeHelper 
     38    #     def format_time(time, format=:long, blank_message="&nbsp;") 
     39    #       time.blank? ? blank_message : time.to_s(format) 
     40    #     end 
    3141    #   end 
    3242    # 
    33     # MyHelper can now be included in a controller, like this: 
    34     # 
    35     #   class MyController < ActionController::Base 
    36     #     helper :my_helper 
     43    # +FormattedTimeHelper+ can now be included in a controller, using the +helper+ class method: 
     44    # 
     45    #   class EventsController < ActionController::Base 
     46    #     helper FormattedTimeHelper 
     47    #     def index 
     48    #       @events = Event.find(:all) 
     49    #     end 
    3750    #   end 
    3851    # 
    39     # ...and, same as above, used in any template rendered from MyController, like this: 
    40     # 
    41     # Let's hear what the helper has to say: <tt><%= hello_world %></tt> 
     52    # Then, in any view rendered by <tt>EventController</tt>, the <tt>format_time</tt> method can be called: 
     53    # 
     54    #   <% @events.each do |event| -%> 
     55    #     <p> 
     56    #       <% format_time(event.time, :short, "N/A") %> | <%= event.name %>  
     57    #     </p> 
     58    #   <% end -%> 
     59    # 
     60    # Finally, assuming we have two event instances, one which has a time and one which does not,  
     61    # the output might look like this: 
     62    # 
     63    #   23 Aug 11:30 | Carolina Railhawks Soccer Match  
     64    #   N/A | Carolina Railhaws Training Workshop 
     65    # 
    4266    module ClassMethods 
    4367      # Makes all the (instance) methods in the helper module available to templates rendered through this controller. 
    …… 
    4872      end 
    4973 
    50       # Declare a helper: 
    51       # 
    52       #   helper :foo 
    53       # requires 'foo_helper' and includes FooHelper in the template class. 
    54       # 
    55       #   helper FooHelper 
    56       # includes FooHelper in the template class. 
    57       # 
    58       #   helper { def foo() "#{bar} is the very best" end } 
    59       # evaluates the block in the template class, adding method #foo. 
    60       # 
     74      # The +helper+ class method can take a series of helper module names, a block, or both. 
     75      # 
     76      # * <tt>*args</tt>: One or more +Modules+, +Strings+ or +Symbols+, or the special symbol <tt>:all</tt>. 
     77      # * <tt>&block</tt>: A block defining helper methods. 
     78      #  
     79      # ==== Examples 
     80      # When the argument is a +String+ or +Symbol+, the method will provide the "_helper" suffix, require the file  
     81      # and include the module in the template class.  The second form illustrates how to include custom helpers  
     82      # when working with namespaced controllers, or other cases where the file containing the helper definition is not 
     83      # in one of Rails' standard load paths: 
     84      #   helper :foo             # => requires 'foo_helper' and includes FooHelper 
     85      #   helper 'resources/foo'  # => requires 'resources/foo_helper' and includes Resources::FooHelper 
     86      # 
     87      # When the argument is a +Module+, it will be included directly in the template class. 
     88      #   helper FooHelper # => includes FooHelper 
     89      # 
     90      # When the argument is the symbol <tt>:all</tt>, the controller will includes all helpers from  
     91      # <tt>app/views/helpers/**/*.rb</tt> under RAILS_ROOT 
     92      #   helper :all 
     93      # 
     94      # Additionally, the +helper+ class method can receive and evaluate a block, making the methods defined available  
     95      # to the template. 
     96      #   # One line 
     97      #   helper { def hello() "Hello, world!" end } 
     98      #   # Multi-line 
     99      #   helper do 
     100      #     def foo(bar)  
     101      #       "#{bar} is the very best"  
     102      #     end 
     103      #   end 
     104      #  
     105      # Finally, all the above styles can be mixed together, and the helper method can be invokved with a mix of 
     106      # +symbols+, +strings+, +modules+ and blocks. 
    61107      #   helper(:three, BlindHelper) { def mice() 'mice' end } 
    62       # does all three. 
    63       # 
    64       #   helper :all 
    65       # includes all helpers from app/views/helpers/**/*.rb under RAILS_ROOT 
     108      # 
    66109      def helper(*args, &block) 
    67110        args.flatten.each do |arg| 
    …… 
    98141 
    99142      # Declare a controller method as a helper.  For example, 
    100       #   helper_method :link_to 
    101       #   def link_to(name, options) ... end 
    102       # makes the link_to controller method available in the view. 
     143      #   class ApplicationController < ActionController::Base 
     144      #     helper_method :current_user 
     145      #     def current_user 
     146      #       @current_user ||= User.find(session[:user]) 
     147      #     end 
     148      #   end 
     149      # makes the +current_user+ controller method available in the view. 
    103150      def helper_method(*methods) 
    104151        methods.flatten.each do |method|