A Catalog of Helper Methods: Appendix D - Learning Rails

Returns a div containing the error message for a given object and method. You can add text before or after the message.

Returns a div containing all the error messages for a given object. (The documentation suggests that you look at the code and make your own method if you need something more specific.)

Creates a POST-based form based on the ActiveRecord object, all in one call. You can add extra pieces to the form through a block, but mostly this is good for quick-and-dirty instant forms.

Creates an input element based on the type of the object and method it’s passed. It’s kind of like a field-by-field version of form.

Lets you specify the location of an RSS or Atom feed.

Returns an HTML img tag for the specified image name.

Returns a script tag for the JavaScript files you identify as parameters. If one of the parameters is :defaults, the application.js file will be included, bringing in the Prototype and Script.aculo.us libraries. You can provide full paths to your scripts, even scripts on other servers, or you can just provide the file’s name. If you’re feeling fancy, you can define groups of styles with register_javascript_expansion, and reference them with symbols.

Returns a link tag for the CSS stylesheet files you identify as parameters. You can provide full paths to your stylesheets, even stylesheets on other servers, or you can just provide the name of the file. The :all symbol will link all of the stylesheets in the public/stylesheets directory. As with scripts, if you’re feeling really fancy, you can define groups of styles with register_stylesheet_expansion, and reference them with symbols.

An internal method used to calculate where to point for an image.

An internal method used to calculate where to point for a JavaScript file.

Lets you register a symbol that can reference JavaScript files. Useful if you consistently use a group of script files together.

Lets you add JavaScript files to the :defaults symbol used by the javascript_include_tag method.

Lets you register a symbol that can reference style files. Useful if you consistently use a group of stylesheets together.

An internal method used to calculate where to point for a stylesheet.

Takes a block, creating an atom:feed element and giving the block an AtomFeedBuilder object that child components can use for context. It also accepts parameters for :language, :root_url, :url, and :schema_date.

Creates an atom:entry element. Accepts parameters for :published, which represents the time when the entry was first published, :update, which represents the time of the latest changes, and :url, where to find the entry.

Takes a time and converts it to the right format for Atom feed times.

The benchmark method takes an optional message argument and an optional logging level argument (:debug, :info, :warn, or :error). It records how long the wrapped code takes to run. It requires a block argument, so it usually looks something like:

<% benchmark "It took this long:" do %>
 <%= my_long_method %>
<% end % >

The message and the length of time it takes to run will end up in the logs.

The cache method lets you flag fragments of your view to be kept for caching. Like benchmark, cache wraps around the view code it’s meant to work on with a block argument:

<% cache do %>
  <%= my_repetitive_method_that_should_be_cached %>
<% end % >

You should only cache information that doesn’t change very often, but many HTML components are pretty stable.

The capture method wraps around view code and stores its output to a variable. You can then reference the variable and have that content appear wherever you need. In operation, it looks like a variable assignment to a method:

<% @trapped_content = capture do %>
  <%= content_to_put_in_there %>
<% end % >

Once you’ve captured it, you can reference @trapped_content wherever it is convenient.

The content_for method is much like capture, but instead of putting the content in a variable, it lets you create a named block you can yield to in order to include the content.

Takes two time values and expresses how far apart they are in rough word descriptions rather than precise time notation—e.g., “2 days,” or “about 1 month,” or “less than a minute.”

Like distance_of_time_in_words, but with the to_time always set to now.

The date_select method creates drop-down year, month, and day select fields bound to a particular ActiveRecord object of type :date.

The datetime_select method creates drop-down year, month, day, hour, minute, and second select fields bound to a particular ActiveRecord object of type :datetime.

The time_select method creates drop-down hour, minute, and second select fields bound to a particular ActiveRecord object of type :time.

The select_date method creates drop-down year, month, and day select fields.

The select_datetime method creates drop-down year, month, day, hour, minute, and second select fields.

The select_day method creates a drop-down field for day of the month (1–31).

The select_hour method creates a drop-down field for hours (0–23).

The select_minute method creates a drop-down field for minutes (0–59).

The select_month method creates a drop-down field for month (1–12).

The select_second method creates a drop-down field for seconds (0–59).

The select_time method creates drop-down hour, minute, and second select fields.

The select_year method creates a drop-down field for year. By default it uses five years on either side of the current or selected year, but you can set start and end years through parameters.

