New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[LiveComponent] Document how to use `extra_options` in the Ajax-powered autocomplete #1702

Open

jakubtobiasz wants to merge 1 commit into symfony:2.x from jakubtobiasz:autocomplete_extra_options_docs

Contributor

jakubtobiasz commented Apr 9, 2024 •

edited

Q	A
Bug fix?	no
New feature?	n/a
Issues	requested in #1322 (comment)
License	MIT

Time spent on this PR has been sponsored by Commerce Weavers ♥️.

carsonbot added the Status: Needs Review label


          [LiveComponent] Document how to use extra_options in the Ajax-power…

f57c765

…ed autocomplete

jakubtobiasz force-pushed the autocomplete_extra_options_docs branch from a06528b to f57c765 Compare

April 9, 2024 07:43

Collaborator

smnandre commented Apr 9, 2024

Thanks @jakubtobiasz ! I'll make some minor comments / suggestions tonight, but this is very welcome !

Contributor Author

jakubtobiasz commented Apr 9, 2024

@smnandre I believe there're might be some places to be improved, as I'm not the best to write docs, especially if most of them have some kind of standarization :D. So I'm open for any comments 🙌🏻.

smnandre reviewed

View reviewed changes

src/Autocomplete/doc/index.rst

		@@ -171,6 +171,109 @@ After creating this class, use it in your form:

		Congratulations! Your ``EntityType`` is now Ajax-powered!

Collaborator

smnandre Apr 9, 2024

Just before there is a caution block concerning options ... maybe it could be updated / rewritten to push the extra option handling ?

smnandre reviewed

View reviewed changes

src/Autocomplete/doc/index.rst

@@ @@ -171,6 +171,109 @@ After creating this class, use it in your form: @@
               Congratulations! Your ``EntityType`` is now Ajax-powered!
+              .. _passing-extra-options-to-the-ajax-powered-autocomplete:
+              Passing Extra Options to the Ajax-powered Autocomplete

Collaborator

smnandre Apr 9, 2024

I'd move this block after the standard options.. wdyt ?

(especially if we rewrite the caution block to add a link to this section)

smnandre reviewed

View reviewed changes

src/Autocomplete/doc/index.rst

+              Passing Extra Options to the Ajax-powered Autocomplete
+              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+              .. versionadded:: 2.13

Collaborator

smnandre Apr 9, 2024

Suggested change

      
            .. versionadded:: 2.13
          
            .. versionadded:: 2.14

smnandre reviewed

View reviewed changes

src/Autocomplete/doc/index.rst


		.. versionadded:: 2.13

		The ability to pass extra options was added in LiveComponents 2.13.

Collaborator

smnandre Apr 9, 2024

Suggested change

      
                The ability to pass extra options was added in LiveComponents 2.13.
          
                The ability to pass extra options was added in Autocomplete 2.14.

smnandre reviewed

View reviewed changes

src/Autocomplete/doc/index.rst

+              Passing Extra Options to the Autocompleter
+              ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+              .. versionadded:: 2.13

Collaborator

smnandre Apr 9, 2024

Suggested change

      
            .. versionadded:: 2.13
          
            .. versionadded:: 2.14

smnandre reviewed

View reviewed changes

src/Autocomplete/doc/index.rst


		.. versionadded:: 2.13

		The ability to pass extra options was added in LiveComponents 2.13.

Collaborator

smnandre Apr 9, 2024

Suggested change

      
                The ability to pass extra options was added in LiveComponents 2.13.
          
                The ability to pass extra options was added in Autocomplete 2.14.

smnandre reviewed

View reviewed changes

src/Autocomplete/doc/index.rst

@@ @@ -274,6 +377,9 @@ to the options above, you can also pass: @@
                   Set to ``focus`` to call the ``load`` function when control receives focus.
                   Set to ``true`` to call the ``load`` upon control initialization (with an empty search).
+              ``extra_options`` (default ``[]``)
+                  Allow you to pass extra options for Ajax-based autocomplete fields.

