Documentation for Outlets API #604

marcoroth · 2022-11-18T17:44:50Z

This Pull request adds documentation for the Outlets API which was introduced in #576.

It also updates the order for the other sections in the reference.

Feedback very welcome, especially on the used examples.

Spone · 2022-11-18T19:00:44Z

docs/reference/outlets.md

+
+## Attributes and Names
+
+The `data-search-result-outlet` attribute is called an _outlet attribute_, and its value is a [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) which you can use to refer to other controller elements which should be available as outlets on the _host controller_.


The host controller designation may be introduced a bit sooner to help understanding this. Maybe on line 8?

I know the terminology may already be decided upon but could we call this source controller instead of host controller?

So it's source/outlet not host/outlet?

Yeah agreed. I wasn't too happy with the term "host controller". It's not decided yet, that's just what I had in there as a placeholder. Happy to change it whatever makes to most sense. source seems better fitting to me

lb-

Some general comments below but what happens if you have an outlet that has two or more Controllers on it?

Maybe I missed something but does the name of the outlet have to match the name of the expected outlet controller?

lb- · 2022-11-18T21:59:16Z

docs/reference/outlets.md

+
+## Attributes and Names
+
+The `data-search-result-outlet` attribute is called an _outlet attribute_, and its value is a [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) which you can use to refer to other controller elements which should be available as outlets on the _host controller_.


I know the terminology may already be decided upon but could we call this source controller instead of host controller?

So it's source/outlet not host/outlet?

docs/reference/outlets.md

lb- · 2022-11-18T22:08:28Z

docs/reference/outlets.md

+
+Outlet callbacks are specially named functions called by Stimulus to let you respond to whenever an outlet is added or removed from the page.
+
+To observe outlet changes, define a function named `[name]OutletConnected()` or `[name]OutletDisconnected()`.


Suggested change

To observe outlet changes, define a function named `[name]OutletConnected()` or `[name]OutletDisconnected()`.

To observe outlet changes, define a class method named `[name]OutletConnected()` or `[name]OutletDisconnected()`.

Not sure if needed but it may be clearer if we say that this is a class method?

you are right, in the targets section they are also called "methods" 👍🏼

docs/reference/outlets.md

lb- · 2022-11-18T22:11:24Z

docs/reference/outlets.md

+
+### Referencing non-controller elements
+
+Stimulus will throw an exception if you try to declare an element as an outlet which doesn't have the corresponding `data-controller` and identifier on it:


When will this error be thrown?

Once the controller is instantiated? Or when you attempt to access the outlet?

Might be good to be clear here - for some cases the data controller attribute could be added later maybe.

It's throwing the error when you attempt to access the outlet, similar to how targets handle this. I'll try to make this clearer, thanks!

docs/reference/outlets.md

Co-authored-by: LB (Ben Johnston) <[email protected]>

marcoroth · 2022-11-18T22:42:10Z

Thanks for the review!

Some general comments below but what happens if you have an outlet that has two or more Controllers on it?

An element with two controllers attached to it also has two different controllers instances. You'll get the controller instance for the controller identifier you referenced as the outlet.

Maybe I missed something but does the name of the outlet have to match the name of the expected outlet controller?

Yes, the outlet name has to match the controller identifier. This is what's used to get right controller instance for a given element.
The reason why you are able to provide a CSS selector is that you can specify which element/instance you want to associate with the source controller, because usually there are more than one instance of the same controller on the page.

lb- · 2022-11-19T00:13:39Z

Thanks @marcoroth it makes sense that the outlet name must match the controller identifier. I must have missed that or maybe we can make it clearer.

lb- · 2022-11-19T00:15:54Z

docs/reference/outlets.md

+
+## Definitions
+
+Define controller identifiers in your controller class using the `static outlets` array. This array declares which other controller identifiers can be used as outlets on this controller:


Suggested change

Define controller identifiers in your controller class using the `static outlets` array. This array declares which other controller identifiers can be used as outlets on this controller:

Define controller identifiers in your controller class using the `static outlets` array. This array declares which other Controller identifiers can be used as outlets on this controller:

I see we say identifiers here. Just another nitpicky fix for proper noun usage of Controller

Documentation for Outlets API

4a835e5

marcoroth mentioned this pull request Nov 18, 2022

Outlets API #576

Merged

Spone reviewed Nov 18, 2022

View reviewed changes

lb- reviewed Nov 18, 2022

View reviewed changes

Apply suggestions from code review

6356be8

Co-authored-by: LB (Ben Johnston) <[email protected]>

lb- reviewed Nov 19, 2022

View reviewed changes

dhh merged commit 273f5a7 into hotwired:main Nov 21, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation for Outlets API #604

Documentation for Outlets API #604

marcoroth commented Nov 18, 2022

Spone Nov 18, 2022

lb- Nov 18, 2022

marcoroth Nov 18, 2022

lb- left a comment

lb- Nov 18, 2022

lb- Nov 18, 2022

marcoroth Nov 18, 2022

lb- Nov 18, 2022

marcoroth Nov 18, 2022

lb- Nov 19, 2022

marcoroth commented Nov 18, 2022

lb- commented Nov 19, 2022

lb- Nov 19, 2022


		## Attributes and Names

		The `data-search-result-outlet` attribute is called an _outlet attribute_, and its value is a [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) which you can use to refer to other controller elements which should be available as outlets on the _host controller_.


		Outlet callbacks are specially named functions called by Stimulus to let you respond to whenever an outlet is added or removed from the page.

		To observe outlet changes, define a function named `[name]OutletConnected()` or `[name]OutletDisconnected()`.

	To observe outlet changes, define a function named `[name]OutletConnected()` or `[name]OutletDisconnected()`.
	To observe outlet changes, define a class method named `[name]OutletConnected()` or `[name]OutletDisconnected()`.


		### Referencing non-controller elements

		Stimulus will throw an exception if you try to declare an element as an outlet which doesn't have the corresponding `data-controller` and identifier on it:


		## Definitions

		Define controller identifiers in your controller class using the `static outlets` array. This array declares which other controller identifiers can be used as outlets on this controller:

Documentation for Outlets API #604

Documentation for Outlets API #604

Conversation

marcoroth commented Nov 18, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lb- left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcoroth commented Nov 18, 2022

lb- commented Nov 19, 2022

Choose a reason for hiding this comment