The debug method takes an object as its argument. It then serializes the object into YAML, and wraps the YAML output (and any errors) in pre tags so you can inspect it.

Creates a checkbox field bound to an attribute from the object specified in form_for or in the parameters. (It also creates a hidden field bound to the same attribute for use if the checkbox isn’t checked.)

fields_for is like form_for, except that it doesn’t create the actual form tags.

Creates a file upload field bound to an attribute from the object specified in form_for or in the parameters. (You’ll need to modify the form_for call as described in Chapter 8, Improving Forms to use this method.)

Creates a form element and sets the context for the other helper methods in FormHelper.

Creates a hidden field bound to an attribute from the object specified in form_for or in the parameters.

Creates a label for a field created with the other methods of FormHelper.

Creates a password field bound to an attribute from the object specified in form_for or in the parameters.

Creates a radio button bound to an attribute from the object specified in form_for or in the parameters.

Creates a larger multiline text area bound to an attribute from the object specified in form_for or in the parameters.

Creates a single-line text field bound to an attribute from the object specified in form_for or in the parameters.

Lets you create checkboxes. Unlike check_box, it doesn’t automatically create a hidden field for use if the box is unchecked.

Creates a fieldset tag for grouping form elements. You can set the legend for the fieldset as an argument.

Creates a file upload tag. To use this, you also need to give the form_tag method a :multipart => true parameter.

Creates a form tag that wraps around other form elements but does not set context like form_for.

Creates a hidden form field.

Not for submitting images, but rather for creating submit buttons that are presented as images.

Creates a label.

Creates a password field.

Creates a radio button.

Creates a drop-down select or multiselect list.

Creates a submit button with a text caption.

Creates a larger multiline text area.

Creates a single-line text field.

Creates a select list from a specified object or array.

Creates option tags for an alphabetical list of countries, accepting arguments to indicate which should be selected and which should appear first in the list.

Creates a complete select list of countries including option tags. Also accepts arguments for a selected default and for giving countries higher priority in the list.

Creates option tags structured with optgroup tags based on an object or array.

Creates option tags based on a hash or array.

Creates option tags based on a collection object.

Creates a complete select list including option tags.

Returns option tags for time zones across the planet.

Returns a complete select list for time zones across the planet.

Creates a button that will call a JavaScript function using its onclick handler. It accepts a block of code, which works like RJS.

Creates a link to Prototype and other JavaScript files, but is best avoided. Use javascript_include_tag instead.

Reformats JavaScript containing carriage returns and quotes so that it can safely be put into HTML attribute values.

Creates a script tag. Again, javascript_include_tag may be a better option.

Creates a link that will call a JavaScript function. Like button_to_function, it also can take a block that works like RJS.

Turns a number into a currency representation. You can select the :unit (denomination), :separator (normally .), :delimiter (normally , ), :format (whether the currency comes before or after the number), and :precision (normally 2).

Turns file-size byte counts into more typical human representations, like 12 GB.

Turns a number into a percent value. You can select the :precision (normally three digits after the decimal), and the :separator (normally .).

Turns a number into an American-style telephone number. You can specify a country code, extension, delimiter, and whether or not the area code has parentheses, but you can’t specify how the numbers are broken down.

Formats a number with a given :delimiter between thousands (, by default) and decimal :separator (. by default).

Formats a number to present as many digits after the decimal point as are specified in the second argument (three is the default).

Evaluates the JavaScript response from a remote service using the JavaScript eval method. The eval method opens JavaScript applications up to attack, so be certain that what you’re processing is free of potentially harmful code.

Same as remote_form_for, described later.

Creates a form element that uses an XmlHttpRequest call to submit form data. This allows the page to handle the response rather than reloading an entirely new page.

Creates a link that issues an XmlHttpRequest call, again allowing the page to handle the response rather than replacing the current page with a new destination.

Watches the content of a given field and makes a remote call (or a JavaScript function call) when the content of that field changes. Useful for components like text fields that provide suggestions.

Watches the content of a given form and makes a remote call (or a JavaScript function call) when the content of that field changes.

Makes an XmlHttpRequest call every so often, according to a duration specified in seconds set as the :frequency option.

Works like form_for, except that submitting the form triggers an XmlHttpRequest call that gets handled by Ajax in the browser instead of the usual form submission process.

Returns the JavaScript needed to make an XmlHttpRequest call to a remote function.

