Skip to content

Commit 9376d04

Browse files
mlapondermlaponder
committed
Add docs for single object datasource property
1 parent f3ae75b commit 9376d04

2 files changed

Lines changed: 72 additions & 8 deletions

File tree

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

Lines changed: 72 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,8 @@ This defines a property's type. A `type` must be one of the following:
5959
* [object](#object)
6060
* [file](#file)
6161
* [datasource](#datasource)
62+
* [List data source](#list-datasource)
63+
* [Single object data source](#single-object-datasource)
6264
* [selection](#selection)
6365

6466
### XML Elements
@@ -746,23 +748,19 @@ Then the Studio Pro UI for the property appears like this:
746748

747749
### Datasource {#datasource}
748750

749-
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), [`association`](#association), [`expression`](#expression), [`text template`](#texttemplate), and [`widgets`](#widgets) properties. See [Data Sources](/refguide/data-sources/#list-widgets) for available data source types.
751+
The datasource property allows widgets to work with data from the Mendix Platform. It comes in two variants controlled by the `isList` attribute: a **list data source** (`isList="true"`) for working with collections of objects, and a **single object data source** (`isList="false"`) for working with a single object.
750752

751753
If no data source has been configured by the user, any properties that are linked to the datasource property are automatically omitted from the props passed to the client component (even if they are marked as required).
752754

753-
{{% alert color="warning" %}}
754-
Only list datasources are supported, therefore specifying `isList="true"` is required.
755-
{{% /alert %}}
756-
757755
#### XML Attributes
758756

759757
| Attribute | Required | Attribute Type | Description |
760758
|----------------|----------|----------------|------------------------------------------------------------------------------------------------------------|
761759
| `type` | Yes | String | Must be `datasource` |
762760
| `key` | Yes | String | See [key](#key) |
763-
| `isList` | Yes | Boolean | Must be `true` |
761+
| `isList` | Yes | Boolean | `true` for a list data source, `false` for a single object data source |
764762
| `required` | No | Boolean | This decides if the user is required to specify a datasource, `true` by default |
765-
| `defaultType` | No | String | Default type for the property, supported values are `Database`, `Microflow`, `Nanoflow`, and `Association` |
763+
| `defaultType` | No | String | Default type for the property, see [Default Data Sources](#data-source-defaults) |
766764
| `defaultValue` | No | String | Default value for the property, see [Default Data Sources](#data-source-defaults) |
767765

768766
##### Data Source Defaults {#data-source-defaults}
@@ -780,7 +778,22 @@ The format of `defaultValue` depends on the chosen `defaultType`:
780778
| `Database` `Association` | Entity Path | `ModuleName.EntityName` or `ModuleName.A/ModuleName.A_B/ModuleName.B` |
781779
| `Microflow` `Nanoflow` | Document ID | `ModuleName.DocumentName` |
782780

783-
#### Studio Pro UI
781+
#### List Data Source {#list-datasource}
782+
783+
A list data source (`isList="true"`) allows a widget to work with a collection of objects. The client component receives a prop of type [`ListValue`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis-list-values/#listvalue). See [Data Sources](/refguide/data-sources/#list-widgets) for available data source types.
784+
785+
A list data source may be linked to [`action`](#action), [`attribute`](#attribute), [`association`](#association), [`expression`](#expression), [`text template`](#texttemplate), and [`widgets`](#widgets) properties using the `dataSource` attribute on those properties. When linked to a list data source, those properties receive their list-aware counterparts in the client component:
786+
787+
| Property type | Client type when linked to list data source |
788+
|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
789+
| `action` | [`ListActionValue`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis-list-values/#listactionvalue) |
790+
| `attribute` | [`ListAttributeValue<T>`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis-list-values/#listattributevalue) |
791+
| `association` | [`ListReferenceValue` or `ListReferenceSetValue`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis-list-values/#listassociationvalue) |
792+
| `expression` | [`ListExpressionValue<T>`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis-list-values/#listexpressionvalue) |
793+
| `textTemplate` | [`ListExpressionValue<string>`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis-list-values/#listexpressionvalue) |
794+
| `widgets` | [`ListWidgetValue`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis-list-values/#listwidgetvalue) |
795+
796+
##### Studio Pro UI
784797

785798
When the property is defined as follows:
786799

@@ -795,6 +808,53 @@ Then the Studio Pro UI for the property appears like this:
795808

796809
{{< figure src="/attachments/apidocs-mxsdk/apidocs/pluggable-widgets/pluggable-widgets-property-types/datasource.png" class="no-border" >}}
797810

811+
#### Single Object Data Source {#single-object-datasource}
812+
813+
{{% alert color="info" %}}
814+
The single object data source was introduced in Mendix [11.11](/releasenotes/studio-pro/11.11/).
815+
{{% /alert %}}
816+
817+
A single object data source (`isList="false"`) allows a widget to work with a single object. The client component receives a prop of type [`DynamicValue<ObjectItem>`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#dynamic-value).
818+
819+
A widget may have at most one single object data source property.
820+
821+
The available source types differ from list data sources:
822+
823+
| Platform | Available source types |
824+
|----------|-----------------------------------------------------------|
825+
| Web | Context, Microflow, Nanoflow, Listen to widget |
826+
| Native | Context, Microflow, Nanoflow |
827+
828+
A single object data source may be linked to [`action`](#action), [`attribute`](#attribute), [`association`](#association), [`expression`](#expression), [`text template`](#texttemplate), and [`widgets`](#widgets) properties using the `dataSource` attribute on those properties. When linked to a single object data source, those properties receive the same types as unlinked properties — there are no list-aware variants:
829+
830+
| Property type | Client type when linked to single object data source |
831+
|-----------------|-----------------------------------------------------------|
832+
| `action` | [`ActionValue`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#action-value) |
833+
| `attribute` | [`EditableValue<T>`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#editable-value) |
834+
| `association` | `ReferenceValue` or `ReferenceSetValue` |
835+
| `expression` | [`DynamicValue<T>`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#dynamic-value) |
836+
| `textTemplate` | [`DynamicValue<string>`](/apidocs-mxsdk/apidocs/pluggable-widgets-client-apis/#dynamic-value) |
837+
| `widgets` | `ReactNode` |
838+
839+
{{% alert color="warning" %}}
840+
[`selection`](#selection) properties may only be linked to a list data source, not a single object data source.
841+
{{% /alert %}}
842+
843+
##### Studio Pro UI
844+
845+
When the property is defined as follows:
846+
847+
```xml
848+
<property key="data" type="datasource" isList="false" required="false">
849+
<caption>Data source</caption>
850+
<description />
851+
</property>
852+
```
853+
854+
Then the Studio Pro UI for the property appears like this:
855+
856+
{{< figure src="/attachments/apidocs-mxsdk/apidocs/pluggable-widgets/pluggable-widgets-property-types/datasource-single-object.png" class="no-border" >}}
857+
798858
### Selection {#selection}
799859

800860
{{% alert color="info" %}}
@@ -813,6 +873,10 @@ The selection property allows a widget to read and set a selection that can be u
813873
| `defaultValue` | No | String (Expression) | Default value for the property |
814874
| `onChange` | No | Property Path | The path to an [`action`](#action) property that will be run by the Mendix Platform when the selection is changed by the widget |
815875

876+
{{% alert color="warning" %}}
877+
The `dataSource` attribute must refer to a [list data source](#list-datasource). Linking a selection property to a single object data source is not supported.
878+
{{% /alert %}}
879+
816880
#### XML Elements
817881

818882
`<selectionTypes>` (required) — This element encapsulates `<selectionType>` elements which declare supported selection types available while configuring the selection property in Studio Pro.

‎static/attachments/apidocs-mxsdk/apidocs/pluggable-widgets/pluggable-widgets-property-types/datasource-single-object.png‎

39.6 KB
Loading

0 commit comments

Comments
 (0)