Skip to content

[WTF-2552] Update docs with file and image props with upload capabilities #10751

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
stdagkalakis wants to merge 1 commit into
base: development
Choose a base branch
from
Open

[WTF-2552] Update docs with file and image props with upload capabilities #10751

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 45 additions & 0 deletions ...apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-client-apis/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
48 changes: 34 additions & 14 deletions ...sdk/apidocs/studio-pro-11/pluggable-widgets/pluggable-widgets-property-types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down