Regardless of whether you use declared Reflexes in your HTML markup or call stimulate() directly from inside of a Stimulus controller, StimulusReflex maps your requests to Reflex classes on the server. These classes are found in app/reflexes and they inherit from ApplicationReflex.

app/reflexes/example_reflex.rb
class ExampleReflex < ApplicationReflex
end

Setting a declarative data-reflex="click->Example#test" will call the test method in the Example Reflex class. We refer to Reflex class methods which get called from the client as "Reflex Action methods".

You can do anything you like in a Reflex action, including retrieving data from Redis, ActiveRecord database updates, launching ActiveJobs and even initiating CableReady broadcasts.

You can get and set values on the session object, and if you're using the (default) Page Morph Reflexes, any instance variables that you set in your Reflex Action method will be available to the controller action before your page is re-rendered.

app/reflexes/example_reflex.rb
class ExampleReflex < ApplicationReflex
  def test
    @id = element.dataset["id"] # @id will be available inside your controller action if you're doing a Page Morph
  end
end

You will learn all about the element accessor in the next section.

ActionCable Connection Identifiers

It's very common to want to be able to access the current_user or equivalent accessor inside your Reflex actions. First, you'll need to make sure that your Connection is "identified" by your current_user. Since ActionCable is separate from the ActionController namespace, accessors need to be setup as part of your authentication process.

Your Connection can have multiple accessors defined. For example, it's common to implement a hybrid technique to use the visitor's session_id before they authenticate, and then switch over to current_user.

Once your connection is identified_by :current_user, you can delegate current_user to your ActionCable Connection:

app/reflexes/example_reflex.rb
class ExampleReflex < ApplicationReflex
  delegate :current_user, to: :connection
​
  def increment
    current_user.counter.increment!
  end
end

If you plan to access current_user from all of your Reflex classes, delegate it your ApplicationReflex:

app/reflexes/application_reflex.rb
class ApplicationReflex < StimulusReflex::Reflex
  delegate :current_user, to: :connection
end

Queries and associations are cached

When using identified_by accessors such as current_user, it's important to remember that any ActiveRecord queries or associations you access will be cached by default, even across multiple Reflexes.

The cache is cleared when the ActionCable Connection is re-established (usually with a page refresh) or you manually force the accessor to reload its associations:

current_user.reload

You can also bust the cached value by running a different query, but Rails developers are used to thinking in terms of request/response cycles. They know controller actions are idempotent, and so it's reasonable to expect Reflex actions to also be idempotent. And they are... except for accessors on the Connection.

If you are expecting your data to change and it doesn't, you can lose an afternoon to debugging.

Likewise, if you keep this potential gotcha in the back of your mind, it's entirely fair to see this association caching behavior as a performance boost. After all, it's one less query to run! 😅

Building your Reflex action

The following properties available to the developer inside Reflex actions:

• 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

• flash - the ActionDispatch::Flash::FlashHash for the current request

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

• params - an ActionController::Parameters of the closest form

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

• reflex_id - a UUIDv4 that uniquely identies each Reflex

element

The element property contains all of the Stimulus controller's DOM element attributes as well as other properties like tagName, checked and value. In addition, values and the dataset property reference special collections as described below.

Here's an example that outlines how you can interact with the element property and the dataset collection in your Reflex action. You can use the dot notation as well as string and symbol accessors.

app/views/examples/show.html.erb
<input type="checkbox" id="example" label="Example" checked
  data-reflex="change->Example#accessors" data-value="123" />

app/reflexes/example_reflex.rb
class ExampleReflex < ApplicationReflex
  def accessors
​
    element.id                  # => "example"
    element[:id]                # => "example"
    element["id"]               # => "example"
    
    element.value               # => "on" (checkbox is always "on", use checked)
    element.values              # => nil, or Array for multiple values
​
    element[:tag_name]          # => "CHECKBOX"
    element[:checked]           # => true
    element["checked"]          # => true
    element.checked             # => true
    element.label               # => "Example"
​
    element.data_reflex         # => "change->Example#accessors"
    element["data-reflex"]      # => "change->Example#accessors"
    element.dataset[:reflex]    # => "change->Example#accessors"
    element.dataset["reflex"]   # => "change->Example#accessors"
​
    element.dataset.value       # => "123"
    element.data_value          # => "123"
    element["data-value"]       # => "123"
    element.dataset[:value]     # => "123"
    element.dataset["value"]    # => "123"
​
  end
end

Signed and unsigned Global ID accessors

Rails has a pair of cool features that allow developers to generate tokens from ActiveRecord models. These tokens can later be used to access those models, and in the case of signed Global IDs, obscure the model from prying eyes. They can even be set to expire after a period of time.

The element accessor on every Reflex has two dynamic accessors, signed and unsigned which automatically unpack Global IDs stored in data attributes and converts them to model instances.

<div data-reflex="click->Example#foo"
     data-public="<%= @foo.to_global_id.to_s %>"
     data-secure="<%= @foo.to_sgid.to_s %>"
>

While in reality, you'd never use both on the same object, you can now have StimulusReflex automatically convert these attributes into instances of the models they reference. This happens lazily, at the time you access the accessor:

class ExampleReflex < ApplicationReflex
  def foo
    puts element.unsigned[:public] # returns Foo model instance
    puts element.signed[:secure] # returns Foo model instance
  end
end

While most developers default to using signed Global IDs, understand that the tradeoff is that signed tokens can be quite long, whereas unsigned tokens remain short.

Reflex exceptions are rescuable

If you'd like to wire up 3rd-party exception handling services like Sentry or HoneyBadger to your Reflex classes, you can use rescue_from to respond to an errors raised.

class MyTestReflex < ApplicationReflex
  rescue_from StandardError do |exception|
    ExceptionTrackingService.error(exception)
  end
  # ...
end

Accessing reflex_id

Every Reflex starts as a client-side data structure that is assigned a unique UUIDv4 used to track it through its round-trip life-cycle. Most developers using StimulusReflex never have to think about these details. However, if you're building an application that is based on transactional concepts, it might be very useful to be able to track interactions based on the reflex_id.

class ExampleReflex < ApplicationReflex
  def foo
    puts reflex_id
  end
end