How do I trigger a Stimulus controller function from a Turbo Stream in Rails?

Below is an explanation of what you’re aiming for and an approach you could use.

---

What You’re Trying to Do

You're aiming to use Turbo Streams to push data from the server to the client and, rather than just updating the DOM via a Turbo action (for example, using broadcast_append_to), you want to intercept that data in a Stimulus controller so you can hand it off to a custom JavaScript function (e.g., processData). In other words, you want server-pushed data to trigger your own client-side behavior instead of—or in addition to—a DOM update.

Since Turbo Streams are designed primarily for DOM updates, your challenge is to bridge that gap and run a custom JavaScript function when data is received.

---

How to Approach This

Turbo Streams work by updating the DOM when they arrive. To call a Stimulus controller method (or custom JavaScript) with streamed data, you can embed a custom event or inline script in your Turbo Stream template. The idea is to have that event caught by your Stimulus controller, which then calls your function (processData) with the data payload received from the server.

You might consider these two techniques:

1. Using Custom Turbo Stream Actions or Embedded Scripts:
   Instead of (or in addition to) a standard broadcast_append_to, render your Turbo Stream as a partial that includes a small inline <script> block. That script can dispatch a custom event with the data payload.

2. Using Mutation Observers or Event Listeners within Stimulus:
   Have your Stimulus controller listen for custom events on the page (or even observe certain DOM changes) and, when triggered, process the incoming data.

---

Example Implementation

Assume you’ve decided to use a custom event dispatched from your Turbo Stream template. Here’s one way to implement that:

Turbo Stream Partial (ERB)

Create a partial that renders the Turbo Stream along with the embedded script.

ERBCopied
<turbo-stream action="append" target="messages">
  <template>
    <!-- Optionally update the DOM as needed -->
    <div class="message"><%= message.content %></div>

    <!-- Dispatch a custom event with the data -->
    <script>
      const event = new CustomEvent('message:received', {
        detail: { data: "<%= j message.content %>" }
      });
      window.dispatchEvent(event);
    </script>
  </template>
</turbo-stream>

Here each streamed message both updates the DOM and dispatches a custom event (message:received) with the details you need.

Stimulus Controller (JavaScript)

Have your Stimulus controller listen for this event and then call your custom function:

JAVASCRIPTCopied
import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  static targets = [ "messages" ]

  connect() {
    window.addEventListener('message:received', this.handleMessage.bind(this))
  }

  disconnect() {
    window.removeEventListener('message:received', this.handleMessage.bind(this))
  }

  handleMessage(event) {
    const data = event.detail.data
    console.log('Received data:', data)
    // Call your custom processing function here:
    this.processData(data)
  }

  processData(data) {
    // Your logic goes here
    console.log('Processing data:', data)
    // For example, parsing JSON, updating a chart, etc.
  }
}

In this approach:

• The Turbo Stream partial dispatches a message:received event when it is rendered.
• Your Stimulus controller listens for that event and calls processData(data) with the streamed data.

---

Summary

What you’re trying to do is to have server-pushed data delivered via Turbo Streams trigger a Stimulus controller method that calls your custom JavaScript function. While Turbo Streams are built for DOM updates by default, you can augment that behavior by using custom events (or inline scripts) within your Turbo Stream payload. This pattern lets you decouple the DOM update (if needed) from additional custom processing logic on the client, all without requiring any user interaction.

Remember that this approach leverages Turbo’s push mechanism while using Stimulus to control client-side behavior, maintaining a separation between server-rendered content and client-side JavaScript processing.