Creates a button that will submit a form using an XmlHttpRequest call.

Creates the context for RJS calls, allowing a block of code to update multiple elements on the same page.

Creates JavaScript, wrapped in a script tag, using the same mechanisms as creating RJS code.

Creates a value suitable for a class attribute that is the singular form of the object name.

Creates a value suitable for an id attribute that is the singular form of the object name plus _ and the object’s id value.

Creates a value containing plural/singular form of an object’s name, like turtles/turtle or people/person.

The sanitize method provides a customizable approach to removing attributes and markup that you don’t want to pass through. The customization can be specified through the :tags and :attributes parameters, or set by default through initializer code.

The sanitize_css method removes features from CSS that the creators of sanitize felt were too dangerous. This is used by sanitize on style attributes.

The strip_links method leaves markup other than links intact, but removes all links from the argument.

The strip_tags method removes all HTML markup from the argument. (The documentation warns that it may not always find all HTML markup, however.)

Identifies an HTML element, specified by id attribute value, as supporting user efforts to drag it around the screen and potentially drop it on a receiving element.

Identifies an HTML element, again by id attribute value, as a container where users can drop draggable objects and expect a response. When the drop happens, the code this creates can make a remote Ajax call or a local JavaScript call, and supports class-based constraints on which objects to accept. It also supports changing the class of the receiving element to give users visual feedback when they’ve positioned a draggable object over a container that could accept it.

Identifies an HTML element, again by id attribute value, as a collection users can reorder, making an Ajax call when changes occur.

Provides access to the Script.aculo.us library’s collection of visual effects, applying them to an HTML element specified by id.

As its name suggests, the cdata_section method lets you create CDATA sections wrapping the content specified in the argument. (CDATA sections let you mark sections of an XML document as not containing any markup, so you can use <, >, and & to your heart’s content.)

The content_tag method is a generic tag building method. You define the name of the tag, the attributes, and the content of the tag through the arguments.

The escape_once method is extremely convenient when you have content that needs <, >, and & escaped—but you might already have done some of the escaping. This method is smart enough to escape markup text that needs escaping, while leaving the ampersands that are part of prior escaping alone.

The tag method creates an empty tag (like <br />).

The auto_link method is a simple way to make links live without requiring people to use HTML. Its first argument is a block of text. By default, it will turn all URLs and email addresses in that text into live links. The link parameter defaults to :all, but also accepts :email_addresses and :urls as options if you just want one or the other. The href_options parameter lets you add attributes.

(If you want to get really fancy, you can supply a block of code that will be executed for every link that gets added, letting you control processing precisely.)

Used for those obscure times when you want to generate output inside of a <% %> ERb code block instead of the usual <%= %> block.

Creates an object that lets you alternate different values for each member of an array. This lets you do things like alternate formatting to reflect even and odd rows, or mark every 10th element.

Finds a given phrase in a given text and returns the phrase with surrounding context.

Finds a given phrase in a given text and marks all occurrences with <strong class="highlight" >.

When used with the BlueCloth plug-in (http://www.deveiate.org/projects/BlueCloth), lets you convert text containing Markdown codes (http://daringfireball.net/projects/markdown/syntax) into HTML.

Lets you apply Rails’ inflector (the same code that manages singular and plural for ActiveRecord objects) to any text you’d like.

Starts a cycle (described earlier) over again.

Adds HTML line breaks and paragraph marks to plain text.

When used with the RedCloth plug-in (http://whytheluckystiff.net/ruby/redcloth/), lets you convert text containing Textilize codes (http://www.textism.com/tools/textile) into HTML.

Just like textilize, but with one fewer surrounding paragraph mark (<p>...</p>).

Cuts off the end of a string after a specified number of characters and adds a truncate string, usually ....

Wraps text to a specified line width, breaking on whitespace when possible.

Generates a form containing a single button that links to the specified controller. (It’s the same as url_for, but wraps the result in a button.) You can ask users to confirm their interest after clicking the button.

Returns true if the current page has the same URL as the URL created by the options listed.

Creates a link (a) element linking to the specified controller. (It’s the same as url_for, but wraps the result in an HTML link.)

Like link_to, but lets you specify conditions.

Like link_to, but lets you specify prohibitions.

Like link_to, but won’t link if the link is to the current page.

Creates a mailto: link to a given email address.

Creates a URL based on the options provided and the Rails application’s routing table.