Documentation for complete API

I took a look at the source code and found that there might be more “features” than are visible in the current documentation on the website. I wondered if this information is omitted accidentally or willingly. For example, functions like getControllerForElementAndIdentifier on the application object which can be quite handy if one knows that it exists.

Any plans to extend the documentation for a full reference of all available functions?

Also, side-note, it would be nice if the functions featured JSDoc comments so that the reference for IDEs and code editors supporting JSDoc can show this additional information. Or at least the generated d.ts files would already be an improvement.

[leastbad]

Hey gang, it’s true that there’s a lot of “missing manual” around Stimulus.

The best way to learn advanced Stimulus techniques IMHO is to read the source of projects like stimulus-use and StimulusReflex. The SR client is likely the most sophisticated Stimulus controller, today.

@julianrubisch has done a heroic job of compiling a lot of the missing concepts on https://betterstimulus.com (as linked by @lordcysiek above) but there’s always more and we’re still discovering new patterns all of the time.

New patterns is my segue to the issue of controller-to-controller communication! When I proposed the this.element['foo'] = this binding technique, I didn’t intend that it was for controllers that are connected to the same DOM element, at all.

You can talk across this.element, but the goal is to access controllers on elements elsewhere in the DOM that you have a reference to, usually via id query. You might have a <div id="content" data-controller="content"></div> that is conceptually important in your application; you also have components anywhere on the page that need to access the internal state of the content controller instance. This is an intentional set of design decisions which allow you to build-up functionality.

Raising and listening for custom events should be the first tool you reach for when you need to communicate between Stimulus controllers. One of the “missing manual” concepts is how most of what people put in their connect should actually be in initialize, leaving connect and disconnect almost exclusively to set up addEventListener/removeEventListener pairs.

However, event dispatch is passive and asyncronous; you’re working in callbacks. There are times where you need to reach into a controller and access its internal state - whether to inspect a variable or execute a method - from your current scope right now… and that’s what hanging this on a variable on an element is for.

[dhh]

Feel free to turn any of these discussions into doc PRs for consideration.