2.4.0

• Updated Phlex to 2.4.0
• The default cache store is now Rails.cache. Previously it was unset.
• Added javascript_importmap_module_preload_tags and javascript_inline_importmap_tag helpers
• Fixed compatibility issues with Rails 8.1.2
• Made it easier to detect wrapped form builders and added an unwrap method that returns the original form builder
• register_output_helper now accepts mark_safe: true for helpers that return safe HTML strings rather than ActiveSupport::SafeBuffers
• Added Phlex::Rails::Types::Buffered(T) and Phlex::Rails::Types::Builder(T) — the methods return objects that respond to ===(value) for use with Literal, Dry, etc.
• Fixed a Ruby LSP add-on issue that would make it raise when analysing certain syntax
• Updated the no method error that recommends including a helper adapter module. It now includes a snippet that can be pasted verbatim.

2.3.1

Fix an issue with old-style helper methods, such as check_box, text_area as opposed to the newer checkbox, textarea. #301

Full Changelog: 2.3.0...2.3.1

2.3.0

Highlights

• Added support for custom Rails form builders
• New RubyLSP indexing enhancement for register_output_helper and register_value_helper
• You can now customise Phlex’ generators, creating custom templates in lib/generators/phlex/templates/component.rb.erb and lib/generators/phlex/templates/view.rb.erb
• Support for Phlex 2.3

PRs

• Update docs link in helpers deprecation warning by @MSchmidt in #286
• Define send on decorators by @joeldrapper in #290
• Support custom form builders by @joeldrapper in #291
• Add RubyLSP indexing enhancement for helpers by @joeldrapper in #297
• Improve buffered interface by @joeldrapper in #298
• Switch to Zeitwerk by @joeldrapper in #300
• Raise when options_for_select is used as a value by @joeldrapper in #293
• Allow the use of custom generator templates by @UnderpantsGnome in #289

New Contributors

• @MSchmidt made their first contribution in #286
• @UnderpantsGnome made their first contribution in #289

Full Changelog: 2.2.0...2.3.0

2.2.0

Highlights

We fixed a bug where capture would sometimes return nil. You should be able to expect capture to always return a string, even if that strings may be empty and/or frozen.

We also updated Phlex to 2.2.1.

PRs

• Fix a bug where capture could return nil when nothing was captured by @willcosgrove in #285

Full Changelog: 2.1.3...2.2.0

2.1.3

Highlights

• Fixed a regression which caused fragment caching to break
• Caching is now enabled/disabled with config.action_controller.perform_caching
• Fixed an issue with Phlex::CSV where given an ActiveRecord::Relation, it’s meant to use find_each by default but didn’t

What's Changed

• Fix caching by @joeldrapper in #279
• Enable the cache based on Rails app config by @joeldrapper in #280
• Fix Phlex::CSV override by @joeldrapper in #281

Full Changelog: 2.1.2...2.1.3

2.1.2

What's Changed

• Fix vanish context bug by @joeldrapper in #274

Full Changelog: 2.1.1...2.1.2

2.1.1

What's Changed

• Fix layout rendering issue by @joeldrapper in #273

Full Changelog: 2.1.0...2.1.1

2.1.0

Phlex now uses a completely different mechanism for interoperating with ERB templates from ActionView and ViewComponent.

This release is a minor breaking change which means it could break your code, so be careful when upgrading. If you rely on using slot-style components from ERB, you need to make sure you’re not using <%= tags when calling slot methods on the component.

<%= render Table.new(@people) do |t| %>
  <% t.column("Name") do |person| %>
    <%= person.name %>
  <% end %>

  <% t.column("Age") do |person| %>
    <%= person.age %>
  <% end %>
<% end %>

For UI Kit maintainers, it’s probably a good idea to make your slot methods return nil in case a user does pass them to <%= output tags.

def column(header, &content)
  @columns << { header:, content: }
  nil # <-- return nil
end

If we didn’t return nil from column in this example, the <%= ERB output tags would output the to_s of the @columns array.

If your components are builder-style (e.g. not yielding early), you can usually just depend on the fact that most of Phlex own methods return nil.

Impersonating a Rails builder

If you need to use Phlex to impersonate a Rails builder object where builder methods return HTML-safe strings instead of pushing output to a buffer, you will need to wrap each builder method in a capture. I can only think of one library that might need to do this since it’s aiming for exact API compatibility with existing Rails helpers.

Here’s one example:

class Nav < Phlex::HTML
  def view_template(&)
    nav(class: "special-nav", &)
  end

  def item(href, &)
    capture do
      a(class: "special-nav-item", href:, &)
    end
  end

  def divider
    capture do
      span(class: "special-nav-divider")
    end
  end
end

Using this component inside Phlex would be strange because you would have to use raw, to render the captured strings.

render Nav do |n|
  raw n.item("/") { "Home" }
end

It is possible to look at the caller location and see if the caller is an ERB file to determine whether to capture or not, but I’ll leave that to you. Going forward, Phlex will push to the buffer rather than capture whether rendering inside Phlex or from ERB. Previously, the behaviour was different for ERB.

PRs

• Style changes on phlex initializer template by @stephannv in #269
• Direct buffering by @joeldrapper in #271

Full Changelog: 2.0.2...2.1.0

2.1.0.rc1

Summary

This is the first release candidate for v2.1 which uses a completely different architecture for interoperating with ERB templates from ActionView and ViewComponent. It does this by sharing a buffer rather than trying to patch all the different interactions.

This release is a minor breaking change which means it could break your code, so be careful when upgrading. If you rely on using slot-style components from ERB, you need to make sure you’re not using <%= tags when calling slot methods on the component. <%= should be used only for the render or for rendering values. See in this example, we do not use <%= for the t.column call.

<%= render Table.new(@people) do |t| %>
  <% t.column("Name") do |person| %>
    <%= person.name %>
  <% end %>

  <% t.column("Age") do |person| %>
    <%= person.age %>
  <% end %>
<% end %>

For UI Kit maintainers, it’s probably a good idea to make your slot methods return nil in case a user does pass them to <%= output tags. If we didn’t return nil from column in this example, the <%= ERB output tags would output the to_s of the @columns array.

def column(header, &content)
  @columns << { header:, content: }
  nil # <-- return nil
end

If your components are builder-style (e.g. not yielding early), you can usually just depend on the fact that most of Phlex own methods return nil.

Impersonating a Rails builder

If you need to use Phlex to impersonate a Rails builder object where builder methods return HTML-safe strings instead of pushing output to a buffer, you will need to wrap each builder method in a capture. I can only think of one library that might need to do this for API compatibility.

class Nav < Phlex::HTML
  def view_template(&)
    nav(class: "special-nav", &)
  end

  def item(href, &)
    capture do
      a(class: "special-nav-item", href:, &)
    end
  end

  def divider
    capture do
      span(class: "special-nav-divider")
    end
  end
end

Using this component inside Phlex would be strange because you would have to use raw, to render the captured strings.

render Nav do |n|
  raw n.item("/") { "Home" }
end

PRs

• Style changes on phlex initializer template by @stephannv in #269
• Direct buffering by @joeldrapper in #271

Full Changelog: 2.0.2...2.1.0.rc1

2.0.2

What's Changed

• Fixed an issue where rendering a Phlex component with a Rails view context but without a request would trigger an error.
• Improved the feature that suggests including a Rails view helper adapter when you call a missing helper method.

Full Changelog: 2.0.1...2.0.2