From a9567dbd74ef8128e0d710c5d0651b4cc87c89da Mon Sep 17 00:00:00 2001
From: jeromecambon <jerome.cambon@bonitasoft.com>
Date: Fri, 20 Dec 2024 12:01:26 +0100
Subject: [PATCH] docs: Autocomplete widget does not update its displayed value
 (#2946) (#2948)

Covers [UID-733](https://bonitasoft.atlassian.net/browse/UID-733)

[UID-733]:
https://bonitasoft.atlassian.net/browse/UID-733?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
---
 .../pages-and-forms/pages/widgets-inputs.adoc |  2 +
 modules/pages-and-forms/pages/widgets.adoc    | 38 +++++++++++++++++--
 2 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/modules/pages-and-forms/pages/widgets-inputs.adoc b/modules/pages-and-forms/pages/widgets-inputs.adoc
index b301cceb69..3a38c7f3d3 100644
--- a/modules/pages-and-forms/pages/widgets-inputs.adoc
+++ b/modules/pages-and-forms/pages/widgets-inputs.adoc
@@ -45,6 +45,8 @@ image::widgets/autocomplete.png[autocomplete]
 
 Use an autocomplete widget to offer the user a list of possible values based on data entered in the field. For example, in a firstName field, if the user types _chri_, the values _chris_, _christine_, _christian_, _christiane_ are proposed. The user selects the correct value. To define the *available values*, bind a data source to initialize the suggestions. For suggestions that are an array of objects, you can specify a *displayed key* to identify the attribute to show as a suggestion in the widget. The value must be bound to a variable that will hold the selected suggestion.
 
+See xref:ROOT:widgets.adoc#troubleshooting-ui-designer-widgets[Troubleshooting UI Designer widgets] to solve common issues with this widget.
+
 === Select widget
 
 image::widgets/select.png[select]
diff --git a/modules/pages-and-forms/pages/widgets.adoc b/modules/pages-and-forms/pages/widgets.adoc
index 29eb463e23..81907cf39c 100644
--- a/modules/pages-and-forms/pages/widgets.adoc
+++ b/modules/pages-and-forms/pages/widgets.adoc
@@ -42,6 +42,8 @@ Limitations:
 * The URL should have the file type as extension (e.g. \https://myhost/doc/sample.pdf)
 ====
 
+See <<troubleshooting-ui-designer-widgets>> to solve common issues with this widget.
+
 [#rich-text-area]
 
 == Rich Text Area widget
@@ -102,6 +104,7 @@ When the switch is completed, you still may have to set properties from the prop
 Switch feature not available for Internet Explorer 11 and Microsoft Edge.
 ====
 
+[#troubleshooting-ui-designer-widgets]
 
 [.troubleshooting-title]
 == Troubleshooting UI Designer widgets
@@ -121,19 +124,48 @@ The URL points on a file without extension (e.g. \https://myhost/doc/sample)
 Make a custom widget from the File Viewer widget, and adapt the `controller.isPDF` or `controller.isImage`.
 --
 
+[.troubleshooting-section]
+--
+[.symptom]
+Autocomplete widget does not update its displayed value
+
+[.symptom-description]
+Autocomplete widget does not update its displayed value when the value is changed by a variable.
+
+[.solution]#Possible solution#
+Make a custom widget from the Autocomplete widget, and update the controller by replacing the function that set the `formatLabel` as follows:
+
+[source,javascript]
+----
+  this.formatLabel = function ($model) {
+    if (this.selectedItem) {
+      let sel = this.selectedItem;
+      this.selectedItem = undefined;
+      return this.getLabel(sel);
+    } else {
+      if (typeof $model === 'object') {
+        return this.getLabel($model);
+      } else {
+        return $model;
+      }
+    }
+  };
+----
+--
+
 [#widgets-templating-troubleshooting]
+
 [.troubleshooting-section]
 --
 [.symptom]
-My custom styling on pbChecklist or pbRadiobuttons isn't working as it was in previous Bonita UI Designer versions. 
+My custom styling on pbChecklist or pbRadiobuttons isn't working as it was in previous Bonita UI Designer versions.
 
 [.symptom-description]
 My custom css rule, from a theme or a css file is not applied after the migration on {bonitaVersion}.
 
 [.cause]#Potential cause#
-The internal HTML templating has been changed so that accessibility rules could be applied for the two widgets. 
+The internal HTML templating has been changed so that accessibility rules could be applied for the two widgets.
 
 [.solution]#Possible solution#
 Check you custom css selector. For example, <label> html tag has been replaced by <legend>. More details are available in UI-Designer, Editor > Help (in the top right corner) > Migrations.
 --
-