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 index 047ef5ad815..8fb5caa5f38 100644 --- 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 @@ -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 { + readonly status: ValueStatus; + readonly readOnly: boolean; + + readonly validation: Option; + setValidator: (validator?: (value: Option) => Option) => void; + + readonly value: Option; + setValue: (value: Option) => 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 extends EditableFileValue { + setThumbnailSize: (width: Option, height: Option) => 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 index e3bd5dba28c..78c24410537 100644 --- 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,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` and `EditableImageValue` as props to a client component. Using `false` is used for legacy `DynamicValue` and `DynamicValue`. + +{{% 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` 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`](/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`](/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 - + Background Image Image shown blurred in a background @@ -699,14 +712,21 @@ 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`](/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`](/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`](/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 @@ -714,7 +734,7 @@ When the property is defined as follows: ```xml - + File Sample text file