Add doc for URL binding feature #1346

squrious · 2023-12-20T10:35:21Z

Q	A
Bug fix?	no
New feature?	no
Issues	NA
License	MIT

Add documentation for #1230

kbond

Looks good! Here's a couple questions I had after reading the doc:

Is the browser's history updated?
What happens if multiple components on the same page use this feature? Should this be avoided?

squrious · 2023-12-21T11:56:54Z

Is the browser's history updated?

No, the current behavior is to update the URL in place. There could be a feature to push new history entries in the future.

What happens if multiple components on the same page use this feature? Should this be avoided?

If multiple components use this feature on the same page, things should work fine as long as they don't use the same field names. Otherwise parameters will collide, so the last rendered component will take priority on URL parameters, overriding ones set by the other components.

Should this be part of the documentation too?

kbond · 2023-12-21T13:17:13Z

Should this be part of the documentation too?

Maybe just a warning

smnandre · 2023-12-21T23:41:30Z

src/LiveComponent/doc/index.rst

+
+.. note::
+
+    Type consistency is enforced by the LiveComponent internal hydrator when the component is initialized with query


Type consistency is enforced by the LiveComponent internal hydrator. When the component is initialized, If a query parameter could not be hydrated properly into a LiveProp, it will be ignored to avoid unfriendly errors for the end user.

Just a suggestion.. feel free to ignore if you prefer the original ;)

I prefer the original, I find it more accurate as this type consistency check is only used on component initialization. But thanks for the suggestion :)

I think we should make this not in a note, rather a normal sentence, as it's really important. And, from a user's point of view, the important thing is that it goes through the hydration system. Something like:

When a page is loaded with a query parameter that's bound to a LiveProp (e.g. /search?query=my+search+string), the value - my search string - goes through the hydration system before it's set onto the property. If a value can't be hydrated, it will be ignored.

src/LiveComponent/doc/index.rst

smnandre · 2023-12-21T23:44:08Z

src/LiveComponent/doc/index.rst

+Validation
+~~~~~~~~~~
+
+To validate your component state when it is rendered for the first time, you have to setup a `PostMount hook`_::


I'd use a warning or caution block there.. wdyt ?

I added a caution block at the top of the section

setup -> set up

weaverryan

Thank you for this! What a great way to start 2024, being reminded that we can to release this feature soon.

weaverryan · 2024-01-09T14:30:50Z

src/LiveComponent/doc/index.rst

+
+.. versionadded:: 2.13
+
+    The ``url`` option was introduced in Live Components 2.13.


weaverryan · 2024-01-09T14:31:27Z

src/LiveComponent/doc/index.rst

@@ -2302,6 +2302,131 @@ You can also trigger a specific "action" instead of a normal re-render:
        #}
    >

+Binding LiveProp to URL query parameters


How about:

Changing the URL when a LiveProp changes

weaverryan · 2024-01-09T14:33:30Z

src/LiveComponent/doc/index.rst

+
+    The ``url`` option was introduced in Live Components 2.13.
+
+You can bind your component LiveProp's values to URL query parameters thanks to the ``url`` option::


How about:

If you want the URL to update when a LiveProp changes, you can do that with the url option:

weaverryan · 2024-01-09T14:33:51Z

src/LiveComponent/doc/index.rst

+
+You can bind your component LiveProp's values to URL query parameters thanks to the ``url`` option::
+
+    // src/Components/SearchModule.php


// src/Twig/Components/SearchModule.php

right?

Other examples in the doc live in src/Components, not sure why this one should be different?

weaverryan · 2024-01-09T14:34:17Z

src/LiveComponent/doc/index.rst

+        public string $query = '';
+    }
+
+Now if you change the value of the ``query`` prop, the url will be updated to reflect the new state of your


Now, when the user changes the...

... prop, a query parameter in the URL will be updated...

weaverryan · 2024-01-09T14:41:27Z

src/LiveComponent/doc/index.rst

+    parameters. If a value could not be hydrated properly, it will be ignored to avoid unfriendly errors for the end
+    user.
+
+Multiple bindings


Suggested change

Multiple bindings

Multiple Query Parameter Bindings

weaverryan · 2024-01-09T14:42:32Z

src/LiveComponent/doc/index.rst

+
+And you only set the ``query`` value, then your URL will be updated to ``https://my.domain/search?query=my+query+string&mode=fulltext``.
+
+Validation


Suggested change

Validation

Validating the Query Parameter Values

weaverryan · 2024-01-09T14:43:05Z

