[WC-3186] Combobox onChange event for store value target (#2053)

Author: r0b1n

packages/pluggableWidgets/combobox-web/CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Added
+
+- We introduced a new "On change" action in Database mode that fires only when the selection changes, unlike the previous behavior that fired on initialization.
+
+### Changed
+
+- We renamed the "On change" action in Database mode to "On selection" to better describe its actual behavior (fires on initialization and selection changes).
+
 ## [2.7.2] - 2026-01-28
 
 ### Fixed

packages/pluggableWidgets/combobox-web/src/Combobox.editorConfig.ts

@@ -107,7 +107,6 @@ export function getProperties(
             "selectionMethod",
             "selectAllButton",
             "selectAllButtonCaption",
-            "onChangeEvent",
             ...ASSOCIATION_SOURCE_CONFIG
         ]);
         if (values.optionsSourceDatabaseDataSource === null) {
@@ -140,6 +139,10 @@ export function getProperties(
             if (values.customEditability !== "conditionally") {
                 hidePropertiesIn(defaultProperties, values, ["customEditabilityExpression"]);
             }
+
+            // hide generic On change event when value is not saved anywhere.
+            // Users should use "On selection" that is assigned to the selection API (onChangeDatabaseEvent)
+            hidePropertiesIn(defaultProperties, values, ["onChangeEvent"]);
         } else {
             hidePropertiesIn(defaultProperties, values, ["customEditability", "customEditabilityExpression"]);
         }

packages/pluggableWidgets/combobox-web/src/Combobox.xml

@@ -104,8 +104,8 @@
                 <!-- END CAPTIONS -->
             </propertyGroup>
             <propertyGroup caption="Store value">
-                <property key="optionsSourceDatabaseValueAttribute" type="attribute" dataSource="optionsSourceDatabaseDataSource">
-                    <caption>Value</caption>
+                <property key="databaseAttributeString" type="attribute" setLabel="true" required="false">
+                    <caption>Target</caption>
                     <description />
                     <attributeTypes>
                         <attributeType name="String" />
@@ -114,8 +114,8 @@
                         <attributeType name="Enum" />
                     </attributeTypes>
                 </property>
-                <property key="databaseAttributeString" type="attribute" setLabel="true" required="false">
-                    <caption>Target attribute</caption>
+                <property key="optionsSourceDatabaseValueAttribute" type="attribute" dataSource="optionsSourceDatabaseDataSource">
+                    <caption>Value</caption>
                     <description />
                     <attributeTypes>
                         <attributeType name="String" />
@@ -314,12 +314,14 @@
 
         <propertyGroup caption="Events">
             <property key="onChangeEvent" type="action" required="false">
+                <!-- this event is called manually in the code, not attached to anything -->
                 <caption>On change</caption>
                 <description />
             </property>
             <property key="onChangeDatabaseEvent" type="action" required="false">
-                <caption>On change</caption>
-                <description />
+                <!-- this event is tied to the Selection API property, fired automatically -->
+                <caption>On selection</caption>
+                <description>This event happens when "selection of" this widget changes or initializes.</description>
             </property>
             <property key="onEnterEvent" type="action" required="false">
                 <caption>On enter</caption>

packages/pluggableWidgets/combobox-web/src/helpers/Database/DatabaseSingleSelectionSelector.ts

@@ -1,4 +1,4 @@
-import { EditableValue, ListAttributeValue, ObjectItem, SelectionSingleValue } from "mendix";
+import { ActionValue, EditableValue, ListAttributeValue, ObjectItem, SelectionSingleValue } from "mendix";
 import {
     ComboboxContainerProps,
     LoadingTypeEnum,
@@ -11,6 +11,7 @@ import { DatabaseCaptionsProvider } from "./DatabaseCaptionsProvider";
 import { DatabaseOptionsProvider } from "./DatabaseOptionsProvider";
 import { DatabaseValuesProvider } from "./DatabaseValuesProvider";
 import { extractDatabaseProps, getReadonly } from "./utils";
+import { executeAction } from "@mendix/widget-plugin-platform/framework/execute-action";
 
 export class DatabaseSingleSelectionSelector<T extends string | Big, R extends EditableValue<T>>
     implements SingleSelector
@@ -30,6 +31,7 @@ export class DatabaseSingleSelectionSelector<T extends string | Big, R extends E
 
     validation?: string = undefined;
     values: DatabaseValuesProvider;
+    private onChangeEvent?: ActionValue;
     protected _attr: R | undefined;
     private selection?: SelectionSingleValue;
 
@@ -52,14 +54,16 @@ export class DatabaseSingleSelectionSelector<T extends string | Big, R extends E
             filterType,
             lazyLoading,
             loadingType,
-            valueSourceAttribute
+            valueSourceAttribute,
+            onChangeEvent
         } = extractDatabaseProps(props);
 
         if (ds.status === "loading" && (!lazyLoading || ds.limit !== Infinity)) {
             return;
         }
 
         this._attr = targetAttribute as R;
+        this.onChangeEvent = onChangeEvent;
         this.readOnly = getReadonly(targetAttribute, props.customEditability, props.customEditabilityExpression);
         this.lazyLoader.updateProps(ds);
         this.lazyLoader.setLimit(
@@ -144,9 +148,19 @@ export class DatabaseSingleSelectionSelector<T extends string | Big, R extends E
         }
     }
 
