HasStimulusAttrs

Helper methods for dealing with stimulus data attributes.

Relies on has_dom_attrs and stimulus_helpers.

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add has_stimulus_attrs

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install has_stimulus_attrs

Usage

Include HasStimulusAttrs in your class and define a controller_name class method:

class ModalComponent
  include HasStimulusAttrs

  def self.controller_name
    "modal-component"
  end
end

controller_name can also be defined in a base class and dynamically resolved:

class ApplicationComponent
  include HasStimulusAttrs

  def self.controller_name
    self.name.underscore.dasherize
  end
end

class DetailsComponent < ApplicationComponent
end

DetailsComponent.controller_name
# => "details-component"

You can then use the included class methods to easily set stimulus attributes on your class:

class ModalComponent < ApplicationComponent
  # Controller
  has_stimulus_controller # sets the "controller" data attribute using :controller_name by default
  has_stimulus_controller "click-outside"
  has_stimulus_controller "scroll-lock", if: :open? # conditionally add the controller
  has_stimulus_controller "scroll-lock", unless: :closed? # conditionally add the controller

  # Action
  has_stimulus_action "click", "onClick"
  has_stimulus_action "click", "onClick", if: :open?

  # Class
  has_stimulus_class "open", "modal--open"
  has_stimulus_class "width", -> { "modal--#{width}" } # resolve the class name dynamically

  # Outlet
  has_stimulus_outlet "outlet", ".selector"

  # Param
  has_stimulus_param :id, 123
  has_stimulus_param :id, -> { id }

  # Target
  has_stimulus_target "target"
  has_stimulus_target "target", controller: "other-controller"

  # Value
  has_stimulus_value "id", 123
  has_stimulus_value "id", -> { id }
  has_stimulus_value "id", -> { id }, controller: "other-controller"
end

Development

After checking out the repo, run bin/setup to install dependencies. 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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/tomasc/has_stimulus_attrs.