Add doc examples using attach_hook for code organization instead of LiveComponents #3685
Conversation
Add small hierarchy headers to the "Compartmentalize state, markup, and events" section Use the guidance in "Functional components or live components?" at the top of `Phoenix.LiveComponent` to avoid using LiveComponents only for organization Provide longer example with a few different alternatives of what *can* be used for organizing events
As pointed out, sticking with attach_hook keeps ownership of the event in the new component
|
Ok, I think that resolves the 3 helpful comments, ty for the tips! |
|
woops, should have used that prominent "add suggestion to batch button" |
|
I know that José loves good documentation, so let's get his eyes on it as well :) |
|
This is a great contribution but it is too much detail for the welcome.md page. I think we should break this into its own guide and make the welcome page be a subtle introduction into these topics. |
Now the "using attach_hook/4 to extract handle_events" example code is actually kept in the doc FOR attach_hook This keeps the welcome.md page similar to it's original size
|
That's a fair point @josevalim! Before I had the long code example in welcome.md, and a link to that example in attach_hook/4's doc I've reversed those. Now the "attach_hook/4 to extract handle_events" example is actually kept in the doc FOR attach_hook/4 This keeps the welcome.md page similar to it's original size |
|
Option B: Do you have a preference between Option A (the most recent commit) vs B? |
|
I like this new direction! My suggestion though, instead of rocking the boat too much, is to simply mention |
So merging the "attach_hook/4 to organize event handling" section into the "Function components" one above it? I like it! |
|
Yes, let's keep the change to the welcome page minimal, basically adding a sentence or two, and then focus on adding more examples to attach_hook! |
- Merge the "attach_hook/4 to organize event handling" section into the "Function components" one above it - Return to the previous bullet-point based summary, adding only a single line to emphasize that function components can work alone for markup, but also organize event handling when paired with attach_hook/4
|
@josevalim All set! I've tried to minimize changes to welcome.md. How do we feel about this version? I do believe many of us struggled with the question of: For lack of a (known) better option, multiple tutorials and recently-published books still reach for LiveComponents to achieve that. So I wanted to at least slightly emphasize that there IS an existing method to organize event handling in another module without resorting to LiveComponents when not needing the separate state |
|
Thank you for the suggestions and fixes @josevalim! I think these examples and nudges towards And thank you again to @Gazler. Both for the awesome example code, and for showing me phoenix_playground. Love it! ❤️ Were there any other tweaks or is this PR ready to be merged? |
|
Thank you a lot! 🙌🏻 |
…iveComponents (#3685) * Update attach_hook/4 with extract handle_event example * Add small header for doc linking * Clarify the code-organization sections of the Welcome guide Add small hierarchy headers to the "Compartmentalize state, markup, and events" section Use the guidance in "Functional components or live components?" at the top of `Phoenix.LiveComponent` to avoid using LiveComponents only for organization Provide longer example with a few different alternatives of what *can* be used for organizing events * Remove suggested option to delegate events manually As pointed out, sticking with attach_hook keeps ownership of the event in the new component * Remove Helpers and use more-standard {:ok, socket} style * Add forgotten line break * Remove 2nd attach_hook example and link directly to the first * Update lib/phoenix_live_view.ex * Update guides/introduction/welcome.md * Update guides/introduction/welcome.md * Update guides/introduction/welcome.md * Update guides/introduction/welcome.md * Update guides/introduction/welcome.md * Update guides/introduction/welcome.md * Update guides/introduction/welcome.md * Reverse locations of long-code-example & link-to-that-example Now the "using attach_hook/4 to extract handle_events" example code is actually kept in the doc FOR attach_hook This keeps the welcome.md page similar to it's original size * Rename "Organizing code" section -> "Sharing event handling logic" * Continue minimizing changes to welcome.md - Merge the "attach_hook/4 to organize event handling" section into the "Function components" one above it - Return to the previous bullet-point based summary, adding only a single line to emphasize that function components can work alone for markup, but also organize event handling when paired with attach_hook/4 * Apply suggestions from code review * Apply suggestions from code review --------- Co-authored-by: Gary Rennie <[email protected]> Co-authored-by: Steffen Deusch <[email protected]> Co-authored-by: José Valim <[email protected]>
Update Welcome doc to use the guidance in "Functional components or live components?"
(near the top of
Phoenix.LiveComponent) to avoid using LiveComponentsonly for organization
Add hierarchy headers to the "Compartmentalize state, markup, and events" section
Provide some example code with a few different alternatives of what to use for
organizing handle_events other than LiveComponents
Example code adapted from @Gazler's incredibly helpful explanation in the below Issue
Resolves #3679