Merge remote-tracking branch 'origin/poc-autocomplete-closure' into poc-autocomplete-closure

Author: antoine

demo/app/Sharp/Posts/PostForm.php

@@ -138,18 +138,17 @@ public function buildFormFields(FieldsContainer $formFields): void
                 SharpFormAutocompleteRemoteField::make('author_id')
                     ->setReadOnly(! auth()->user()->isAdmin())
                     ->setLabel('Author')
-                    ->setRemoteEndpoint('/api/admin/users')
-                    ->queryResultsUsing(function ($search, $data) {
-                        $users = User::orderBy('name');
+                    ->setRemoteCallback(function ($search) {
+                        $users = User::orderBy('name')->limit(10);
 
                         foreach (explode(' ', trim($search)) as $word) {
-                            $users->where(function ($query) use ($word) {
-                                $query->orWhere('name', 'like', "%$word%")
-                                    ->orWhere('email', 'like', "%$word%");
-                            });
+                            $users->where(fn ($query) => $query
+                                ->where('name', 'like', "%$word%")
+                                ->orWhere('email', 'like', "%$word%")
+                            );
                         }
 
-                        return $users->limit(10)->get();
+                        return $users->get();
                     })
                     ->setListItemTemplate('<div>{{ $name }}</div><div><small>{{ $email }}</small></div>')
                     ->setHelpMessage('This field is only editable by admins.'),

demo/app/Sharp/TestForm/TestForm.php

@@ -209,28 +209,24 @@ public function buildFormFields(FieldsContainer $formFields): void
             )
             ->addField(
                 SharpFormSelectField::make('select_dropdown', $this->options())
-                    ->setLocalized()
                     ->setLabel('Select dropdown')
                     ->setMultiple()
                     ->setDisplayAsDropdown(),
             )
             ->addField(
                 SharpFormSelectField::make('select_list', $this->options())
-                    ->setLocalized()
                     ->setLabel('Select list')
                     ->setDisplayAsList(),
             )
             ->addField(
                 SharpFormSelectField::make('select_list_multiple', $this->options())
-                    ->setLocalized()
                     ->setLabel('Select list multiple')
                     ->setMultiple()
                     ->setDisplayAsList()
                     ->setMaxSelected(2),
             )
             ->addField(
                 SharpFormTagsField::make('tags', $this->options())
-                    ->setLocalized()
                     ->setLabel('Tags')
                     ->setCreatable(true)
                     ->setCreateAttribute('label')

docs/guide/form-fields/autocomplete-list.md

@@ -12,7 +12,7 @@ You can in fact define the list as this:
 SharpFormAutocompleteListField::make('winners')
         ->setLabel('Winners')
         ->setItemField(
-            SharpFormAutocompleteField::make('item', 'remote')
+            SharpFormAutocompleteRemoteField::make('item')
                 ->setRemoteEndpoint('/players')
                 // [...]
         )
@@ -30,7 +30,7 @@ But why can't we use a classic List for this? Well, the `model->winners` relatio
 
 Configuration is the same as the classic [List](list.md), except for:
 
-### `setItemField(SharpFormAutocompleteField $field)`
+### `setItemField(SharpFormAutocompleteRemoteField $field)`
 
 You can use this function instead of `addItemField`, since items of AutocompleteList have only one field.
 

docs/guide/form-fields/autocomplete.md

@@ -21,16 +21,52 @@ This method is useful to link the dataset of a local autocomplete (aka: the `loc
 
 ### `setRemoteEndpoint(string $remoteEndpoint)`
 
-The endpoint to hit with mode=remote.
+The remote endpoint which should return JSON-formatted results. Note that you can add the `sharp_auth` middleware to this route to handle authentication and prevent this API endpoint to be called by non-sharp users:
 
-If this endpoint is yours (`remote` mode here is useful to avoid loading a lot of data in the view), you can add the `sharp_auth` middleware to the API route to handle authentication and prevent this API endpoint to be called by non-sharp users:
+```php
+// in a route file
+
+Route::get('/api/sharp/clients', [MySharpApiClientController::class, 'index'])
+    ->middleware('sharp_auth');
+```
+
+::: tip
+This endpoint MUST be part of your application. If you need to hit an external endpoint, you should create a custom endpoint in your application that will call the external endpoint (be sure to check the alternative `setRemoteCallback` method).
+:::
+
+### `setRemoteCallback(Closure $closure, ?array $linkedFields = null)`
+
+To avoid the pain of writing a new dedicated endpoint, and for simple cases, you can use this method to provide a callback that will be called when the autocomplete field needs to fetch data. The callback will receive the search string as a parameter and should return an array of objects.
+
+Example:
+
+```php
+SharpFormAutocompleteRemoteField::make('customer')
+    ->setRemoteCallback(function ($search) {
+        return Customer::select('id', 'name', 'email')
+            ->where('name', 'like', "%$search%")
+            ->get();
+    });
+```
+
+The second argument, `$linkedFields`, allows you to provide a list of fields that will be sent with their values to the callback, so you can filter the results based on the values of other fields.
+
+Example:
 
 ```php
-Route::get('/api/sharp/clients')
-    ->middleware('sharp_auth')
-    ->uses('MySharpApiClientController@index')
+SharpFormAutocompleteRemoteField::make('customer')
+    ->setRemoteCallback(function ($search, $linkedFields) {
+        return Customer::select('id', 'name', 'email')
+            ->when(
+                $linkedFields['country'], 
+                fn ($query) => $query->where('country_id', $linkedFields['country'])
+            )
+            ->where('name', 'like', "%$search%")
+            ->get();
+    }, linkedFields: ['country']);
 ```
 
+
 ### `setSearchMinChars(int $searchMinChars)`
 
 Set a minimum number of character to type before performing the search.
@@ -61,7 +97,7 @@ Set the remote method to GET (default) or POST.
 In a remote autocomplete case, you can use this method instead of `setRemoteEndpoint` to handle a dynamic URL, based on another form field. Here's how, for example:
 
 ```php
-SharpFormAutocompleteField::make('brand', 'remote')
+SharpFormAutocompleteRemoteField::make('brand')
     ->setDynamicRemoteEndpoint('/brands/{{country}}');
 ```
 
@@ -71,7 +107,7 @@ You may need to provide a default value for the endpoint, used when `country` (i
 fill the second argument:
 
 ```php
-SharpFormAutocompleteField::make('model', 'remote')
+SharpFormAutocompleteRemoteField::make('model')
     ->setDynamicRemoteEndpoint(''/models/{{country}}/{{brand}}'', [
         'country' => 'france',
         'brand' => 'renault'
@@ -90,53 +126,22 @@ Set the name of the id attribute for items. This is useful :
 - to designate the id attribute in the remote API call return.
 Default: `"id"`
 
-### `setListItemInlineTemplate(string $template)`
-### `setResultItemInlineTemplate(string $template)`
-Just write the template as a string, using placeholders for data like this: `{{var}}`.
+### `setListItemTemplate(View|string $template)`
+### `setResultItemTemplate(View|string $template)`
 
-Example:
+The templates for the list and result items can be set in two ways: either by passing a string, or by passing a Laravel view.
 
-```php
-$panel->setInlineTemplate(
-    'Foreground: <strong>{{color}}</strong>'
-)
-```
-
-The template will be used, depending on the function, to display either the list item (in the result dropdown) or the result item (meaning the valuated form input).
-
-Be aware that you'll need for this to work to pass a valuated object to the Autocomplete, as data.
-
-### `setListItemTemplatePath(string $listItemTemplatePath)`
-### `setResultItemTemplatePath(string $resultItemTemplate)`
-
-Use this if you need more control: give the path of a full template, in its own file.
-
-The template will be [interpreted by Vue.js](https://vuejs.org/v2/guide/syntax.html), meaning you can add data placeholders, DOM structure but also directives, and anything that Vue will parse. For instance:
-
-```vue
-<div v-if="show">result is {{value}}</div>
-<div v-else>result is unknown</div>
-```
-
-The template will be used, depending on the function, to display either the list item (in the result dropdown) or the result item (meaning the valuated form input).
-
-Be aware that you'll need for this to work to pass a valuated object to the Autocomplete, as data.
-
-### `setAdditionalTemplateData(array $data)`
-
-Useful to add some static (or at least not instance-dependant) data to the template. For instance:
+Examples:
 
 ```php
-SharpFormAutocompleteRemoteField::make('brand')
-    ->setAdditionalTemplateData([
-        'years' => [2020, 1018, 2017]
-    ]);
-```
-
-In the template, the provided data can be used as normal:
-
-```vue
-<div v-for="year in years"> {{ year }} </div>
+SharpFormAutocompleteRemoteField::make('customer')
+    ->setRemoteCallback(function ($search) {
+        return Customer::select('id', 'name', 'email')
+            ->where('name', 'like', "%$search%")
+            ->get();
+    })
+    ->setListItemTemplate('<div>{{$name}}</div><div><small>{{$email}}</small></div>')
+    ->setResultItemTemplate(view('my/customer/blade/view'));
 ```
 
 ## Formatter

docs/guide/upgrading/9.0.md

@@ -495,7 +495,11 @@ class PostBlockList extends SharpEntityList
 
 You can of course instead declare a real Filter.
 
-## SharpFormGeolocationField using Google Maps API must now provide a Map ID
+## Localization feature was removed for `SharpFormSelectField`, `SharpFormTagsField` and `SharpFormAutocompleteField` fields
+
+Those fields could be localized in 8.x it a weird way: **labels** were localized, but not **values**. This was a really misleading, so we decided to remove entirely this behavior in 9.x. The only real impact should be to remove setLocalized() calls in your code for these fields.
+
+## `SharpFormGeolocationField` using Google Maps API must now provide a Map ID
 
 Sharp 9.x now uses Advanced Markers which requires a [Map ID](https://developers.google.com/maps/documentation/get-map-id), register it with the following method of the field :
 
@@ -515,15 +519,15 @@ class PostForm extends SharpForm
 ```
 
 
-## SharpFormAutocompleteFormField was split in two subclasses for local and remote cases
+## `SharpFormAutocompleteFormField` was rewritten and need to be migrated
 
-REWRITE THIS WITH:
-- no more `setAdditionalTemplateData`
-- 
+First, the `SharpFormAutocompleteFormField` class was split into two classes: `SharpFormAutocompleteLocalField` and `SharpFormAutocompleteRemoteField`, to clearly separate these two different use cases.
 
-This isn’t a breaking change, since `SharpFormAutocompleteFormField::make($key, $mode)` is still supported, but deprecated. You should migrate to the new `SharpFormAutocompleteLocalField` and `SharpFormAutocompleteRemoteField` classes.
+Second, Vue templates must be migrated to Blade templates (similar to the `SharpWidgetPanel` or Page Alerts migrations). You can either pass a view name or a blade template directly to the newly named `setListItemTemplate()` and `setResultItemTemplate()` methods (the old `setListItemInlineTemplate()`, `setListItemTemplatePath()`, `setResultItemInlineTemplate()` and `setResultItemTemplatePath()` were removed).
 
-In 8.x:
+The `setAdditionalTemplateData()` method was also removed, in favor of a more straightforward way to pass additional data to the template.
+
+Example in 8.x:
 
 ```php
 class PostForm extends SharpForm
@@ -565,8 +569,7 @@ class PostForm extends SharpForm
             ->addField(
                 SharpFormAutocompleteRemoteField::make('author_id')
                     ->setRemoteEndpoint('/api/admin/users')
-                    ->setListItemInlineTemplate('{{name}}')
-                    ->setResultItemInlineTemplate('{{name}}')
+                    ->setListItemTemplate('{{$name}}')
             )
             ->addField(
                 SharpFormAutocompleteLocalField::make('category_id')
@@ -585,6 +588,51 @@ class PostForm extends SharpForm
 }
 ```
 
+Finally, there is a big evolution which concerns the remote autocomplete endpoint: your 8.x implementation should still work, but you should note that:
+- you can now directly write the autocomplete endpoint as a callback closure in the field (no need to use a dedicated route + controller), 
+- external endpoint URLs aren’t supported anymore (you must write a wrapper around this external endpoint, either as a route + controller or via the new callback option).
+
+Example in 8.x:
+
+```php
+class PostForm extends SharpForm
+{
+    public function buildFormFields(FieldsContainer $formFields): void
+    {
+        $formFields
+            ->addField(
+                SharpFormAutocompleteField::make('author_id', 'remote')
+                    ->setRemoteEndpoint('/api/admin/users')
+                    ->setListItemInlineTemplate('{{name}}')
+                    ->setResultItemInlineTemplate('{{name}}')
+            );
+    }
+    
+    // ...
+}
+```
+
+In 9.x:
+
+```php
+class PostForm extends SharpForm
+{
+    public function buildFormFields(FieldsContainer $formFields): void
+    {
+        $formFields
+            ->addField(
+                SharpFormAutocompleteRemoteField::make('author_id')
+                    ->setRemoteCallback(function ($search) {
+                        return User::where('name', 'like', "%$search%")->get();
+                    })
+                    ->setListItemTemplate('{{$name}}')
+            );
+    }
+    
+    // ...
+}
+```
+
 ## `SharpFormUploadField`’s image related methods were renamed
 
 This isn't a breaking change, since the old methods are still available, but deprecated. You should migrate to the new methods:

src/Data/Form/Fields/FormAutocompleteRemoteFieldData.php

@@ -25,7 +25,7 @@ public function __construct(
         public string $itemIdAttribute,
         public int $searchMinChars,
         public int $debounceDelay,
-        public string $remoteEndpoint,
+        public ?string $remoteEndpoint = null,
         /** @var string[]|null */
         public ?array $callbackLinkedFields = null,
         public ?string $placeholder = null,

src/Form/Fields/SharpFormAutocompleteLocalField.php

@@ -5,12 +5,9 @@
 use Code16\Sharp\Form\Fields\Formatters\AutocompleteLocalFormatter;
 use Code16\Sharp\Form\Fields\Utils\IsSharpFormAutocompleteField;
 use Code16\Sharp\Form\Fields\Utils\SharpFormAutocompleteCommonField;
-use Code16\Sharp\Utils\Fields\IsSharpFieldWithLocalization;
 use Illuminate\Support\Collection;
 
-class SharpFormAutocompleteLocalField
-    extends SharpFormField
-    implements IsSharpFieldWithLocalization, IsSharpFormAutocompleteField
+class SharpFormAutocompleteLocalField extends SharpFormField implements IsSharpFormAutocompleteField
 {
     use SharpFormAutocompleteCommonField;