Merge pull request mendix#10751 from stdagkalakis/wtf/WTF-2552-file-image-props-upload

Yiyun333 · web-flow · commit 4d468f9898e2 · 2026-03-02T16:43:07.000+01:00
[WTF-2552] Update docs with file and image props with upload capabilities
diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-client-apis/_index.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-client-apis/_index.md
@@ -121,7 +121,7 @@ Though the type definition above looks complex, it is fairly simply to use becau
 
 ### EditableValue {#editable-value}
 
-`EditableValue` is used to represent values, either an attribute or a variable, that can be changed by a pluggable widget client component and is passed only to [attribute properties](/apidocs-mxsdk/apidocs/pluggable-widgets-property-types/#attribute). It is defined as follows:
+`EditableValue` is used to represent a value (either an attribute or a variable) that can be changed by a pluggable widget client component and is passed only to [attribute properties](/apidocs-mxsdk/apidocs/pluggable-widgets-property-types/#attribute). It is defined as follows:
 
 ```ts
 export interface EditableValue<T extends AttributeValue> {
@@ -145,22 +145,67 @@ export interface EditableValue<T extends AttributeValue> {
 
 A component will receive `EditableValue<X>` where `X` depends on the configured `attributeType`.
 
-`status` is similar to one exposed for `DynamicValue`. It indicates if the value's loading has finished and if loading was successful. Similarly to `DynamicValue`, `EditableValue` keeps returning the previous `value` when `status` changes from `Available` to `Loading` to help a widget avoid flickering.
+`status` is similar to the one exposed for `DynamicValue`. It indicates if the value's loading has finished, and if loading was successful. Similarly to `DynamicValue`, `EditableValue` keeps returning the previous `value` when `status` changes from `Available` to `Loading` to help a widget avoid flickering.
 
 The flag `readOnly` indicates whether a value can actually be edited. It will be true, for example, when a widget is placed inside a Data view that is not [editable](/refguide/data-view/#editable), or when a selected attribute is not editable due to [access rules](/refguide/access-rules/). The `readOnly` flag is always true when a `status` is not `ValueStatus.Available`. Any attempt to edit a value set to read-only will have no affect and incur a debug-level warning message.
 
 The value can be read from the `value` field and modified using `setValue` function. Note that `setValue` returns nothing and does not guarantee that the value is changed synchronously. But when a change is propagated, a component receives a new prop reflecting the change.
 
-When setting a value, a new value might not satisfy certain validation rules — for example when an attribute is selected and the new value is bigger than the underlying attribute allows. In this case, your change will affect only `value` and `displayValue` received through a prop. Your change will not be propagated to an object’s attribute and will not be visible outside of your component. The component will also receive a validation error text through the `validation` field of `EditableValue`.
+When setting a value, a new value might not satisfy certain validation rules — for example, when an attribute is selected and the new value is bigger than the underlying attribute allows. In this case, your change will affect only `value` and `displayValue` received through a prop. Your change will not be propagated to an object’s attribute and will not be visible outside of your component. The component will also receive a validation error text through the `validation` field of `EditableValue`.
 
-It is possible for a component to extend the defined set of validation rules. A new validator — a function that checks a passed value and returns a validation message string if any — can be provided through the `setValidator` function. A component can have only a single custom validator. The Mendix Platform ensures that custom validators are run whenever necessary, for example when a page is being saved by an end-user. It is best practice to call `setValidator` early in a component's lifecycle — specifically in the [componentDidMount](https://en.reactjs.org/docs/react-component.html#componentdidmount) function.
+It is possible for a component to extend the defined set of validation rules. A new validator (a function that checks a passed value and returns a validation message string if any) can be provided through the `setValidator` function. A component can have only a single custom validator. The Mendix Platform ensures that custom validators are run whenever necessary, for example when a page is being saved by an end-user. It is best practice to call `setValidator` early in a component's lifecycle — specifically in the [componentDidMount](https://en.reactjs.org/docs/react-component.html#componentdidmount) function.
 
-In practice, many client components present values as nicely formatted strings which take locale-specific settings into account. To facilitate such cases `EditableValue` exposes a field `displayValue` which is the formatted version of `value`, and a method `setTextValue` — a version of `setValue` that takes care of parsing. `setTextValue` also validates that a passed value can be parsed and assigned to the target's value type. Similarly to `setValue`, a change to an invalid value will not be propagated further than the prop itself, but a `validation` is reported. Note that if a value cannot be parsed, the prop will contain only a `displayValue` string and `value` will become undefined.
+In practice, many client components present values as nicely formatted strings which take locale-specific settings into account. To facilitate such cases, `EditableValue` exposes a field `displayValue` (which is the formatted version of `value`), and a method `setTextValue` (a version of `setValue` that takes care of parsing). `setTextValue` also validates that a passed value can be parsed and assigned to the target's value type. Similarly to `setValue`, a change to an invalid value will not be propagated further than the prop itself, but a `validation` is reported. Note that if a value cannot be parsed, the prop will contain only a `displayValue` string and `value` will become undefined.
 
 There is a way to use more the convenient `displayValue`  and `setTextValue` while retaining control over the format. A component can use a `setFormatter` method passing a formatter object: an object with `format` and `parse` methods. The Mendix Platform provides a convenient way of creating such objects for simple cases. An existing formatter exposed using a `EditableValue.formatter` field can be modified using its `withConfig` method. For complex cases formatters still can be created manually. A formatter can be reset back to default settings by calling `setFormatter(undefined)`.
 
 The optional field `universe` is used to indicate the set of all possible values that can be passed to a `setValue` if a set is limited. Currently, `universe` is provided only when the edited value is of the Boolean or enumeration [types](/refguide/attributes/#type).
 
+### EditableFileValue {#editable-file-value}
+
+`EditableFileValue` is used to represent file values, that can be changed by a pluggable widget client component and is passed only to [file](/apidocs-mxsdk/apidocs/pluggable-widgets-property-types/#file). It is defined as follows:
+
+```ts
+export interface EditableFileValue<T = FileValue> {
+    readonly status: ValueStatus;
+    readonly readOnly: boolean;
+
+    readonly validation: Option<string>;
+    setValidator: (validator?: (value: Option<T>) => Option<string>) => void;
+
+    readonly value: Option<T>;
+    setValue: (value: Option<T>) => void;
+}
+```
+
+Member `status` is similar to one exposed for `DynamicValue`. It indicates if the value's loading has finished and if loading was successful. Similarly to `DynamicValue`, `EditableFileValue` keeps returning the previous `value` when `status` changes from `Available` to `Loading` to help a widget avoid flickering.
+
+The flag `readOnly` indicates whether a value can actually be edited. The `readOnly` flag is always true when a `status` is not `ValueStatus.Available`. Any attempt to edit a value set to read-only will have no affect and incur a debug-level warning message.
+
+The value can be read from the `value` field and modified using `setValue` function. Note that `setValue` returns nothing and does not guarantee that the value is changed synchronously. But when a change is propagated, a component receives a new prop reflecting the change.
+
+When setting a value, a new value might not satisfy certain validation rules — for example when a file is selected and the new value is bigger than the underlying file allows, or the file type is not allowed. In this case, your change will affect only `value` received through a prop. Your change will not be propagated to an object and will not be visible outside of youAllowUpload (Optional)
+
+This component. The component will also receive a validation error text through the `validation` field of `EditableFileValue`.
+
+It is possible for a component to extend the defined set of validation rules. A new validator — a function that checks a passed value and returns a validation message string if any — can be provided through the `setValidator` function. A component can have only a single custom validator. The Mendix Platform ensures that custom validators are run whenever necessary, for example when a page is being saved by an end-user. It is best practice to call `setValidator` early in a component's lifecycle — specifically in the [componentDidMount](https://en.reactjs.org/docs/react-component.html#componentdidmount) function.
+
+### EditableImageValue {#editable-image-value}
+
+`EditableImageValue` is used to represent image values, that can be changed by a pluggable widget client component and is passed only to [image](/apidocs-mxsdk/apidocs/pluggable-widgets-property-types/#image). It acts as an extension of [EditableFileValue](#editable-file-value) it is defined as follows:
+
+```ts
+export interface EditableImageValue<T extends ImageValue> extends EditableFileValue<T> {
+    setThumbnailSize: (width: Option<number>, height: Option<number>) => void;
+}
+```
+
+`EditableImageValue` provides upload capabilities to [`ImageValue`](#imagevalue), similarly to how [`EditableFileValue`](#editable-file-value) for [`FileValue`](#filevalue). Also it adds `setThumbnailSize`  method which enables a component to request the Mendix Platform to return an image with specific dimensions. The Mendix Platform will take care of resizing the image while keeping the aspect ratio intact. When a thumbnail size is set, the `value` field of `EditableImageValue` will contain a resized image. When a thumbnail size is not set, the `value` field will contain an original image.
+
+{{% alert color="warning" %}}
+`EditableImageValue` does not support `NativeImage`.
+{{% /alert %}}
+
 ### ModifiableValue {#modifiable-value}
 
 `ModifiableValue` is used to represent values that can be changed by a pluggable widget client component. It is passed only to [association properties](/apidocs-mxsdk/apidocs/pluggable-widgets-property-types/#association), and is defined as follows:
diff --git a/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-property-types.md b/content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-property-types.md
@@ -26,7 +26,17 @@ The common structure of a property definition is as follows:
 
 This defines the prop `key` in the client component props which are supplied to the widget client component. Each property must have a unique `key` which can contain letters of all cases, digits, or underscores. However, a `key` attribute cannot *start* with a digit.
 
-#### Type (required)
+#### AllowUpload (Optional) {#allow-upload}
+
+This optional attribute applies only to [file](#file) and [image](#image) properties and determines whether users can upload and edit files. When set to the default value of `false`, properties use the legacy read-only behavior. Setting it to `true` unlocks upload and edit capabilities by passing `EditableFileValue<FileValue>` and `EditableImageValue<ImageValue>` types, as props to a client component.
+
+{{% alert color="warning" %}} Legacy DynamicValue types for file and image properties are deprecated and will be removed at Mendix 12. Use allowUpload="true" to migrate to the new editable types before Mendix 12. {{% /alert %}}
+
+Be aware of behavioral differences between the legacy read-only mode (`false`) and the new editable mode (`true`).
+
+{{% alert color="info" %}} Editable types are not supported for Native as of now. {{% /alert %}}
+
+#### Type (Required)
 
 This defines a property's type. A `type` must be one of the following: 
 
@@ -257,26 +267,29 @@ Then the Studio Pro UI for the component appears like this:
 
 ### Image {#image}
 
-Image allows a user to configure a static image from an [image collection](/refguide/image-collection/). It also allows a user to configure an image from an object that is a specialization of **System.Image**. It is passed as an `DynamicValue<ImageValue>` prop to a client component (for more information, see the [ImageValue](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#imagevalue) section of *Client APIs Available to Pluggable Widgets*). See the [Images Reference Guide](/refguide/images/) for more information about supported image formats.
+Image allows a user to configure an image from an object that is a specialization of **System.Image**. It is passed as an [`EditableImageValue<ImageValue>`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#editable-image-value) prop to a client component. For more information about supported image formats, see the [Images Reference Guide](/refguide/images/).
 
-{{% alert color="warning" %}}
-GIF images are not supported in native mobile apps on Android devices.
-{{% /alert %}}
+The user can use the optional attribute [`allowUpload`](#allow-upload) with default value `false` to use the legacy [`Dynamic<FileValue>`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#filevalue) prop. Beware of behavioral differences based on the `allowUpload` attribute.
+
+{{% alert color="warning" %}} Legacy DynamicValue types for file and image properties are deprecated and will be removed at Mendix 12. Use allowUpload="true" to migrate to the new editable types before Mendix 12. {{% /alert %}}
+
+{{% alert color="info" %}} Editable types are not supported for Native as of now. {{% /alert %}}
 
 #### XML Attributes
 
-| Attribute  | Required | Attribute Type | Description                                                           |
-|------------|----------|----------------|-----------------------------------------------------------------------|
-| `type`     | Yes      | String         | Must be `image`                                                       |
-| `key`      | Yes      | String         | See [key](#key)                                                       |
-| `required` | No       | Boolean        | Whether the property must be specified by the user, `true` by default |
+| Attribute  	| Required | Attribute Type | Description                                                           |
+|---------------|----------|----------------|-----------------------------------------------------------------------|
+| `type`     	| Yes      | String         | Must be `image`                                                       |
+| `key`      	| Yes      | String         | See [key](#key)                                                       |
+| `required` 	| No       | Boolean        | Whether the property must be specified by the user, `true` by default |
+| `allowUpload` | No       | Boolean        | See [allowUpload](#allow-upload)                                      |
 
 #### Studio Pro UI
 
 When the component is defined as follows:
 
 ```xml
-<property key="bgImage" type="image" required="false">
+<property key="bgImage" type="image" required="false" allowUpload="true" >
 	<caption>Background Image</caption>
 	<description>Image shown blurred in a background</description>
 </property>
@@ -699,22 +712,29 @@ Then the Studio Pro UI for the property appears like this:
 
 ### File {#file}
 
-The file property type allows a user to configure a file from an object that is a specialization of **System.File**. It is passed as a [`DynamicValue<FileValue>`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#filevalue) prop to a client component.
+The file property type allows a user to configure and edit a file from and to an object that is a specialization of **System.File**. It is passed as a [`EditableFileValue<FileValue>`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#editable-file-value) prop to a client component.
+
+The user can use the optional attribute [`allowUpload`](#allow-upload) with default value `false` to use the legacy [`Dynamic<FileValue>`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#filevalue) prop. Beware of behavioral differences based on the `allowUpload` attribute.
+
+{{% alert color="warning" %}} Legacy DynamicValue types for file and image properties are deprecated and will be removed at Mendix 12. Use allowUpload="true" to migrate to the new editable types before Mendix 12. {{% /alert %}}
+
+{{% alert color="info" %}} Editable types are not supported for Native as of now. {{% /alert %}}
 
 #### XML Attributes
 
-| Attribute | Required | Attribute Type | Description     |
-|-----------|----------|----------------|-----------------|
-| `type`    | Yes      | String         | Must be `file`  |
-| `key`     | Yes      | String         | See [key](#key) |
+| Attribute     | Required | Attribute Type | Description                      |
+|---------------|----------|----------------|----------------------------------|
+| `type`        | Yes      | String         | Must be `file`                   |
+| `key`         | Yes      | String         | See [key](#key)                  |
+| `allowUpload` | No       | Boolean        | See [allowUpload](#allow-upload) |
 
 #### Studio Pro UI
 
 When the property is defined as follows:
 
 ```xml
 
-<property key="file" type="file" required="false">
+<property key="file" type="file" required="false" allowUpload="true">
 	<caption>File</caption>
 	<description>Sample text file</description>
 </property>
