123456789_123456789_123456789_123456789_123456789_

Class: ActionView::Base

Overview

Action View templates can be written in several ways. If the template file has a .erb extension, then it uses the erubi template system which can embed Ruby into an HTML document. If the template file has a .builder extension, then Jim Weirich's Builder::XmlMarkup library is used.

ERB

You trigger ::ERB by using embeddings such as <% %>, <% -%>, and <%= %>. The <%= %> tag set is used when you want output. Consider the following loop for names:

<b>Names of all the people</b>
<% @people.each do |person| %>
Name: <%= person.name %><br/>
<% end %>

The loop is set up in regular embedding tags <% %>, and the name is written using the output embedding tag <%= %>. Note that this is not just a usage suggestion. Regular output functions like print or puts won't work with ::ERB templates. So this would be wrong:

<%# WRONG %>
Hi, Mr. <% puts "Frodo" %>

If you absolutely must write from within a function use concat.

When on a line that only contains whitespaces except for the tag, <% %> suppresses leading and trailing whitespace, including the trailing newline. <% %> and <%- -%> are the same. Note however that <%= %> and <%= -%> are different: only the latter removes trailing whitespaces.

Using sub templates

Using sub templates allows you to sidestep tedious replication and extract common display structures in shared templates. The classic example is the use of a header and footer (even though the Action Pack-way would be to use Layouts):

<%= render "application/header" %>
Something really specific and terrific
<%= render "application/footer" %>

As you see, we use the output embeddings for the render methods. The render call itself will just return a string holding the result of the rendering. The output embedding writes it to the current template.

But you don't have to restrict yourself to static includes. Templates can share variables amongst themselves by using instance variables defined using the regular embedding tags. Like this:

<% @page_title = "A Wonderful Hello" %>
<%= render "application/header" %>

Now the header can pick up on the @page_title variable and use it for outputting a title tag:

<%= @page_title %>

Passing local variables to sub templates

You can pass local variables to sub templates by using a hash with the variable names as keys and the objects as values:

<%= render "application/header", { headline: "Welcome", person: person } %>

These can now be accessed in application/header with:

Headline: <%= headline %>
First name: <%= person.first_name %>

The local variables passed to sub templates can be accessed as a hash using the local_assigns hash. This lets you access the variables as:

Headline: <%= local_assigns[:headline] %>

This is useful in cases where you aren't sure if the local variable has been assigned. Alternatively, you could also use defined? headline to first check if the variable has been assigned before using it.

By default, templates will accept any locals as keyword arguments. To restrict what locals a template accepts, add a locals: magic comment:

<%# locals: (headline:) %>

Headline: <%= headline %>

In cases where the local variables are optional, declare the keyword argument with a default value:

<%# locals: (headline: nil) %>

<% unless headline.nil? %>
Headline: <%= headline %>
<% end %>

Read more about strict locals in Action View Overview in the guides.

Template caching

By default, Rails will compile each template to a method in order to render it. When you alter a template, Rails will check the file's modification time and recompile it in development mode.

Builder

Builder templates are a more programmatic alternative to ::ERB. They are especially useful for generating XML content. An XmlMarkup object named xml is automatically made available to templates with a .builder extension.

Here are some basic examples:

xml.em("emphasized")                                 # => <em>emphasized</em>
xml.em { xml.b("emph & bold") }                      # => <em><b>emph &amp; bold</b></em>
xml.a("A Link", "href" => "http://onestepback.org")  # => <a href="http://onestepback.org">A Link</a>
xml.target("name" => "compile", "option" => "fast")  # => <target option="fast" name="compile"\>
                                                   # NOTE: order of attributes is not specified.

Any method with a block will be treated as an XML markup tag with nested markup in the block. For example, the following:

xml.div do
xml.h1(@person.name)
xml.p(@person.bio)
end

would produce something like:

David Heinemeier Hansson

A product of Danish Design during the Winter of '79...

