Advanced Use

How to get the most out of StimulusReflex

ActionCable

StimulusReflex leverages Rails ActionCable. Understanding what Rails provides out of the box will help you get the most value from this library.

The ActionCable defaults of window.App and App.cable are used if they exist. A new socket connection will be established if these do not exist.

Performance

ActionCable emits verbose log messages. Disabling ActionCable logs may improve performance.

config/initializers/action_cable.rb

ActionCable.server.config.logger = Logger.new(nil)

Rooms

You might find the need to restrict communication to a specific room. This can be accomplished in 2 ways.

1. Passing the room name as an option to register.

app/javascript/controllers/example_controller.js

export default class extends Controller {
  connect() {
    StimulusReflex.register(this, { room: 'ExampleRoom12345' });
  }
}

1. Setting the data-room attribute on the StimulusController element.

<a href="#"
   data-controller="example"
   data-reflex="click->ExampleReflex#do_stuff"
   data-room="12345">

Setting room in the body with a data attribute can pose a security risk. Consider assigning room when registering the Stimulus controller instead.

Stimulus Controllers

Render Delay

An attempt is made to reduce repaint jitter when users trigger several updates in succession.

You can control how long to wait prior to updating the DOM - think debounce. Simply set the renderDelay option in milliseconds when registering the controller.

app/javascript/controllers/example_controller.js

export default class extends Controller {
  connect() {
    StimulusReflex.register(this, { renderDelay: 200 });
  }
}

renderDelay defaults to25milliseconds.

Reflexes

Server side reflexes inherit from StimulusReflex::Reflex and hold logic responsible for performing operations like writing to your backend data stores. Reflexes are not concerned with rendering because rendering is delegated to the Rails controller and action that originally rendered the page.

Properties

• connection - the ActionCable connection

• channel - the ActionCable channel

• request - an ActionDispatch::Request proxy for the socket connection

• session - the ActionDispatch::Session store for the current visitor

• url - the URL of the page that triggered the reflex

• element - a Hash like object that represents the HTML element that triggered the reflex

element

The element property contains all of the Stimulus controller's DOM element attributes as well as other properties like checked and value.

Most values are strings. The only exceptions are checked and selected which are booleans.

Here's an example that outlines how you can interact with the element property in your reflexes.

app/views/examples/show.html.erb

<checkbox id="example" label="Example" checked
  data-reflex="ExampleReflex#work" data-value="123" />

app/reflexes/example_reflex.rb

class ExampleReflex < StimulusReflex::Reflex
  def work()
    element[:id]    # => the HTML element's id attribute value
    element.dataset # => a Hash that represents the HTML element's dataset

    element[:id]                 # => "example"
    element[:checked]            # => true
    element[:label]              # => "Example"
    element["data-reflex"]       # => "ExampleReflex#work"
    element.dataset[:reflex]     # => "ExampleReflex#work"
    element["data-value"]        # => "123"
    element.dataset[:value]      # => "123"
  end
end