ReActionView Documentation

ReActionView is an ActionView-compatible ERB engine that integrates Herb::Engine into Rails applications. It replaces or enhances standard ERB rendering with an HTML-aware parser (built on Prism) to provide modern developer experiences.

Key capabilities include:

• HTML-aware parsing: Uses the Herb parser for better template understanding.
• HTML Validation & Security: Provides context-aware validation and security checks.
• Enhanced Error Feedback: Uses validation overlays to display template errors directly in the browser.
• Debug Mode: Injects element metadata into the HTML for visual debugging.
• Full Compatibility: Designed as a zero-breaking-change replacement for standard .html.erb templates, preserving Rails helpers, conventions, and the asset pipeline.

ReActionView offers two distinct ways to leverage the enhanced Herb::Engine rendering:

1. Native .html.herb templates: Use the .html.herb file extension for templates you want to be automatically processed with Herb::Engine.
2. Intercept .html.erb templates: By enabling intercept_erb in the configuration, you can instruct ReActionView to process all standard .html.erb templates using the Herb engine instead of the default Rails ERB engine.

Because ReActionView is built on Herb::Engine, it automatically integrates with the Herb ecosystem's development tools. This provides a suite of tools for template development, including:

• Formatter: Ensures consistent template formatting.
• Linter: Provides HTML-aware linting rules.
• Language Server: Enables editor integration and IntelliSense.
• VS Code Extension: Offers full IDE support.

ReActionView operates by intercepting the template rendering lifecycle:

1. Template Registration: It registers itself as a handler for .html.herb files and can optionally intercept standard .html.erb files.
2. Herb Processing: Templates are processed via the Herb::Engine instead of the standard Ruby ERB parser.
3. Enhanced Output: The engine performs validation, security checks, and (if enabled) injects debug metadata.
4. Rails Integration: The final output is compatible with Rails' @output_buffer and standard HTML safety mechanisms.

ReActionView can display validation errors and template issues directly in the browser as HTML overlays. This mode provides real-time feedback during development without crashing your application or raising exceptions, making it ideal for a smoother development experience when dealing with template issues.

# Set the validation mode to :overlay to enable browser overlays
config.validation_mode = :overlay

ReActionView integrates with Rails applications as a template handler to provide enhanced ERB processing. It supports Rails 7.0+ and is recommended for Rails 8.0+.

Integration is achieved through:

• Template Handler Registration: Automatically registers support for .herb files.
• ERB Interception: Can be configured to optionally process all .html.erb files.
• ActionView Compatibility: Maintains full compatibility with standard Rails conventions.
• Railtie Integration: Provides automatic setup and configuration via a Railtie.

For the best development experience in VS Code, install the Herb Language Server extension. This provides IntelliSense and IDE support for ReActionView templates.

code --install-extension marcoroth.herb-lsp

Use the Rails generator to create the initial configuration file at config/initializers/reactionview.rb.

rails generate reactionview:install

To install ReActionView, add the gem to your Gemfile and run bundle install.

Requirements

• Ruby: 3.0+ (3.4+ recommended)
• Rails: 7.0+ (8.0+ recommended)
• Herb: Installed automatically as a dependency.

gem "reactionview"

bundle install

Debug mode injects metadata attributes into HTML elements during development to assist with template debugging and element identification. It is enabled by default in development environments, but you can explicitly control it via the config.debug_mode setting in your ReActionView initializer.

To configure this, use the ReActionView.configure block in config/initializers/reactionview.rb.

ReActionView.configure do |config|
  config.debug_mode = Rails.env.development?
end

The ReActionView::Template::Handlers::Herb class manages how templates are processed using the Herb engine. It integrates with ReActionView.config to determine debugging and validation behavior.

Key configuration behaviors:

• Debug Mode: When ReActionView.config.debug_mode_enabled? is true and the template is a local file, a ::Herb::Engine::DebugVisitor is automatically added to the processing pipeline.
• Validation Mode: The validation_mode (e.g., :overlay, :raise, or :none) determines how validation errors are presented. If set to :overlay, specific HTML markup is injected into layout templates to provide user instructions.
• Transform Visitors: Any visitors defined in ReActionView.config.transform_visitors are appended to the processing pipeline during the template call.