Here is a full-length RSS example actually used on Basecamp:

xml.rss("version" => "2.0", "xmlns:dc" => "http://purl.org/dc/elements/1.1/") do
xml.channel do
  xml.title(@feed_title)
  xml.link(@url)
  xml.description "Basecamp: Recent items"
  xml.language "en-us"
  xml.ttl "40"

  @recent_items.each do |item|
    xml.item do
      xml.title(item_title(item))
      xml.description(item_description(item)) if item_description(item)
      xml.pubDate(item_pubDate(item))
      xml.guid(@person.firm..url + @recent_items.url(item))
      xml.link(@person.firm..url + @recent_items.url(item))

      xml.tag!("dc:creator", item.author_name) if item_has_creator?(item)
    end
  end
end
end

For more information on Builder please consult the source code.

Constant Summary

::ERB::Util - Included

HTML_ESCAPE, HTML_ESCAPE_ONCE_REGEXP, INVALID_TAG_NAME_FOLLOWING_REGEXP, INVALID_TAG_NAME_START_REGEXP, SAFE_XML_TAG_NAME_REGEXP, TAG_NAME_FOLLOWING_CODEPOINTS, TAG_NAME_REPLACEMENT_CHAR, TAG_NAME_START_CODEPOINTS

Helpers::AssetUrlHelper - Included

ASSET_EXTENSIONS, ASSET_PUBLIC_DIRECTORIES, URI_REGEXP

Helpers::TagHelper - Included

ARIA_PREFIXES, BOOLEAN_ATTRIBUTES, DATA_PREFIXES, PRE_CONTENT_STRINGS, TAG_TYPES

Helpers::AssetTagHelper - Included

MAX_HEADER_SIZE

Helpers::ContentExfiltrationPreventionHelper - Included

CLOSE_CDATA_COMMENT, CLOSE_FORM_TAG, CLOSE_OPTION_TAG, CLOSE_QUOTES_COMMENT, CONTENT_EXFILTRATION_PREVENTION_MARKUP

Helpers::ControllerHelper - Included

CONTROLLER_DELEGATES

Helpers::DateHelper - Included

MINUTES_IN_QUARTER_YEAR, MINUTES_IN_THREE_QUARTERS_YEAR, MINUTES_IN_YEAR

Helpers::UrlHelper - Included

BUTTON_TAG_METHOD_VERBS, STRINGIFIED_COMMON_METHODS

RecordIdentifier - Included

JOIN, NEW

Helpers::JavaScriptHelper - Included

JS_ESCAPE_MAP

Helpers::TranslationHelper - Included

MISSING_TRANSLATION, NO_DEFAULT

Class Attribute Summary

Class Method Summary

Instance Attribute Summary

Helpers - Included

Helpers::TranslationHelper - Included

#raise_on_missing_translations

Specify whether an error should be raised for missing translations.

Helpers::JavaScriptHelper - Included

Helpers::FormHelper - Included

Helpers::FormTagHelper - Included

Helpers::SanitizeHelper - Included

Helpers::UrlHelper - Included

Helpers::ControllerHelper - Included

Helpers::ContentExfiltrationPreventionHelper - Included

Helpers::CacheHelper - Included

#caching?

Returns whether the current view fragment is within a cache block.

Helpers::AssetTagHelper - Included

Context - Included

Instance Method Summary

Helpers::TranslationHelper - Included

#l
#localize

Delegates to I18n.localize with no additional functionality.

#t
#translate

Delegates to I18n#translate but also performs three additional functions.

#missing_translation, #scope_key_by_partial

Helpers::RenderingHelper - Included

#_layout_for

Overrides _layout_for in the context object so it supports the case a block is passed to a partial.

#render

Renders a template and returns the result.

Helpers::NumberHelper - Included

Helpers::JavaScriptHelper - Included

#escape_javascript

Escapes carriage returns and single and double quotes for JavaScript segments.