src/LiveComponent/doc/index.rst

+Validation
+~~~~~~~~~~
+
+To validate your component state when it is rendered for the first time, you have to setup a `PostMount hook`_::


setup -> set up

weaverryan · 2024-01-09T14:44:11Z

src/LiveComponent/doc/index.rst

+        public function postMount(): void
+        {
+            // Validate 'mode' field without throwing an exception
+            $this->validateField('mode', false);


It's not clear to me what happens when this fails.

weaverryan · 2024-01-09T14:47:06Z

src/LiveComponent/doc/index.rst

+.. caution::
+
+    It is recommended to validate data provided through query string parameters, so you can prevent malicious inputs
+    from being processed and rendered.


This is interesting. If a LiveProp is writable, then the fact that it is bound to a query parameter does not open a new malicious entrypoint: the value can always be changed to "anything". Two things:

A) If we want to talk about validating writable properties in general more clearly, then we can talk about that in another PR
B) This section may still make sense, but I think it's only important for the (probably rare) situation where you have url: true and writable: false (e.g. when the user calls a LiveAction, you change the prop inside that method, but the user doesn't change it directly).

The goal of this section was to be explicit about the fact that bound props are not validated when initialized from the URL, even if the component uses validation. But yes, the security concern only applies when the validation logic itself involves some security process (sanitizing or whatever). Maybe I can change the caution block to a note like:

If your component uses validation, it is recommended to also validate data provided through query string parameters.

For the B) part, I could add another example in this section to illustrate this use case, wdyt?

Hmm, ok, yes, it's more clear to me. So the messaging would be something like:

Like any writable LiveProp, because the user can modify this value, you should consider adding validation (<-- link to that section). When you bind a LiveProp to the URL, the initial value is not automatically validated. To validate it: (then the code).

Also, it's beyond the scope of the doc, but should the URL-binding feature validate automatically? And reject the value (skip it) if it's invalid?

weaverryan · 2024-01-17T15:39:09Z

Thank you @squrious!

squrious force-pushed the live-component/docs-url-binding branch 2 times, most recently from c600ad6 to 0adbb66 Compare December 20, 2023 10:39

kbond reviewed Dec 20, 2023

View reviewed changes

smnandre reviewed Dec 21, 2023

View reviewed changes

weaverryan reviewed Jan 9, 2024

View reviewed changes

Add doc for URL binding feature

4f0d313

weaverryan force-pushed the live-component/docs-url-binding branch from 7a740f6 to 4f0d313 Compare January 17, 2024 15:39

weaverryan merged commit d0c201d into symfony:2.x Jan 17, 2024
6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add doc for URL binding feature #1346

Add doc for URL binding feature #1346

squrious commented Dec 20, 2023

kbond left a comment

squrious commented Dec 21, 2023

kbond commented Dec 21, 2023

smnandre Dec 21, 2023

squrious Dec 22, 2023

weaverryan Jan 9, 2024

smnandre Dec 21, 2023

squrious Dec 22, 2023

weaverryan Jan 9, 2024

weaverryan left a comment

weaverryan Jan 9, 2024

weaverryan Jan 9, 2024

weaverryan Jan 9, 2024

weaverryan Jan 9, 2024

squrious Jan 12, 2024

weaverryan Jan 9, 2024

weaverryan Jan 9, 2024

weaverryan Jan 9, 2024

weaverryan Jan 9, 2024

weaverryan Jan 9, 2024

weaverryan Jan 9, 2024

squrious Jan 10, 2024

weaverryan Jan 10, 2024

weaverryan commented Jan 17, 2024


		.. note::

		Type consistency is enforced by the LiveComponent internal hydrator when the component is initialized with query


		.. versionadded:: 2.13

		The ``url`` option was introduced in Live Components 2.13.


		The ``url`` option was introduced in Live Components 2.13.

		You can bind your component LiveProp's values to URL query parameters thanks to the ``url`` option::


		You can bind your component LiveProp's values to URL query parameters thanks to the ``url`` option::

		// src/Components/SearchModule.php


		And you only set the ``query`` value, then your URL will be updated to ``https://my.domain/search?query=my+query+string&mode=fulltext``.

		Validation

Add doc for URL binding feature #1346

Add doc for URL binding feature #1346

Conversation

squrious commented Dec 20, 2023

kbond left a comment

Choose a reason for hiding this comment

squrious commented Dec 21, 2023

kbond commented Dec 21, 2023

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

weaverryan 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

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

weaverryan commented Jan 17, 2024