Start a section about writing Stimulus controllers for the back end

[m-vo]

No description provided.

[fritzmg]

Suggested change

	title: "Turbo-compatible Stimulus controllers"
	description: "Howto write Stimulus controllers for a Turbo application (that don't suck)"
	title: "Turbo-compatible Stimulus controllers"
	description: "How to write Stimulus controllers for a Turbo application (that don't suck)"

Not sure we should use the wording "don't suck" in the official documentation ;)

[fritzmg]

I think it would be helpful to elaborate on this a bit. i.e. describe the difference between initialize() and connect() a bit more. Because if you have data-controller="foobar" on multiple elements, initialize() will be called multiple times as well, right?

[m-vo]

Yes, it is basically:

foo = new FooController           --> foo.initialize()
<foo> element found in DOM        --> foo.connect()
<foo> element removed from DOM    --> foo.disconnect()
<foo> element readded to DOM      --> foo.connect() (on same fooInstance!)

[fritzmg]

Yes, but what happens during a turbo:render? Will initialize() be called for every new element again?

[m-vo]

initialize() is run right before the first connect on each newly found element. When an element is removed from DOM (but a reference is being kept) and then it is re-added, the same controller instance will be used. So in this case, there would be a connect() call but no initialize() call.

But as an implementer I think you should not care about this: initialize() is basically your constructor, where you can set up things for the object instance. When Turbo serves a page from cache, the instances are probably still alive, but this is an implementation detail of the cache.

[m-vo]

Here is the source code: https://github.com/hotwired/stimulus/blob/main/src/core/context.ts#L33 where you can see, that initialize() is just invoked inside the constructor().

[fritzmg]

Yeah, but that's the thing. With Turbo I cannot wrap my head around when initialize() will be called.

[m-vo]

Why would you even bother? You should not alter the DOM or anything in there, it's just boring setup like in any constructor. 🙃

[fritzmg]

I still do not understand 😁
In the realm of Turbo and Stimulus, when is this constructor called?

I know in PHP for instance that a constructor of a service will only be called once per request. But if I understand this correctly, initialize() would not behave the same way, right?

[m-vo]

A service is probably not the best analogy, because there you typically only have one instance of a kind/class, whereas in Stimulus each DOM element with a data-controller="…" property will be associated with its own instance.

Behind the scenes it kind of works like this:

• the mutation observer detects a new controller DOM element e
• look up, if e is known in the weak map for this controller type (DOM element -> controller instance)
  • if no: create a new instance (this will invoke initialize() on the newly created instance; see here) and use this
  • if yes: take the instance from the map
• invoke connect()

So if your element was removed from the DOM and readded (for example by a script reorganizing things, and calling element.remove() and parent.appendChild()), you would not need to reinitialize things - event listeners would be still intact and so on. If however the reference is lost (e.g. due to Turbo creating a snapshot with clonedElement = element.clone(true) which is later appended to the DOM), then there is no possible connection between the DOM string <div … data-controller="…"> and the instance anymore. So if nobody is holding any reference anymore it will be garbage collected. And on the Stimulus side you would also see a initialize() call on the next connect (because new instance).

But in practice I think you should never ever rely on how often or if this is happening. It is merely an optimization: reusing things where possible saves resources. So as a guideline I would say:

• Expect connect() to be called multiple times on this instance.
• If you need to setup things during connect() that are then stored to the instance or the DOM element (= that are still valid the next time this DOM element reference is "connected"), put it in initialize().

[fritzmg]

Suggested change

	<div data-controller="add-foo"></div>
	<div data-controller="add-foo"></div>

[fritzmg]

Suggested change

	<div data-controller="add-foo">
	<div data-controller="add-foo">

[fritzmg]

Suggested change

	<div data-controller="add-foo">
	<div data-controller="add-foo">

[fritzmg]

I am a bit confused here. You are saying that any cleanup in a disconnect() method has no effect, but further down in 2) you are also saying:

Cleanup CSS classes on parent elements, created sibling elements, etc.

So shouldn't it be enough to delete and created sibling elements in the disconnect() method rather than having to rely on the turbo:before-cache event?

[m-vo]

The order for a page transition with caching is beforeCache, then disconnect. So from the perspective of the snapshot the disconnect has no effect.

The disconnect is still crucial for when the DOM/parts of it get exchanged. Memory cleanup, removing parent classes etc. This will happen without beforeCache calls and even on the cached snapshot when it is displayed as a preview before the actual content has arrived.

[m-vo]

Basically: beforeCache must shape the DOM, so that a connect can run on it, disconnect must restore the DOM to its original state.

[m-vo]

Feel free to improve the text, if we can make this more clear.