#j
#javascript_tag

Returns a JavaScript tag with the content inside.

#javascript_cdata_section

Helpers::FormOptionsHelper - Included

#collection_check_boxes
#collection_checkboxes

Returns check box tags for the collection of existing return values of method for object's class.

#collection_radio_buttons

Returns radio button tags for the collection of existing return values of method for object's class.

#collection_select

Returns

#grouped_collection_select

Returns

#grouped_options_for_select

Returns a string of tags, like #options_for_select, but wraps them with tags:

#option_groups_from_collection_for_select

Returns a string of tags, like #options_from_collection_for_select, but groups them by tags based on the object relationships of the arguments.

#options_for_select

Accepts a container (hash, array, enumerable, your type) and returns a string of option tags.

#options_from_collection_for_select

Returns a string of option tags that have been compiled by iterating over the collection and assigning the result of a call to the value_method as the option value and the text_method as the option text.

#select

Create a select tag and a series of contained option tags for the provided object and method.

#time_zone_options_for_select

Returns a string of option tags for pretty much any time zone in the world.

#time_zone_select

Returns select and option tags for the given object and method, using #time_zone_options_for_select to generate the list of option tags.

#weekday_options_for_select

Returns a string of option tags for the days of the week.

#weekday_select

Returns select and option tags for the given object and method, using #weekday_options_for_select to generate the list of option tags.

#extract_selected_and_disabled, #extract_values_from_collection, #option_html_attributes, #option_text_and_value, #option_value_selected?, #prompt_text, #value_for_collection

Helpers::FormHelper - Included

#check_box
#checkbox

Returns a checkbox tag tailored for accessing a specified attribute (identified by method) on an object assigned to the template (identified by object).

#color_field

Returns a text_field of type "color".

#date_field

Returns a text_field of type "date".

#datetime_field

Returns a text_field of type "datetime-local".

#datetime_local_field
#email_field

Returns a text_field of type "email".

#fields

Scopes input fields with either an explicit scope or model.

#fields_for

Creates a scope around a specific model object like #form_with, but doesn't create the form tags themselves.

#file_field

Returns a file upload input tag tailored for accessing a specified attribute (identified by method) on an object assigned to the template (identified by object).

#form_for

Creates a form that allows the user to create or update the attributes of a specific model object.

#form_with

Creates a form tag based on mixing URLs, scopes, or models.

#hidden_field

Returns a hidden input tag tailored for accessing a specified attribute (identified by method) on an object assigned to the template (identified by object).

#label

Returns a label tag tailored for labelling an input field for a specified attribute (identified by method) on an object assigned to the template (identified by object).

#month_field

Returns a text_field of type "month".

#number_field

Returns an input tag of type "number".

#password_field

Returns an input tag of the "password" type tailored for accessing a specified attribute (identified by method) on an object assigned to the template (identified by object).

#phone_field
#radio_button

Returns a radio button tag for accessing a specified attribute (identified by method) on an object assigned to the template (identified by object).

#range_field

Returns an input tag of type "range".

#search_field

Returns an input of type "search" for accessing a specified attribute (identified by method) on an object assigned to the template (identified by object_name).

#telephone_field

Returns a text_field of type "tel".

#text_area
#text_field

Returns an input tag of the "text" type tailored for accessing a specified attribute (identified by method) on an object assigned to the template (identified by object).

#textarea

Returns a textarea opening and closing tag set tailored for accessing a specified attribute (identified by method) on an object assigned to the template (identified by object).

#time_field

Returns a text_field of type "time".

#url_field

Returns a text_field of type "url".

#week_field

Returns a text_field of type "week".

#default_form_builder_class, #html_options_for_form_with, #instantiate_builder, #_object_for_form_builder, #apply_form_for_options!

RecordIdentifier - Included

#dom_class

The DOM class convention is to use the singular form of an object or class.

#dom_id

