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..fcb9e81228d 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 @@ -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 { @@ -145,22 +145,67 @@ export interface EditableValue { A component will receive `EditableValue` 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 { + 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) + +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 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..24ea2702f08 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,7 +26,15 @@ 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 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" %}} +The optional 'allowUpload' attribute on Image and File properties, which enables editing, will be deprecated starting with Mendix 12. After Mendix 12, such properties will have editing capabilities by default. Be aware of behavioral differences based on the 'allowUpload' attribute. +{{% /alert %}} + +#### Type (Required) This defines a property's type. A `type` must be one of the following: @@ -257,26 +265,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. For more information about supported image formats, see the [Images Reference Guide](/refguide/images/). + +The user can use the optional attribute [`allowUpload`](#allow-upload) with default value `false` to use the legacy [`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. +The optional 'allowUpload' attribute on Image and File properties, which enables editing, will be deprecated starting with Mendix 12. After Mendix 12, such properties will have editing capabilities by default. Be aware of behavioral differences based on the 'allowUpload' attribute. {{% /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 +710,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 legacy [`Dynamic`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#filevalue) prop. Beware of behavioral differences based on the `allowUpload` attribute. + +{{% alert color="warning" %}} +The optional 'allowUpload' attribute on Image and File properties, which enables editing, will be deprecated starting with Mendix 12. After Mendix 12, such properties will have editing capabilities by default. Be aware of behavioral differences based on the 'allowUpload' attribute. +{{% /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 +732,7 @@ When the property is defined as follows: ```xml - + File Sample text file