Skip to content
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.

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

[Autocomplete] Adjust index.rst format #2297

Merged
merged 1 commit into from
Oct 24, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 37 additions & 31 deletions src/Autocomplete/doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ Tom Select-powered UI control by adding the ``autocomplete`` option:
}

That's all you need! When you refresh, the Autocomplete Stimulus controller
will transform your select element into a smart UI control:
will transform your ``<select>`` element into a smart UI control:

.. image:: food-non-ajax.png
:alt: Screenshot of a Food select with Tom Select
Expand Down Expand Up @@ -99,7 +99,8 @@ Or, create the field by hand::
// src/Form/FoodAutocompleteField.php
// ...

use Symfony\Bundle\SecurityBundle\Security;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\UX\Autocomplete\Form\AsEntityAutocompleteField;
use Symfony\UX\Autocomplete\Form\BaseEntityAutocompleteType;

Expand Down Expand Up @@ -283,16 +284,22 @@ Passing Extra Options to the Ajax-powered Autocomplete

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

Autocomplete field options are not preserved when the field is rendered on an Ajax call. So, features like exclude some options
based on the current form data are not possible by default. To partially avoid this limitation, the `extra_options` option was added.
Autocomplete field options are **not preserved** when the field is rendered
on an Ajax call. So, features like exclude some options based on the current
form data are not possible by default.

To partially avoid this limitation, the ``extra_options`` option was added.

.. warning::

Only scalar values (``string``, ``integer``, ``float``, ``boolean``), ``null`` and ``array`` (consisted from the same types as mentioned before) can be passed as extra options.
Only scalar values (``string``, ``integer``, ``float``, ``boolean``),
``null`` and ``array`` (consisted from the same types as mentioned before)
can be passed as extra options.

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::
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::

// src/Form/FoodForm.php
// ...
Expand All @@ -306,21 +313,18 @@ the default ``query_builder`` will be used::
$builder
->add('food', FoodAutocompleteField::class, [
'query_builder' => function (EntityRepository $er) {
$qb = $er->createQueryBuilder('o');

$qb->andWhere($qb->expr()->notIn('o.id', [$currentFoodId]));

return $qb;
};
}
return $er->createQueryBuilder('o')
->andWhere($qb->expr()->notIn('o.id', [$currentFoodId]));
};
])
;
}
}

If some food can be consisted of other foods, we might want to exclude the "root" food from the list of available foods.
To achieve this, we can remove the ``query_builder`` option from the above example and pass the ``excluded_foods`` extra option
to the ``FoodAutocompleteField``::
If some food can be consisted of other foods, we might want to exclude the
"root" food from the list of available foods. To achieve this, we can remove
the ``query_builder`` option from the above example and pass the ``excluded_foods``
extra option to the ``FoodAutocompleteField``::

// src/Form/FoodForm.php
// ...
Expand All @@ -341,13 +345,13 @@ to the ``FoodAutocompleteField``::
}
}

The magic of the ``extra_options`` is that it will be passed to the ``FoodAutocompleteField`` every time an Ajax call is made.
So now, we can just use the ``excluded_foods`` extra option in the default ``query_builder`` of the ``FoodAutocompleteField``::
The magic of the ``extra_options`` is that it will be passed to the ``FoodAutocompleteField``
every time an Ajax call is made. So now, we can just use the ``excluded_foods``
extra option in the default ``query_builder`` of the ``FoodAutocompleteField``::

// src/Form/FoodAutocompleteField.php
// ...

use Symfony\Bundle\SecurityBundle\Security;
use Symfony\UX\Autocomplete\Form\AsEntityAutocompleteField;
use Symfony\UX\Autocomplete\Form\BaseEntityAutocompleteType;

Expand Down Expand Up @@ -593,12 +597,14 @@ Passing Extra Options to the Autocompleter

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

If you need to pass extra options to the autocompleter, you can do so by implementing the
``\Symfony\UX\Autocomplete\OptionsAwareEntityAutocompleterInterface`` interface.
If you need to pass extra options to the autocompleter, you can do so by
implementing the ``\Symfony\UX\Autocomplete\OptionsAwareEntityAutocompleterInterface``
interface.

.. tip::

If you want to know **why** you might need to use the ``extra_options`` feature, see :ref:`passing-extra-options-to-the-ajax-powered-autocomplete`.
If you want to know **why** you might need to use the ``extra_options``
feature, see :ref:`passing-extra-options-to-the-ajax-powered-autocomplete`.

.. code-block:: diff

Expand Down Expand Up @@ -634,13 +640,13 @@ If you need to pass extra options to the autocompleter, you can do so by impleme
+ return $qb;
+ }

+/**
+ * @param array<string, mixed> $options
+ */
+public function setOptions(array $options): void
+{
+ $this->options = $options;
+}
+ /**
+ * @param array<string, mixed> $options
+ */
+ public function setOptions(array $options): void
+ {
+ $this->options = $options;
+ }

.. _manual-stimulus-controller:

Expand Down