The DOM id convention is to use the singular form of an object or class with the id following an underscore.

#dom_target

The DOM target convention is to concatenate any number of parameters into a string.

#record_key_for_dom_id

Returns a string representation of the key attribute(s) that is suitable for use in an HTML DOM id.

ModelNaming - Included

#convert_to_model

Converts the given object to an Active Model compliant one.

#model_name_from_record_or_class

Helpers::FormTagHelper - Included

#button_tag

Creates a button element that defines a submit button, reset button or a generic button which can be used in JavaScript, for example.

#check_box_tag
#checkbox_tag

Creates a check box form input tag.

#color_field_tag

Creates a text field of type "color".

#date_field_tag

Creates a text field of type "date".

#datetime_field_tag

Creates a text field of type "datetime-local".

#datetime_local_field_tag
#email_field_tag

Creates a text field of type "email".

#field_id

Generate an HTML id attribute value for the given name and field combination.

#field_name

Generate an HTML name attribute value for the given name and field combination.

#field_set_tag

Creates a field set for grouping HTML form elements.

#fieldset_tag
#file_field_tag

Creates a file upload field.

#form_tag

Starts a form tag that points the action to a URL configured with url_for_options just like ActionController::Base#url_for.

#hidden_field_tag

Creates a hidden form input field used to transmit data that would be lost due to HTTP's statelessness or data that should be hidden from the user.

#image_submit_tag

Displays an image which when clicked will submit the form.

#label_tag

Creates a label element.

#month_field_tag

Creates a text field of type "month".

#number_field_tag

Creates a number field.

#password_field_tag

Creates a password field, a masked text field that will hide the users input behind a mask character.

#phone_field_tag
#radio_button_tag

Creates a radio button; use groups of radio buttons named the same to allow users to select from a group of options.

#range_field_tag

Creates a range form element.

#search_field_tag

Creates a text field of type "search".

#select_tag

Creates a dropdown selection box, or if the :multiple option is set to true, a multiple choice selection box.

#submit_tag

Creates a submit button with the text value as the caption.

#telephone_field_tag

Creates a text field of type "tel".

#text_area_tag
#text_field_tag

Creates a standard text field; use these text fields to input smaller chunks of text like a username or a search query.

#textarea_tag

Creates a text input area; use a textarea for longer text inputs such as blog posts or descriptions.

#time_field_tag

Creates a text field of type "time".

#url_field_tag

Creates a text field of type "url".

#utf8_enforcer_tag

Creates the hidden UTF-8 enforcer tag.

#week_field_tag

Creates a text field of type "week".

#convert_direct_upload_option_to_url, #extra_tags_for_form, #form_tag_html, #form_tag_with_body, #html_options_for_form,
#sanitize_to_id
#set_default_disable_with

Helpers::TextHelper - Included

#concat

The preferred method of outputting text in your views is to use the <%= "text" %> eRuby syntax.

#current_cycle

Returns the current cycle string after a cycle has been started.

#cycle

Creates a Cycle object whose to_s method cycles through elements of an array every time it is called.

#excerpt

Extracts the first occurrence of phrase plus surrounding text from text.

#highlight

Highlights occurrences of phrases in text by formatting them with a highlighter string.

#pluralize

Attempts to pluralize the singular word unless count is 1.

#reset_cycle

Resets a cycle so that it starts from the first element the next time it is called.

#safe_concat,
#simple_format

Returns text transformed into HTML using simple formatting rules.

#truncate

Truncates text if it is longer than a specified :length.

#word_wrap

Wraps the text into lines no longer than line_width width.

#cut_excerpt_part,
#get_cycle

The cycle helpers need to store the cycles in a place that is guaranteed to be reset every time a page is rendered, so it uses an instance variable of Base.

#set_cycle, #split_paragraphs

Helpers::SanitizeHelper - Included

#sanitize

Sanitizes HTML input, stripping all but known-safe tags and attributes.

