Stimulizer

Easily work with StimulusJS data-* attributes in ViewComponents, Phlex templates, etc.

This gem is particularly handy in ViewComponents and Phlex when you have a 1-1 relationship between a component and a Stimulus controller, especially when using 'sidecar' controllers.

For example:

  class Mynamespace::Deeper::ButtonsGridComponent < ApplicationComponent
  # ...

<div 
  data-controller="mynamespace--deeper--buttons-grid-component"
  data-mynamespace--deeper--buttons-grid-component-url-value="http://example.com"
  data-mynamespace--deeper--buttons-grid-component-color-value="#ff0000"
  data-action="click->data-mynamespace--deeper--buttons-grid-component#doSomething"
>

<div 
  <%= stimulus(
    :controller, 
    values: {url: "http://example.com", color: "#ff0000"}, 
    action: "click->doSomething"
  )%>
>

Add this line to your application's Gemfile:

gem 'stimulizer'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install stimulizer

Include the module in your ApplicationController (or individual controllers):

class ApplicationController < ActionController::Base
  include Stimulizer
  helper_method :stimulus
  # ...

NOTE that you have to add helper_method :stimulus to ensure the view templates can use the stimulus method.

Include this in your class:

class MyComponent < ApplicationComponent
  include Stimulizer
  # ...

Render the stimulusjs data strings into your template...

  <!-- use the derived controller name -->
  <%= stimulus(:controller) %>   

  <!-- specify the controller explicity, and/or add more controllers space-separated -->
  <%= stimulus(controller: "another foo")
  
  <!-- Note: 'action' is singular because it works like 'data-action' -->
  <%= stimulus(action: "click->doThing")

  <!-- but you can have multiple actions separated by spaces -->
  <%= stimulus(action: "click->doThing mouseup->otherThing")

  <!-- you can also skip the event, just like usual -->
  <%= stimulus(action: "doThing")

  <!-- 
    target for this element (if you need to also target it for other controllers, you'll have to do that manually with the old 'data-blah-target=' approach)
  -->
  <%= stimulus(target: "button")

  <!-- supports the 'classes' feature -->
  <%= stimulus(classes: {foo: "text-red-500", busy: "opacity-50 animate-spin"})
  
  <!-- supports the 'values' feature -->
  <%= stimulus(values: {url: "https://example.com"})

  <!-- supports the 'params' feature -->
  <%= stimulus(params: {foo: "bar", this_thing: "whatever"})
     
  <!-- supports the 'outlets' feature -->
  <%= stimulus(outlets: {foo: ".my-class", bar: "#widget"})     

... or combine them:

  <%= stimulus(:controller, target: "button", action: "click->doThing")

Use the stimulize method after including the module to set some config options...

Use the ignore_prefix option to chop off some of the namespacing if you want to shorten up those crazy-long controller filenames.

stimulize ignore_prefix: "Components::"

Use the output option to change from an html-style string of data attributes (default) to a Hash of data attributes, useful in other circumstances, like tag builders and Phlex views.

stimulize output: :hash

My main use case for Stimulizer is with so-called 'sidecar' javascript. That is, if I have a component in the filepath components/foo/bar/other/button_component.rb, I will also have a stimulus controller at components/foo/bar/other/button_component_controller.js.

In this case, Stimulizer will auto-derive the controller name properly.

If you're not doing things this way, you may need to manually set your controller name in each component/template...

def stimulus_controller
  "whatever--name--you-want-here"
end

or...

You can also pass the controller name directly to the stimulus() method. This starts to become less automagical, but still handy in reducing the repetition of those controller names.

<div
  <%= stimulus(
    controller_name: "my--fancy--buttons", 
    action: "click->show", 
    values: {url: "example.com"}
  ) %>
>

# => <div data-controller='my--fancy--buttons' data-action='click->my--fancy--buttons#show' data-my--fancy--buttons-url-value="example.com">

By default, Stimulizer returns a html-style string of data-* attributes from the stimulus() method. But if you're using something like Phlex templates, or if you want to use this with a tag-building method, you might want the original Hash instead. You have two options:

module Views
  class ApplicationView < Phlex::View
    include Stimulizer
    stimulize output: :hash

stimulus_hash(:controller, action: "click->doThis")

Thanks to @joeldrapper for suggesting this and for inspiring the idea of this gem. You can use destructuring to great effect in Phlex views:

div(**stimulus(:controller, action: "click->show"), class: "text-red-500") do
  # ...

Note that this example is assuming you've turned on :hash mode as above. You could also use **stimulus_hash() in the same way.

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/stimulizer. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Stimulizer project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.