Welcome to Stimulux! This gem provides a set of helpers to simplify the integration of Stimulus JS with Phlex and HtmlSlice components, focusing on generating the necessary data-* attributes with ease and precision.
The goal is to improve productivity and legibility while working with Stimulus inside Ruby html generation gems.
# ... inside our component
include Stimulux
# data-controller="hello other" data-other-some-thing-value="hey"
div **stimulus_controller('hello', ['other', { someThing: "hey" }]) do
# data-other-no-results-class='bg-gray-500'
div **stimulus_class(['other', { 'noResults' => 'bg-gray-500' }]) do
# data-hello-target="name" data-other-target="ho"
input type: 'text', **stimulus_target('hello#name', 'other#ho')
# data-action="click->hello#greet"
button **stimulus_action('click->hello#greet')
# data-hello-target="output" data-other-target="letsGo"
span **stimulus_target('hello#output', 'other#letsGo')
end
endAdd this line to your application's Gemfile:
gem 'stimulux'And then execute:
$ bundle installOr install it yourself as:
$ gem install stimuluxStimulux offers a variety of helpers to generate data-* attributes for Stimulus controllers, actions, targets, and classes.
This helper generates the data-controller attribute, along with any specified data- values. You can pass multiple controller names as strings or symbols. To pass values, you can use a hash with the controller name as the key.
Simple Controller:
Stimulux.stimulus_controller('my-controller')
# => { 'data-controller' => 'my-controller' }Multiple Controllers:
Stimulux.stimulus_controller('controller-one', 'controller-two')
# => { 'data-controller' => 'controller-one controller-two' }Controller with Values:
When you need to pass values to a Stimulus controller, you can use an array where the first element is the controller's name and the second is a hash of values.
Stimulux.stimulus_controller(['my-controller', { url: '/path', count: 1 }])
# => {
# 'data-controller' => 'my-controller',
# 'data-my-controller-url-value' => '/path',
# 'data-my-controller-count-value' => 1
# }Combining Multiple Controllers and Values:
Stimulux.stimulus_controller('controller-one', ['my-controller', { url: '/path', count: 1 }])
# => {
# 'data-controller' => 'controller-one my-controller',
# 'data-my-controller-url-value' => '/path',
# 'data-my-controller-count-value' => 1
# }This helper generates the data-action attribute. You can pass multiple action strings.
Stimulux.stimulus_action('click->my-controller#action')
# => { 'data-action' => 'click->my-controller#action' }Multiple Actions:
Stimulux.stimulus_action('click->my-controller#action', 'mouseover->my-controller#anotherAction')
# => { 'data-action' => 'click->my-controller#action mouseover->my-controller#anotherAction' }This helper generates data- target attributes. The target name should be in the format controller-name#target-name.
Stimulux.stimulus_target('my-controller#my-target')
# => { 'data-my-controller-target' => 'my-target' }Multiple Targets for the same controller:
Stimulux.stimulus_target('my-controller#target-one', 'my-controller#target-two')
# => { 'data-my-controller-target' => 'target-one target-two' }Multiple Targets for different controllers:
Stimulux.stimulus_target('my-controller#target-one', 'another-controller#target-two')
# => {
# 'data-my-controller-target' => 'target-one',
# 'data-another-controller-target' => 'target-two'
# }This helper generates data- class attributes. It takes a hash where the keys are controller names and the values are hashes of class mappings.
Stimulux.stimulus_class(
'my-controller' => {
loading: 'is-loading',
loaded: 'is-loaded'
}
)
# => {
# 'data-my-controller-loading-class' => 'is-loading',
# 'data-my-controller-loaded-class' => 'is-loaded'
# }Multiple Controllers with Classes:
Stimulux.stimulus_class(
'my-controller' => {
loading: 'is-loading',
loaded: 'is-loaded'
},
'another-controller' => {
active: 'is-active'
}
)
# => {
# 'data-my-controller-loading-class' => 'is-loading',
# 'data-my-controller-loaded-class' => 'is-loaded',
# 'data-another-controller-active-class' => 'is-active'
# }This benchmark shows the performance effect on Phlex and HtmlSlice rendering 10000 divs with **stimulus_controller and **stimulus_target helpers. Note that this is a very unusual case. Most of the time we will use 1 to 10 helpers at a same time.
user system total real
raw phlex v1.11.0 0.049055 0.000000 0.049055 ( 0.049057)
phlex v1.11.0 using stimulux 0.166384 0.000839 0.167223 ( 0.167249)
raw html_slice v0.2.4 0.094993 0.001005 0.095998 ( 0.096003)
html_slice v0.2.4 using stimulux 0.216557 0.001040 0.217597 ( 0.217603)In most realistic scenarios (the test below renders div elements with Stimulux helpers 100 times), there is almost no performance difference:
user system total real
raw phlex v1.11.0 0.001983 0.000000 0.001983 ( 0.001980)
phlex v1.11.0 using stimulux 0.002300 0.000072 0.002372 ( 0.002376)
raw html_slice v0.2.4 0.002512 0.000000 0.002512 ( 0.002515)
html_slice v0.2.4 using stimulux 0.002955 0.000000 0.002955 ( 0.002956)
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec 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/henrique-ft/stimulux.
The gem is available as open source under the terms of the MIT License.