#sanitize_css

Sanitizes a block of CSS code.

#strip_links

Strips all link tags from html leaving just the link text.

#strip_tags

Strips all HTML tags from html, including comments and special characters.

Helpers::UrlHelper - Included

#button_to

Generates a form containing a single button that submits to the URL created by the set of options.

#current_page?

True if the current request URI was generated by the given options.

#link_to

Creates an anchor element of the given name using a URL created by the set of options.

#link_to_if

Creates a link tag of the given name using a URL created by the set of options if condition is true, otherwise only the name is returned.

#link_to_unless

Creates a link tag of the given name using a URL created by the set of options unless condition is true, in which case only the name is returned.

#link_to_unless_current

Creates a link tag of the given name using a URL created by the set of options unless the current request URI is the same as the links, in which case only the name is returned (or the given block is yielded, if one exists).

#mail_to

Creates a mailto link tag to the specified email_address, which is also used as the name of the link unless name is specified.

#phone_to

Creates a TEL anchor link tag to the specified phone_number.

#sms_to

Creates an SMS anchor link tag to the specified phone_number.

#add_method_to_attributes!, #convert_options_to_data_attributes, #link_to_remote_options?, #method_for_options, #method_not_get_method?, #method_tag, #remove_trailing_slash!,
#to_form_params

Returns an array of hashes each containing :name and :value keys suitable for use as the names and values of form input fields:

#token_tag, #url_target,
#url_for

Basic implementation of url_for to allow use helpers without routes existence.

#_back_url, #_filtered_referrer

Helpers::DebugHelper - Included

#debug

Returns a YAML representation of object wrapped with

and
.

Helpers::DateHelper - Included

#date_select

Returns a set of select tags (one for year, month, and day) pre-selected for accessing a specified date-based attribute (identified by method) on an object assigned to the template (identified by object).

#datetime_select

Returns a set of select tags (one for year, month, day, hour, and minute) pre-selected for accessing a specified datetime-based attribute (identified by method) on an object assigned to the template (identified by object).

#distance_of_time_in_words

Reports the approximate distance in time between two ::Time, ::Date, or ::DateTime objects or integers as seconds.

#distance_of_time_in_words_to_now
#relative_time_in_words

Like time_ago_in_words, but adds a prefix/suffix depending on whether the time is in the past or future.

#select_date

Returns a set of HTML select-tags (one for year, month, and day) pre-selected with the date.

#select_datetime

Returns a set of HTML select-tags (one for year, month, day, hour, minute, and second) pre-selected with the datetime.

#select_day

Returns a select tag with options for each of the days 1 through 31 with the current day selected.

#select_hour

Returns a select tag with options for each of the hours 0 through 23 with the current hour selected.

#select_minute

Returns a select tag with options for each of the minutes 0 through 59 with the current minute selected.

#select_month

Returns a select tag with options for each of the months January through December with the current month selected.

#select_second

Returns a select tag with options for each of the seconds 0 through 59 with the current second selected.

#select_time

Returns a set of HTML select-tags (one for hour and minute).

#select_year

Returns a select tag with options for each of the five years on each side of the current, which is selected.

#time_ago_in_words

Like distance_of_time_in_words, but where to_time is fixed to Time.now.

#time_select

Returns a set of select tags (one for hour, minute, and optionally second) pre-selected for accessing a specified time-based attribute (identified by method) on an object assigned to the template (identified by object).

#time_tag

Returns an HTML time tag for the given date or time.

#normalize_distance_of_time_argument_to_time

Helpers::CsrfHelper - Included

#csrf_meta_tag
#csrf_meta_tags

Returns meta tags "csrf-param" and "csrf-token" with the name of the cross-site request forgery protection parameter and token, respectively.

Helpers::CspHelper - Included

#csp_meta_tag

Returns a meta tag "csp-nonce" with the per-session nonce value for allowing inline