Everyone who has used Rails for a while has their own set of
“commonly used” helper methods. Many times, though, those commonly used
sets are different. Some people use FormHelper for all of their forms, while others
prefer FormTagHelper. Some people use
AssetTagHelper, while others handcode
links to static resources like stylesheets and images.
Rather than provide a comprehensive reference to these methods—the API documentation does that—this appendix provides a catalog you can browse to decide which methods might actually prove useful to your own needs. Much of the difficulty in using helpers is in finding them before you reinvent the wheel yourself.
All of these classes are subclasses of ActionView::Helpers.
Note
The easiest place to find API documentation, in a friendlier form than usual, is at http://rails-doc.org/. The search boxes give you choices as you type, and the explanations are presented in smaller pieces. You can also find the documentation at http://www.railsbrain.com/ and http://www.gotapi.com/rubyrails. They’re all a little different, but hopefully one of them will prove comfortable for you.
Every helper method has its own set of parameters, and often it’s not clear from the documentation which parameters it will accept. How do you interpret the following?
label(object_name, method, text = nil, options = {})The first few parameters at least take simple values. The object_name parameter will take a symbol
pointing to an ActiveRecord object, like :person. The method parameter, though—what method does it
take? It actually wants a symbol, say :name, for an attribute from the object specified in the
previous parameter. Why would the Rails documentation call that a
method? Because it’ll use a method to access the attribute.
The next parameter, text, is
shown with its default value, nil.
Any time you see a parameter listed as equal to something, that value is
the default.
And options? What is options? It looks like lots of methods must
have the same options, because they all have the same entry in the
documentation, but it’s really just a convention. The actual options,
named parameters, are listed below in the documentation for the method.
Sometimes the options just create HTML attributes—use the name of the
attribute to create an attribute, like :id
=> 'myIDvalue'. Other times the helper methods take more
specific options that fit their particular needs. You don’t generally
need to surround the options in {},
either.
Note
For more on a case where the curly braces ({}) are necessary, see Creating Checkboxes” in Chapter 6.
There’s also a case—with FormHelper methods in particular—where some
of the parameters disappear into a context object. See the section Form As a Wrapper” in Chapter 6 for more information
on how this works.
Sometimes you’ll also see parameters listed that begin with an
asterisk, like *sources. This means
that you can supply multiple values for that parameter.
Parameters and named parameters are enough for most helper method
calls, but every now and then you’ll see a method whose arguments end
with &block. form_for is one of the commonly used ones that
does this, but some methods take this as an option and others require
it. When you call a method with a block, however, the block doesn’t look
quite like part of the arguments:
<% benchmark "It took this long:" do %> <%= my_long_method %> <% end % >
In this case, the benchmark
method is taking two arguments. The first, a string, is “It took this
long:”; this will be text incorporated in the log. The second argument
starts with do and closes with
end, and includes everything in the
middle. That’s the block. (Blocks can also be marked with { and } in
normal Ruby code, but in the ERb where you’ll be writing helper methods,
do and end are a better choice.)
Because benchmark is keeping
track of how long it takes some code to run, it needs that code included
as an argument. The cache, capture, and content_for methods have similar needs, as do
form_for and fields_for, which surround a group of methods
and provide them context.
For developers coming from less flexible languages, Ruby’s creative use of blocks can be very difficult to figure out. If you’re feeling stuck, your best option is to work from examples until you’re ready to move forward with your own experiments.