Update Image and File properties, add EditableImageValue, EditableFileValue sections

Author: stdagkalakis

content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-client-apis/_index.md

@@ -161,6 +161,51 @@ There is a way to use more the convenient `displayValue`  and `setTextValue` whi
 
 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)
+
+Thisr 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:

content/en/docs/apidocs-mxsdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-property-types.md

@@ -26,6 +26,16 @@ 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.
 
+#### AllowUpload (Optional) {#allow-upload}
+
+This optional attribute is only applicable for properties of type [file](#file) and [image](#image) and has a default value of `false`. By setting this attribute to `true` a user can use the upload capabilities by passing  `EditableFileValue<FileValue>` and `EditableImageValue<ImageValue>` as props to a client component. Using `false` is used for legacy `DynamicValue<File>` and `DynamicValue<ImageValue>`.
+
+{{% alert color="warning" %}}
+Optional attribute `allowUpload` will be deprecated as of Mx 12. After Mx 12 such `file` and `image` will have by default editing capabilities and users will not be able to use the legacy behavior.
+
+After Mx 12, the attribute won't be taken into account during the property evaluation, and legasy functionality won't be available.
+{{% /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. See the [Images Reference Guide](/refguide/images/) for more information about supported image formats.
+
+The user can use the optional attribute [`allowUpload`](#allow-upload) with default value `false` to use the legasy [`Dynamic<FileValue>`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#filevalue) prop. Beware of behavioral differences based on the `allowUpload` attribute.
 
 {{% alert color="warning" %}}
-GIF images are not supported in native mobile apps on Android devices.
+Optional attribute `allowUpload` will be deprecated as of Mx 12. After Mx 12 such `image` will have by default editing capabilities and users will not be able to use the legacy behavior.
 {{% /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 legasy [`Dynamic<FileValue>`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#filevalue) prop. Beware of behavioral differences based on the `allowUpload` attribute.
+
+{{% alert color="warning" %}}
+Optional attribute `allowUpload` will be deprecated as of Mx 12. After Mx 12 such `file` will have by default editing capabilities and users will not be able to use the legacy behavior.
+{{% /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>