+    setAttributeValue(value: T): void {
+        if (this._attr) {
+            const oldValue = this._attr.value;
+            this._attr.setValue(value);
+            if (!_valuesIsEqual(oldValue, value)) {
+                executeAction(this.onChangeEvent);
+            }
+        }
+    }
+
     setValue(objectId: string | null): void {
         const value = this.values.get(objectId) as T;
-        this._attr?.setValue(value);
+        this.setAttributeValue(value);
         if (objectId !== (this.selection?.selection?.id ?? "")) {
             this.selection?.setSelection(this.options._optionToValue(objectId));
         }

packages/pluggableWidgets/combobox-web/src/helpers/Database/utils.ts

@@ -1,4 +1,5 @@
 import {
+    ActionValue,
     DynamicValue,
     EditableValue,
     ListAttributeValue,
@@ -29,6 +30,7 @@ type ExtractionReturnValue = {
     loadingType: LoadingTypeEnum;
     valueSourceAttribute: ListAttributeValue<string | Big> | undefined;
     filterInputDebounceInterval: number;
+    onChangeEvent: ActionValue | undefined;
 };
 
 export function extractDatabaseProps(props: ComboboxContainerProps): ExtractionReturnValue {
@@ -72,6 +74,8 @@ export function extractDatabaseProps(props: ComboboxContainerProps): ExtractionR
         }
     }
 
+    const onChangeEvent = props.onChangeEvent;
+
     return {
         targetAttribute,
         captionProvider: captionType === "attribute" ? captionAttribute : captionExpression,
@@ -85,7 +89,8 @@ export function extractDatabaseProps(props: ComboboxContainerProps): ExtractionR
         lazyLoading,
         loadingType,
         valueSourceAttribute,
-        filterInputDebounceInterval
+        filterInputDebounceInterval,
+        onChangeEvent
     };
 }
 

packages/pluggableWidgets/combobox-web/typings/ComboboxProps.d.ts

@@ -63,8 +63,8 @@ export interface ComboboxContainerProps {
     optionsSourceDatabaseCaptionAttribute?: ListAttributeValue<string>;
     optionsSourceAssociationCaptionExpression?: ListExpressionValue<string>;
     optionsSourceDatabaseCaptionExpression?: ListExpressionValue<string>;
-    optionsSourceDatabaseValueAttribute?: ListAttributeValue<string | Big>;
     databaseAttributeString?: EditableValue<string | Big>;
+    optionsSourceDatabaseValueAttribute?: ListAttributeValue<string | Big>;
     attributeAssociation: ReferenceValue | ReferenceSetValue;
     optionsSourceAssociationDataSource?: ListValue;
     staticAttribute: EditableValue<string | Big | boolean | Date>;
@@ -120,8 +120,8 @@ export interface ComboboxPreviewProps {
     optionsSourceDatabaseCaptionAttribute: string;
     optionsSourceAssociationCaptionExpression: string;
     optionsSourceDatabaseCaptionExpression: string;
-    optionsSourceDatabaseValueAttribute: string;
     databaseAttributeString: string;
+    optionsSourceDatabaseValueAttribute: string;
     attributeAssociation: string;
     optionsSourceAssociationDataSource: {} | { caption: string } | { type: string } | null;
     staticAttribute: string;