> For the complete documentation index, see [llms.txt](https://andrewmcodes.gitbook.io/test/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://andrewmcodes.gitbook.io/test/advanced-use.md).

# Advanced Use

[![GitHub stars](https://img.shields.io/github/stars/hopsoft/stimulus_reflex?style=social)](https://github.com/hopsoft/stimulus_reflex) [![GitHub forks](https://img.shields.io/github/forks/hopsoft/stimulus_reflex?style=social)](https://github.com/hopsoft/stimulus_reflex) [![Twitter follow](https://img.shields.io/twitter/follow/hopsoft?style=social)](https://twitter.com/hopsoft)

## ActionCable

StimulusReflex leverages [Rails ActionCable](https://guides.rubyonrails.org/action_cable_overview.html). Understanding what Rails provides out of the box will help you get the most value from this library.

{% hint style="info" %}
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.**
{% endhint %}

### Performance

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

{% code title="config/initializers/action\_cable.rb" %}

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

{% endcode %}

### 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`.

{% code title="app/javascript/controllers/example\_controller.js" %}

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

{% endcode %}

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

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

{% hint style="danger" %}
**Setting room in the body with a data attribute can pose a security risk.** Consider assigning room when registering the Stimulus controller instead.
{% endhint %}

## 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.

{% code title="app/javascript/controllers/example\_controller.js" %}

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

{% endcode %}

{% hint style="info" %}
`renderDelay` defaults to`25`milliseconds.
{% endhint %}

## 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](https://developer.mozilla.org/en-US/docs/Web/API/Element/attributes) as well as other properties like `checked` and `value`.

{% hint style="info" %}
**Most values are strings.** The only exceptions are `checked` and `selected` which are booleans.
{% endhint %}

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

{% code title="app/views/examples/show\.html.erb" %}

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

{% endcode %}

{% code title="app/reflexes/example\_reflex.rb" %}

```ruby
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
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://andrewmcodes.gitbook.io/test/advanced-use.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.