Collaborator

smnandre Apr 9, 2024

Add a link to the related section ?

smnandre reviewed

View reviewed changes

src/Autocomplete/doc/index.rst

+                  #[AsEntityAutocompleteField]
+                  class FoodAutocompleteField extends AbstractType
+                  {
+                      public function configureOptions(OptionsResolver $resolver)

Collaborator

smnandre Apr 9, 2024

Suggested change

      
                    public function configureOptions(OptionsResolver $resolver)
          
                    public function configureOptions(OptionsResolver $resolver): void

smnandre reviewed

View reviewed changes

src/Autocomplete/doc/index.rst

Comment on lines +255 to +266

+                              'query_builder' => function (Options $options) {
+                                  return function (EntityRepository $er) use ($options) {
+                                      $qb = $er->createQueryBuilder('o');
+                                      $excludedFoods = $options['extra_options']['excluded_foods'] ?? [];
+                                      if ([] !== $excludedFoods) {
+                                          $qb->andWhere($qb->expr()->notIn('o.id', $excludedFoods));
+                                      }
+                                      return $qb;
+                                  };
+                              }

Collaborator

smnandre Apr 9, 2024

I love this example because it's very relatable.

On the other side, i'm not sure we want to push that much the "query_builder" option, as it may be hard to grasp for newcomers

Just wondering if we could illustrate the extra_options with something "simpler" ...
.. if not this example is great :)

Collaborator

smnandre commented Apr 9, 2024

A more sensible point here: i'd really like to warn users those values will be "readable" from front... or are they encoded i don't remember what choice was made in the end ?

smnandre reviewed

View reviewed changes

src/Autocomplete/doc/index.rst

Comment on lines +183 to +189

+              By default, when you pass any options while adding a field to a form type, they will be lost
+              when the autocomplete field is rendered on an Ajax call. To partially avoid this limitation,
+              the `extra_options` option was added. It can only hold a scalar values, but it covers most use cases.
+              Considering the following example, when the form type is rendered for the first time, it will use the `query_builder` defined
+              while adding a `food` field to the `FoodForm`. However, when the Ajax is used to fetch the results, on the consequent renders,
+              the default `query_builder` will be used::

Collaborator

smnandre Apr 9, 2024

Just a personal feeling (and my english is quite limited so take this with a pinch of salt :) )

And i think @javiereguiluz vision would be much usefull than mine there :)

What i feel here is that those two paragraphs may be written with a tone more "neutral / factual" (not sure of the term)

Something like

Autocomplete field options are not kept from a request to another, so following renders ... 

To persists options betwen [..], you must use extra_options [..]

::warning
only scalar (string, booleans ....)

And then the example.

not sure if what i'm saying is clear 👼

smnandre reviewed

View reviewed changes

src/Autocomplete/doc/index.rst

+                      }
+                  }
+              The magic of the `extra_options` option is that it will be passed to the `FoodAutocompleteField` every time an Ajax call is made.

Collaborator

smnandre Apr 9, 2024

Suggested change

      
            The magic of the `extra_options` option is that it will be passed to the `FoodAutocompleteField` every time an Ajax call is made.
          
            The magic of the `extra_options` is that it will be passed to the `FoodAutocompleteField` every time an Ajax call is made.

Chris53897 commented Apr 24, 2024

@jakubtobiasz Thanks for this PR.

In my use case, we need to overwrite the label.
I solved it with this Code, and i think this is useful for others as well.
Maybe you can add this to the PR? Otherwise i can add a PR after this is merged.

#[AsEntityAutocompleteField]
class FooAutocompleteField extends AbstractType
{
    public function buildView(FormView $view, FormInterface $form, array $options): void
    {
        if(isset($options['extra_options']['label'])) {
            $view->vars['label'] = $options['extra_options']['label'];
        }
    }

class FooFormType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
      $builder->add('bar', FooAutocompleteField::class, ['extra_options' => ['label' => 'Overwritten Label']]);
   }
  ...
}

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment