The Rails framework provides a large number of helpers for working with assets, dates, forms, numbers and Active Record objects, to name a few. These helpers are available to all templates by default.
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., MyController will automatically include MyHelper.
Additional helpers can be specified using the helper class method in ActionController::Base or any controller which inherits from it.
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
FormattedTimeHelper can now be included in a controller, using the helper class method:
class EventsController < ActionController::Base helper FormattedTimeHelper def index @events = Event.find(:all) end end
Then, in any view rendered by EventController, the format_time 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
The helper class method can take a series of helper module names, a block, or both.
- *args: One or more modules, strings or symbols, or the special symbol :all.
- &block: 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
When the argument is a module it will be included directly in the template class.
helper FooHelper # => includes FooHelper
When the argument is the symbol :all, the controller will include all helpers beneath ActionController::Base.helpers_dir (defaults to app/helpers/**/*.rb 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 invoked with a mix of symbols, strings, modules and blocks.
helper(:three, BlindHelper) { def mice() 'mice' end }
[ show source ]
# File actionpack/lib/action_controller/helpers.rb, line 114 114: def helper(*args, &block) 115: args.flatten.each do |arg| 116: case arg 117: when Module 118: add_template_helper(arg) 119: when :all 120: helper(all_application_helpers) 121: when String, Symbol 122: file_name = arg.to_s.underscore + '_helper' 123: class_name = file_name.camelize 124: 125: begin 126: require_dependency(file_name) 127: rescue LoadError => load_error 128: requiree = / -- (.*?)(\.rb)?$/.match(load_error.message).to_a[1] 129: if requiree == file_name 130: msg = "Missing helper file helpers/#{file_name}.rb" 131: raise LoadError.new(msg).copy_blame!(load_error) 132: else 133: raise 134: end 135: end 136: 137: add_template_helper(class_name.constantize) 138: else 139: raise ArgumentError, "helper expects String, Symbol, or Module argument (was: #{args.inspect})" 140: end 141: end 142: 143: # Evaluate block in template class if given. 144: master_helper_module.module_eval(&block) if block_given? 145: end
Declares helper accessors for controller attributes. For example, the following adds new name and name= instance methods to a controller and makes them available to the view:
helper_attr :name attr_accessor :name
[ show source ]
# File actionpack/lib/action_controller/helpers.rb, line 179 179: def helper_attr(*attrs) 180: attrs.flatten.each { |attr| helper_method(attr, "#{attr}=") } 181: end
Declare a controller method as a helper. For example, the following makes the current_user controller method available to the view:
class ApplicationController < ActionController::Base helper_method :current_user, :logged_in? def current_user @current_user ||= User.find_by_id(session[:user]) end def logged_in? current_user != nil end end
In a view:
<% if logged_in? -%>Welcome, <%= current_user.name %><% end -%>
[ show source ]
# File actionpack/lib/action_controller/helpers.rb, line 163 163: def helper_method(*methods) 164: methods.flatten.each do |method| 165: master_helper_module.module_eval "def \#{method}(*args, &block) # def current_user(*args, &block)\ncontroller.send(%(\#{method}), *args, &block) # controller.send(%(current_user), *args, &block)\nend # end\n" 166: end 167: end
Provides a proxy to access helpers methods from outside the view.
[ show source ]
# File actionpack/lib/action_controller/helpers.rb, line 184 184: def helpers 185: unless @helper_proxy 186: @helper_proxy = ActionView::Base.new 187: @helper_proxy.extend master_helper_module 188: else 189: @helper_proxy 190: end 191: end