Creating an Action

In Stimulus, an action is what connects a DOM event to the controller code that you want executed when that event happens. Like controllers, Stimulus actions are defined using a data attribute in the markup: you add the attribute to the DOM element whose events you want to watch. In our case, we want to add a button that says “Hide”:

chapter_03/02/app/views/favorites/_list.html.erb
​ <div class=​"text-3xl font-bold"​>
​  Favorite Concerts
​  <button class=​"​​<%=​ SimpleForm.​button_class​ ​%>​​ py-1 text-xl font-semibold"​
​  data-action=​"click->favorite-toggle#toggle"​>
​  Hide
​  </button>
​ </div>

The new line defining the actions is data-action="click->favorite-toggle#toggle". The data-action is the attribute name that signals to Stimulus that an action is being defined. The value of the data-action attribute is a mini-language to define the connection between the event and the code.

The mini-language, which Stimulus calls an action descriptor, has three parts:

  • The first element is the name of the event being watched for, which in our case is click, followed by an arrow (->).

  • The second element is the name of the controller, spelled exactly the way the name is spelled where the controller is defined, meaning that it’s dash-case. For us, that’s favorite-toggle. This element ends with a hashtag (#).

  • The last element is the name of the method to be called on the controller when the event happens. This needs to be the exact name of the method, which usually means it’s in camelCase. (I’m not sure why Stimulus chooses not to translate from dash-case to camelCase here). Our method name is toggle.

This is a three-part sentence of action, controller, and method. When Stimulus sees a data-action attribute, it sets up a listener on the event, which executes the named method on the controller when the event fires. If there are multiple instances of controllers with that name, the instance representing the closest ancestor to the element triggering the event is the instance that executes the method.

Default Events

images/aside-icons/info.png

I don’t recommend it, but Stimulus allows you to leave off the event name for the “default” event of specific elements. If your element is a, button, or input[type="submit"], then the default action is click, and you can respond to a click event with just the controller name and method, as in "day-toggle#toggle". If the element is any other kind of input, a select, or a textarea, then the default event is change, and for a form, the default event is submit. I find the consistency of keeping the event around to be worth the extra typing, however.

Having created an action descriptor that references a toggle method, we need to write a corresponding toggle method in our controller:

chapter_03/02/app/packs/controllers/favorite_toggle_controller.ts
​ ​import​ { Controller } ​from​ ​"stimulus"​
​ 
​ ​export​ ​default​ ​class​ FavoriteToggleController ​extends​ Controller {
​  toggle(): ​void​ {
​  console.log(​"Click!"​)
​  }
​ }

Here we removed the connect method and replaced it with a toggle that similarly writes to the console. Now if you reload the page, clicking the new Hide button for favorites will cause the output to be written to the console. This is nice but isn’t quite what we’re hoping for. What we need is a way to identify the DOM element we want to hide. We can use DOM IDs for that, but Stimulus gives us a shortcut: targets.

Stimulus Action Names

Before we get to targets, there are a couple more useful facts about Stimulus actions. First, the event name in the action descriptor can be anything you want, including custom events. Custom events can be a useful way to communicate between controllers. You can also capture global events on the window or document by adding @window or @document, as in ready@document. Typically you’d add these global descriptors to the same DOM element that the controller is defined in.

Second, as with controllers, you can define multiple actions on the same DOM element by adding multiple event descriptors to the same attribute, separated by spaces. This is quite common and is a great way to split up behavior into small controllers and small methods. One nice feature is that if you have multiple responses to the same event, Stimulus guarantees the controller methods will be invoked in the same order the action descriptors are displayed, which allows you to rely on the behavior of the first method already having taken place when you call the second method.

We don’t show it in our toggle method, but Stimulus does pass one argument to the methods it calls. For TypeScript purposes, this argument is of type CustomEvent, and it allows you access to the target, which is the element that actually hosted the event, and the currentTarget, which is the element that contains the data-action attribute. The two might differ if, say, the click actually happened on an element nested within the element with the data-action. You also have access to normal DOM event methods, such as preventDefault() and stopPropagation().

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.15.171.202