Recommended way to call custom Rails helper methods

[adamlogic]

When migrating a legacy app to Phlex, we have many existing helper methods that return HTML. I can call these methods via helpers.my_helper, but that doesn't append to the output buffer. My current solution is to call unsafe_raw helpers.my_helper, and I'm wondering if there's a better way.

def template
  div class: "relative px-4" do
    unsafe_raw helpers.svg_icon(:chevronleft)
  end
end

[joeldrapper]

That’s a really good question. It’s not been considered part of the public API, but there's actually a module to help define adapters for Rails helpers, which is used in defining all the built-in adapters. The built-in adapters are mostly all defined in this file, which is a good example to look at.

The module is Phlex::Rails::HelperMacros, and it provides the following:

.define_output_helper

This is for helpers that return HTML. You’d typically use them with <%= %> tags in ERB.

Example:

module Helpers::AudioTag
  extend Phlex::Rails::HelperMacros
  define_output_helper :audio_tag
end

.define_output_helper_with_capture_block

This is for output helpers that accept a block, e.g. link_to("/") { "Hello" }

Example:

module Helpers::LinkTo
  extend Phlex::Rails::HelperMacros
  define_output_helper_with_capture_block :link_to
end

.define_value_helper

This is for helpers that return a value that you need to use directly. You would typically use these helpers as content or attribute values.

Example:

module Helpers::AssetURL
  extend Phlex::Rails::HelperMacros
  define_value_helper :asset_url
end

.define_value_helper_with_capture_block

Same as value helpers, but where the helper accepts a block.

Example:

module Helpers::ContentFor
  extend Phlex::Rails::HelperMacros
  define_value_helper_with_capture_block :content_for
end

.define_builder_yielding_helper

You probably won’t need this, but these helpers yield a builder object to the given block, and that builder object needs to be decorated so that its methods work as expected.

Example:

module Helpers::FormWith
  extend Phlex::Rails::HelperMacros
  define_builder_yielding_helper :form_with, Phlex::Rails::BufferedFormBuilder
end

Note that BufferedFormBuilder is a decorator for a form builder defined here. It too has methods that can yield builders such as label, fields and fields_for.

---

For your use case, you probably want to define a module — maybe ApplicationHelpers — that adapts all your custom helpers:

module ApplicationHelpers
  extend Phlex::Rails::HelperMacros

  define_output_helper :foo_helper
  define_value_helper :bar_helper
end

Then you can include this in ApplicationComponent, and the methods #foo_helper and bar_helper will be available.

class ApplicationComponent < Phlex::HTML
  include ApplicationHelpers
end

class MyComponent < ApplicationComponent
  def template
    foo_helper
    h1(class: bar_helper) { "Hi" }
  end
end

[adamlogic]

Amazing answer. Thanks!!

[joeldrapper]

I should add that it’s perfectly fine to do something like this directly instead, especially if you don’t need to worry about capturing blocks.

def svg_icon(...)
  unsafe_raw helpers.svg_icon(...)
end

If you want to be extra safe, you could check that the helper returns a safe string before passing it to unsafe_raw.

def svg_icon(...)
  output = helpers.svg_icon(...)
  
  if ActiveSupport::SafeBuffer === output
    unsafe_raw output
  end
end