Merge branch 'development' into Maria_Studio_RN

Author: MariaShaposhnikova

content/en/docs/apidocs-mxsdk/apidocs/data-hub-apis.md

@@ -44,3 +44,5 @@ The API includes the following:
 ## 4 Transform API {#transform}
 
 Mendix users who deploy to *non-Mendix clouds* can make use of the [Transform API](https://datahub-spec.s3.eu-central-1.amazonaws.com/transform.html) to generate the request body for the Registration API. The Transform API reconfigures information from the *dependencies.json* file into the correct fields. For an example API, see the [Preparing Your Service Details Using the Transform API](/data-hub/data-hub-catalog/register-data/#transform-api) section of *How to Register OData Resources in the Data Hub Catalog*.
+
+V4 compatibility for the **Transform API** is accessible via the [Data Hub Registration API](https://datahub-spec.s3.eu-central-1.amazonaws.com/registration_v4.html) under the **Endpoints** section.

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

@@ -48,7 +48,7 @@ If a widget uses a TabIndex prop [system property](/apidocs-mxsdk/apidocs/plugga
 
 ### 4.1 ActionValue {#actionvalue}
 
-ActionValue is used to represent actions, like the [On click](/refguide/on-click-event/#on-click) property of an action button. For any action except **Do nothing**, your component will receive a value adhering to the following interface. For **Do nothing** it will receive `undefined`. The `ActionValue` prop appears like this:
+`ActionValue` is used to represent actions, like the [On click](/refguide/on-click-event/#on-click) property of an action button. For any action except **Do nothing**, your component will receive a value adhering to the following interface. For **Do nothing** it will receive `undefined`. The `ActionValue` prop appears like this:
 
 ```ts
 export interface ActionValue {
@@ -68,7 +68,7 @@ The method `execute` triggers the action. It returns nothing and does not guaran
 
 ### 4.2 DynamicValue {#dynamic-value}
 
-DynamicValue is used to represent values that can change over time and is used by many property types. It is defined as follows:
+`DynamicValue` is used to represent values that can change over time and is used by many property types. It is defined as follows:
 
 ```ts
 export type DynamicValue<X> =
@@ -97,7 +97,7 @@ Though the type definition above looks complex, it is fairly simply to use becau
 
 ### 4.3 EditableValue {#editable-value}
 
-EditableValue is used to represent values 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 values 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> {
@@ -137,7 +137,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 attribute is of the Boolean or enumeration [types](/refguide/attributes/#type).
 
-### 4.4 IconValue {#icon-value}
+### 4.4 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:
+
+```ts
+export interface ModifiableValue<T> {
+	readonly status: ValueStatus;
+	readonly readOnly: boolean;
+    
+	readonly value: Option<T>;
+	readonly setValue: (value: Option<T>) => void;
+	readonly validation: Option<string>;
+	readonly setValidator: (validator?: (value: Option<T>) => Option<string>) => void;
+}
+```
+
+The type received by the component for the association property depends on the allowed association types:
+* If only references are allowed, the component receives a `ReferenceValue` defined as `ModifiableValue<ObjectItem> & { type: "Reference" };`
+* If only reference sets are allowed, the client gets a `ReferenceSetValue` defined as `ModifiableValue<ObjectItem[]> & { type: "ReferenceSet" };`
+
+Finally, when both association types are allowed the type is a union of `ReferenceValue` and `ReferenceSetValue` and the widget should check the `type` to determine if a reference or reference set is configured and act accordingly in the code. Checking the type will also [narrow](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#handbook-content) to the correct type in TypeScript.
+
+```ts
+if (association.value === undefined) {
+	return "None";
+}
+
+if (association.type === "Reference") {
+	return textTemplate.get(association.value);
+} else {
+	return association.value.map((objectItem) => textTemplate.get(objectItem)).join(",");
+}
+```
+
+`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`, `ModifiableValue` 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 the `setValue` function.  The `value` contains an `ObjectItem` or an `ObjectItem[]` based on the configured association. The `ObjectItem` can be passed to the `get` function of any [linked property value](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis-list-values/#linked-values) which is linked to the selectable object's datasource. 
+
+When setting a value, the `ObjectItem`(s) must be items from the selectable object's data source. 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.
+
+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 executed 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.
+
+### 4.5 IconValue {#icon-value}
 
 `DynamicValue<IconValue>` is used to represent icons: small pictograms in the Mendix platform. Those can be static or dynamic file- or font-based images. An icon can only be configured through an [icon](/apidocs-mxsdk/apidocs/pluggable-widgets-property-types/#attribute) property. `IconValue` is defined as follows:
 
@@ -164,7 +208,7 @@ export type IconValue = WebIcon | NativeIcon;
 
 In practice, `WebIcon` and `NativeIcon` are usually passed to a `Icon` component provided by Mendix, since this provides a convenient way of handling all types of icons at once. For more information on `Icon`, see the [Icon](#icon) section below.
 
-### 4.5 ImageValue{#imagevalue}
+### 4.6 ImageValue{#imagevalue}
 
 `DynamicValue<ImageValue>` is used to represent static or dynamic images. An image can be configured only through an [image](/apidocs-mxsdk/apidocs/pluggable-widgets-property-types/#image) property. `ImageValue` is defined as follows:
 
@@ -180,7 +224,7 @@ export type ImageValue = WebImage | NativeImage;
 
 `NativeImage` can be passed to a `mendix/components/native/Image` component provided by Mendix for native widgets. `WebImage` can be passed to react-dom’s `img` component.
 
-### 4.6 FileValue {#filevalue}
+### 4.7 FileValue {#filevalue}
 
 `DynamicValue<FileValue>` is used to represent files. A file can be configured only through a [file](/apidocs-mxsdk/apidocs/pluggable-widgets-property-types/#file) property. `FileValue` is defined as follows:
 
@@ -191,7 +235,7 @@ export interface FileValue {
 }
 ```
 
-### 4.7 List values{#list-values}
+### 4.8 List values{#list-values}
 
 `ListValue` is used to represent a list of objects for the [datasource](/apidocs-mxsdk/apidocs/pluggable-widgets-property-types/#datasource) property. See [List Values](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis-list-values/) for more information about usage of `ListValue` and associated property values.
 

content/en/docs/apidocs-mxsdk/apidocs/pluggable-widgets/pluggable-widgets-client-apis/pluggable-widgets-client-apis-list-values.md

@@ -334,7 +334,7 @@ More specifically, the `status` property functions as follows:
 	* In other cases, the `items` is `undefined`. This happens if a page is still being loaded or if the previous state was `ValueStatus.Unavailable`.
 
 
-## 3 Linked Property Values
+## 3 Linked Property Values {#linked-values}
 
 ### 3.1 ListActionValue {#listactionvalue}
 

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

@@ -48,6 +48,7 @@ This defines a property's type. A `type` must be one of the following:
 	* [textTemplate](#texttemplate)
 	* [action](#action)
 	* [attribute](#attribute)
+	* [association](#association)
 	* [object](#object)
 	* [file](#file)
 	* [datasource](#datasource)
@@ -463,7 +464,7 @@ If a `dataSource` attribute is not specified, the client will receive an `Editab
 
 When a `dataSource` attribute is specified and configured by the user, it is passed as a [`ListAttributeValue`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis-list-values/#listattributevalue). For more information, see the [Datasource](#datasource) section below.
 
-#### 4.4.1 XML 
+#### 4.4.1 XML Attributes
 
 | Attribute    | Required | Attribute Type | Description                                                  |
 | ------------ | -------- | -------------- | ------------------------------------------------------------ |
@@ -516,24 +517,74 @@ Then the Studio Pro UI for the property appears like this:
 
 {{< figure src="/attachments/apidocs-mxsdk/apidocs/pluggable-widgets/pluggable-widgets-property-types/attribute.png" >}}
 
-### 4.5 Object{#object}
+### 4.5 Association{#association}
 
-The object property type allows to create an arbitrary list of properties.
+The association property type allows a widget to work directly with both reading and writing associations between entities. Depending on the widget's purposes, a widget should define association types it supports.
+
+The client will receive an `ModifiableValue<T>` where `T` depends on the configured `<associationType>`. For more information, see the [ModifiableValue](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#modifiable-value) section of *Client APIs Available to Pluggable Widgets*.
 
 #### 4.5.1 XML Attributes
 
+| Attribute           | Required | Attribute Type | Description                                                                                                        |
+|---------------------| -------- | -------------- |--------------------------------------------------------------------------------------------------------------------|
+| `type`              | Yes      | String         | Must be `association`                                                                                              |
+| `key`               | Yes      | String         | See [key](#key)                                                                                                    |
+| `required`          | No       | Boolean        | Decides if the property must be specified by the user, `true` by default                                           |
+| `selectableObjects` | Yes      | Property Path  | The path to a Datasource property that will provide selectable objects for the association                         | 
+
+#### 4.5.2 XML Elements
+
+`<associationTypes>` (required) — This element encapsulates `<associationType>` elements which declare supported association types available while configuring the association property in the Studios.
+
+`<associationType>` (required one or more) — this element defines the allowed attribute type in the `name` attribute.
+
+| Supported Attribute Types | Corresponding Types Client Components Receive |
+|---------------------------|-----------------------------------------------|
+| `Reference`               | `ReferenceValue`                              |
+| `ReferenceSet`            | `ReferenceSetValue`                           |
+
+#### 4.5.3 Studio Pro UI
+
+When the property is defined as follows:
+
+```xml
+<property key="ref" type="association" selectableObjects="objectsDatasource">
+    <caption>Reference</caption>
+    <description>Reference</description>
+    <associationTypes>
+        <associationType name="Reference"/>
+        <associationType name="ReferenceSet"/>
+    </associationTypes>
+</property>
+
+<property key="objectsDatasource" type="datasource" isList="true">
+    <caption>Selectable objects</caption>
+    <description/>
+</property>
+```
+
+Then the Studio Pro UI for the property appears like this:
+
+{{< figure src="/attachments/apidocs-mxsdk/apidocs/pluggable-widgets/pluggable-widgets-property-types/association.png" >}}
+
+### 4.6 Object{#object}
+
+The object property type allows to create an arbitrary list of properties.
+
+#### 4.6.1 XML Attributes
+
 | Attribute | Required | Attribute Type | Description                                                                                                                                                          |
 | ---------- | -------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `type`     | Yes      | String         | Must be `object`                                                                                                                                                     |
 | `key`      | Yes      | String         | See [key](#key) |
 | `isList`   | Yes      | Boolean        | Must be `true`                                                                                                                                                       |
 | `required` | No       | Boolean        | This decides if the user is required to specify items in the list, `true` by default |
 
-#### 4.5.2 XML Elements
+#### 4.6.2 XML Elements
 
 `<properties>` (required) — This encapsulates the list or properties to be configured. For more information on property groups, see the [Property Groups](/apidocs-mxsdk/apidocs/pluggable-widgets/#property-groups) section of *Pluggable Widgets API*. Properties must be grouped by `<propertyGroup>` elements. Nested object properties are not supported.
 
-#### 4.5.3 Studio Pro UI
+#### 4.6.3 Studio Pro UI
 
 When the property is defined as follows:
 
@@ -560,18 +611,18 @@ Then the Studio Pro UI for the property appears like this:
 
 {{< figure src="/attachments/apidocs-mxsdk/apidocs/pluggable-widgets/pluggable-widgets-property-types/object.png" >}}
 
-### 4.6 File {#file}
+### 4.7 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.
 
-#### 4.6.1 XML Attributes
+#### 4.7.1 XML Attributes
 
 | Attribute  | Required | Attribute Type | Description |
 | ---------- | -------- | -------------- | ----------- |
 | `type`     | Yes      | String         | Must be `file` |
 | `key`      | Yes      | String         | See [key](#key)  |
 
-#### 4.6.2 Studio Pro UI
+#### 4.7.2 Studio Pro UI
 
 When the property is defined as follows:
 
@@ -587,7 +638,7 @@ Then the Studio Pro UI for the property appears like this:
 
 {{< figure src="/attachments/apidocs-mxsdk/apidocs/pluggable-widgets/pluggable-widgets-property-types/file.png" >}}
 
-### 4.7 Datasource {#datasource}
+### 4.8 Datasource {#datasource}
 
 The datasource property allows widgets to work with object lists. The client component will receive value prop of type [`ListValue`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis-list-values/#listvalue) and may be used with [`action`](#action), [`attribute`](#attribute), [`expression`](#expression), [`text template`](#texttemplate) and [`widgets`](#widgets) properties. See [Data Sources](/refguide/data-sources/#list-widgets) for available data source types.
 
@@ -597,7 +648,7 @@ If no data source has been configured by the user, any properties that are linke
 Only list datasources are supported, therefore specifying `isList="true"` is required.
 {{% /alert %}}
 
-#### 4.7.1 XML Attributes
+#### 4.8.1 XML Attributes
 
 | Attribute  | Required | Attribute Type | Description |
 | ---------- | -------- | -------------- | ----------- |
@@ -606,7 +657,7 @@ Only list datasources are supported, therefore specifying `isList="true"` is req
 | `isList`   | Yes      | Boolean        | Must be `true` |
 | `required` | No       | Boolean        | This decides if the user is required to specify a datasource, `true` by default |
 
-#### 4.7.2 Studio Pro UI
+#### 4.8.2 Studio Pro UI
 
 When the property is defined as follows:
 

content/en/docs/appstore/app-services/text-analytics.md

@@ -200,7 +200,7 @@ The **TokenEndpoint** constant provides a valid endpoint of security token servi
 
 #### 3.3.1 CreateDominantLanguageDetector
 
-The **CreateDominantLanguageDetector** microflow takes **text** (String) and **languageCode** (String) as input parameters to create DominantLanguageDetector as a return object from the back-end service.
+The **CreateDominantLanguageDetector** microflow takes **text** (String) as input parameters to create DominantLanguageDetector as a return object from the back-end service.
 
 {{< figure src="/attachments/appstore/app-services/text-analytics/createdominantlanguagedetector.png" alt="createdominantlanguagedetector" >}}
 
@@ -404,7 +404,7 @@ If you deploy your app in your own environment, you need to configure the licens
 
 ## 4 Usage
 
-### 4.1 Performing Language Detection in Your Browser
+### 4.1 Performing Dominant Language Detection in Your Browser
 
 Use the **CreateDominantLanguageDetector** microflow and the **DetectDominantLanguage** nanoflow to perform language detection. Follow these steps to configure the language detection:
 
@@ -415,7 +415,7 @@ Use the **CreateDominantLanguageDetector** microflow and the **DetectDominantLan
 
         {{< figure src="/attachments/appstore/app-services/text-analytics/call-createdominantlanguagedetector-microflow.png" alt="call-createdominantlanguagedetector-microflow" >}}
 
-   4.  Right-click the create object activity and select **Set $detector as return value** in the pop-up menu.
+   4.  Right-click the microflow activity you just added and select **Set $detector as return value** in the pop-up menu.
 
        {{< figure src="/attachments/appstore/app-services/text-analytics/createdominantlanguagedetector-nanoflow.png" alt="createdominantlanguagedetector-nanoflow" >}}