Action View

Active contributors: rafaelfranca, jonhefner, hartleymcguire

Purpose

Action View renders templates. It owns the template lookup pipeline, the ERB compiler, the helper library (form helpers, asset tags, URL helpers, number/date formatting), and the partial / layout machinery. ~19K lines of lib/ Ruby.

It was extracted from Action Pack in Rails 3 and is now an independent gem; controllers include ActionView::Layouts and friends to opt in.

Directory layout

actionview/
├── lib/
│   └── action_view/
│       ├── base.rb                  # ActionView::Base (the rendering context)
│       ├── buffers.rb               # OutputBuffer, StreamingBuffer
│       ├── context.rb
│       ├── digestor.rb              # Template digests for cache keys
│       ├── flows.rb                 # ContentFor, layout flow
│       ├── helpers/                 # ~30 helper modules
│       ├── helpers.rb
│       ├── layouts.rb               # Layout finding and rendering
│       ├── lookup_context.rb        # Per-controller template lookup
│       ├── path_set.rb              # Ordered set of template paths
│       ├── path_registry.rb
│       ├── render_parser.rb         # Static analysis of `render` calls
│       ├── renderer/                # Concrete renderers: template, partial, collection
│       ├── rendering.rb             # Mixin pulled into ActionController
│       ├── routing_url_for.rb
│       ├── template/                # Template implementations + handlers
│       ├── template.rb
│       ├── template_details.rb
│       └── …
├── test/
└── actionview.gemspec

Helpers

actionview/lib/action_view/helpers/ is one of the most-touched areas of the framework. Notable modules:

• asset_tag_helper.rb / asset_url_helper.rb — image_tag, javascript_include_tag, stylesheet_link_tag.
• cache_helper.rb — cache do ... end (Russian-doll caching with template digests).
• csp_helper.rb, csrf_helper.rb — security tokens and meta tags.
• date_helper.rb — time_ago_in_words, select_date, datetime_select.
• form_helper.rb — form_with, text_field, submit, etc. (the longest production file at 2,766 lines).
• form_options_helper.rb — select, collection_select, grouped options.
• form_tag_helper.rb — standalone tag helpers.
• number_helper.rb — number_to_currency, number_with_delimiter.
• output_safety_helper.rb — raw, safe_join.
• sanitize_helper.rb — sanitize, allowlist HTML.
• tag_helper.rb — tag.div(class: "btn") { "Click" }.
• text_helper.rb — truncate, simple_format, excerpt.
• translation_helper.rb — t(:key) / l(time).
• url_helper.rb — link_to, mail_to, button_to.

Inside helpers/tags/ are the individual form-element classes (text_field.rb, hidden_field.rb, select.rb, …). Per AGENTS.md, when you change form behavior, check all three layers — tags/, form_helper.rb, and form_tag_helper.rb — for consistency.

Templates and rendering

graph LR
    A["render 'show'"] --> B[LookupContext]
    B --> C[Resolver finds template]
    C --> D[Template]
    D --> E[Handler compiles to Ruby]
    E --> F[Compiled template method]
    F --> G[OutputBuffer]
    G --> H[String]

• ActionView::Base is the rendering context. A new instance is created per controller-rendered response, mixing in helpers and view-locals.
• LookupContext (lookup_context.rb) carries the search paths, locales, formats, variants, and view paths.
• Resolver classes (in template/resolver.rb and path_resolver.rb) find templates on disk.
• Handlers (template/handlers/) compile a template's source. Built-in handlers: ERB::Erubi, Builder, Raw, Html. Each handler turns a template string into a Ruby method body.
• Template wraps the compiled method along with metadata (digest, encoding, variant).
• Renderer (renderer/renderer.rb, template_renderer.rb, partial_renderer.rb) drives the actual rendering call, including layout wrapping and partial collection support.

Partials and collections

renderer/partial_renderer.rb and partial_renderer/collection_caching.rb implement render partial:. Iteration over a collection is optimized: a single template lookup plus per-element render. cached: true triggers cache fragment lookup keyed by the per-element cache key plus the partial's digest.

Layouts

layouts.rb mixes ActionView::Layouts into controllers. The layout is resolved relative to the controller name — PostsController looks for layouts/posts then falls back to layouts/application. _layout is exposed as a class attribute.

flows.rb implements content_for, provide, and yield :section for layouts.

Streaming

actionview/lib/action_view/renderer/streaming_template_renderer.rb renders a template incrementally for HTTP streaming, sending head and body chunks as they're produced. The output buffer is ActionView::StreamingBuffer.

Template digests

actionview/lib/action_view/digestor.rb computes a stable hash of a template tree (template + every partial it renders, recursively). This is used as part of the cache key for fragment caching, so changes to a partial automatically expire enclosing fragments.

Render parser

render_parser.rb and the dependency_tracker/ directory perform static analysis of render calls in templates. They power:

• Auto-cache-key invalidation (knowing which partials a template depends on).
• The ActionView::TemplateAssertions matchers in tests.

The parser uses Prism (Gemfile) when available.

Integration points

• Action Controller: ActionView::Rendering is included in ActionController::Base so render :show Just Works.
• Action Mailer: uses Action View to render mail templates. ActionMailer::Base#mail resolves templates through a LookupContext.
• Active Storage: ships partials under activestorage/app/views/active_storage/.
• Action Text: ships rich text rendering helpers and partials.

Asset integration

asset_tag_helper.rb resolves URLs through the configured asset host. The actual asset compilation is delegated to the host gem (Sprockets, Propshaft, Importmap, Webpacker), each of which provides its own railtie that registers helpers on ActionView::Base.

Testing

ActionView::TestCase (actionview/lib/action_view/test_case.rb) is the base for view tests. It sets up:

• assert_dom_equal / assert_dom_not_equal for HTML comparison.
• A view context with helpers loaded.
• _routes so URL helpers work.

For integration with controllers, ActionView::TemplateAssertions provides assert_template.

Entry points for modification

• Adding a helper: new file under actionview/lib/action_view/helpers/, include in actionview/lib/action_view/helpers.rb. Tests under actionview/test/template/<helper>_test.rb.
• Adding a form tag class: new file under actionview/lib/action_view/helpers/tags/ plus a top-level method in form_helper.rb and form_tag_helper.rb for consistency.
• Adding a template handler: subclass ActionView::Template::Handlers::Base, register via ActionView::Template.register_template_handler(:ext, MyHandler).
• Adding a resolver: subclass ActionView::Resolver, append to ActionController::Base.view_paths.

Related pages

• packages/action-pack — controllers compose the view context.
• packages/active-model — form helpers consume ActiveModel::Errors and Naming.
• packages/action-text — rich text rendering layered on top of Action View.