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.
StimulusReflex leverages Rails ActionCable. Understanding what Rails provides out of the box will help you get the most value from this library.
Regardless of whether you use declarative Reflex calls via
stimulate method on your Stimulus controller is being called. We touched on this briefly in the Quick Start chapter; now we are going to document the function signature so that you fully understand what's happening behind the scenes.
All Stimulus controllers that have had
StimulusReflex.register(this) called in their
connect method gain a
this.stimulate(string target, [DOMElement element], [JSONObject argument])
target, required: a string containing the server Reflex class and method, in the form "ExampleReflex#increment".
element, optional: a reference to a DOM element which will provide both attributes and scoping selectors. Frequently pointed to
StimulusReflex makes the following properties available to the developer in the Reflex methods.
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 property contains all of the Stimulus controller's DOM element attributes as well as other properties like
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" checkeddata-reflex="ExampleReflex#work" data-value="123" />
app/reflexes/example_reflex.rbclass ExampleReflex < StimulusReflex::Reflexdef work()element[:id] # => the HTML element's id attribute valueelement.dataset # => a Hash that represents the HTML element's datasetelement[:id] # => "example"element[:checked] # => trueelement[:label] # => "Example"element["data-reflex"] # => "ExampleReflex#work"element.dataset[:reflex] # => "ExampleReflex#work"element["data-value"] # => "123"element.dataset[:value] # => "123"endend
One Rails mechanism that you might use less in a StimulusReflex application is the flash message object. Flash made a lot more sense in the era of submitting a CRUD form and seeing the result confirmed on the next page load. With StimulusReflex, the current state of the UI might be updated dozens of times in rapid succession and the flash message could be easily lost before it's read.
You'll want to experiment with other, more contemporary feedback mechanisms to provide field validations and event notification functionality. An example would be the Facebook notification widget, or a dedicated notification drop-down that is part of your site navigation.
You can also look into using client-side StimulusReflex callbacks along with the
data-reflex-permanent attribute for a solution reminiscent of the classic flash message format.