Skip to content

Commit 3c94783

Browse files
madsrasmussenmadsrasmussen
committed
add property editor + picker data source docs
1 parent c90827b commit 3c94783

File tree

5 files changed

+316
-3
lines changed

5 files changed

+316
-3
lines changed

‎17/umbraco-cms/customizing/property-editors/composition/property-editor-data-source.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# Property Editor Data Source
22

3-
A Property Editor Data Source is a way to provide data to a Property Editor UI. This allows for reuse of the same Property Editor UI but with different data sources.
3+
A Property Editor Data Source is a way to provide data to a Property Editor UI. This allows for reuse of the same UI but with different data sources.
44

5-
Data Sources are an opt-in feature for a Property Editor UI and need to be explicitly enabled. When enabled it allows for other extensions to register Data Sources that can be selected for the Property Editor UI as long as the Data Source Type is supported by the Property Editor UI.
5+
Data Sources are an opt-in feature for a Property Editor UI and need to be explicitly enabled. When enabled it allows for other extensions to register Data Sources that can be selected for the Property Editor UI as long as the Data Source Type is supported by the UI.
66

77
## Enable Data Source Support
88

@@ -78,5 +78,5 @@ interface UmbPropertyEditorUiElement extends HTMLElement {
7878
The Data Source configuration can be accessed through the `config` property of the Property Editor UI element together with the UI and Schema config.
7979

8080
## Built-in Data Source Types
81-
* `picker` - Used by Property Editors that pick entities, e.g. the Entity Data Picker Property Editor.
81+
* [picker](../property-editor-data-source-types/picker.md) - Used by Property Editors that pick entities, e.g. the Entity Data Picker Property Editor.
8282

‎17/umbraco-cms/customizing/property-editors/property-editor-data-source-types/README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Picker Data Source Type
2+
3+
The `picker` Data Source Type is used by Property Editors that pick entities, e.g. the built-in [Entity Data Picker Property Editor](../../../fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/entity-data-picker.md).
4+
5+
## Register a Picker Data Source
6+
7+
**Data Source Manifest**
8+
9+
```typescript
10+
{
11+
type: 'propertyEditorDataSource',
12+
dataSourceType: 'picker'
13+
alias: 'Umb.PropertyEditorDataSource.MyPickerDataSource',
14+
name: 'My Picker Data Source',
15+
api: () => import('./my-picker-data-source.js'),
16+
meta: {
17+
label: 'My Data Source',
18+
description: 'A good description of the data source',
19+
icon: 'icon-database',
20+
},
21+
},
22+
```
23+
24+
The new Picker supports two types of data structures:
25+
* [Collection Data](./collection-data.md)
26+
* [Tree Data](./tree-data.md)

‎17/umbraco-cms/customizing/property-editors/property-editor-data-source-types/picker-collection-data-source.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
## Picker Collection Data Source
2+
3+
The interface below is simplified for clarity and omits return types and args. See full interfaces in the [UI Api Documentation](https://apidocs.umbraco.com/v17/ui-api/modules/packages_core_picker-data-source.html)
4+
5+
```typescript
6+
interface UmbPickerPropertyEditorCollectionDataSource {
7+
requestCollection();
8+
requestItems();
9+
search?();
10+
setConfig?();
11+
getConfig?();
12+
}
13+
```
14+
15+
### Example
16+
```typescript
17+
import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
18+
import type { UmbCollectionFilterModel, UmbCollectionItemModel } from '@umbraco-cms/backoffice/collection';
19+
import type {
20+
UmbPickerCollectionDataSource,
21+
UmbPickerSearchableDataSource,
22+
} from '@umbraco-cms/backoffice/picker-data-source';
23+
import type { UmbSearchRequestArgs } from '@umbraco-cms/backoffice/search';
24+
25+
interface ExampleCollectionItemModel extends UmbCollectionItemModel {
26+
isPickable: boolean;
27+
}
28+
29+
export class MyCustomPickerCollectionPropertyEditorDataSource
30+
extends UmbControllerBase
31+
implements UmbPickerCollectionDataSource<ExampleCollectionItemModel>, UmbPickerSearchableDataSource
32+
{
33+
collectionPickableFilter = (item: ExampleCollectionItemModel) => item.isPickable;
34+
35+
async requestCollection(args: UmbCollectionFilterModel) {
36+
const data = {
37+
items: customItems,
38+
total: customItems.length,
39+
};
40+
41+
return { data };
42+
}
43+
44+
async requestItems(uniques: Array<string>) {
45+
const items = customItems.filter((x) => uniques.includes(x.unique));
46+
return { data: items };
47+
}
48+
49+
async search(args: UmbSearchRequestArgs) {
50+
const items = customItems.filter((item) => item.name?.toLowerCase().includes(args.query.toLowerCase()));
51+
const total = items.length;
52+
53+
const data = {
54+
items,
55+
total,
56+
};
57+
58+
return { data };
59+
}
60+
}
61+
62+
export { ExampleCustomPickerCollectionPropertyEditorDataSource as api };
63+
64+
const customItems: Array<ExampleCollectionItemModel> = [
65+
{
66+
unique: '1',
67+
entityType: 'example',
68+
name: 'Example 1',
69+
icon: 'icon-shape-triangle',
70+
isPickable: true,
71+
},
72+
{
73+
unique: '2',
74+
entityType: 'example',
75+
name: 'Example 2',
76+
icon: 'icon-shape-triangle',
77+
isPickable: false,
78+
},
79+
{
80+
unique: '3',
81+
entityType: 'example',
82+
name: 'Example 3',
83+
icon: 'icon-shape-triangle',
84+
isPickable: true,
85+
},
86+
];
87+
88+
```

‎17/umbraco-cms/customizing/property-editors/property-editor-data-source-types/picker-tree-data-source.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
## Picker Tree Data Source
2+
3+
The interface below is simplified for clarity and omits return types and args. See full interfaces in the [UI Api Documentation](https://apidocs.umbraco.com/v17/ui-api/modules/packages_core_picker-data-source.html)
4+
5+
6+
```typescript
7+
interface UmbPickerPropertyEditorCollectionDataSource {
8+
requestTreeRoot();
9+
requestTreeRootItems();
10+
requestTreeItemsOf();
11+
requestTreeItemAncestors();
12+
requestItems();
13+
search?();
14+
setConfig?();
15+
getConfig?();
16+
}
17+
```
18+
19+
20+
### Example
21+
```typescript
22+
import { UmbControllerBase } from '@umbraco-cms/backoffice/class-api';
23+
import type {
24+
UmbPickerSearchableDataSource,
25+
UmbPickerTreeDataSource,
26+
} from '@umbraco-cms/backoffice/picker-data-source';
27+
import type { UmbSearchRequestArgs, UmbSearchResultItemModel } from '@umbraco-cms/backoffice/search';
28+
import type { UmbTreeChildrenOfRequestArgs, UmbTreeItemModel } from '@umbraco-cms/backoffice/tree';
29+
30+
export class ExampleCustomPickerTreePropertyEditorDataSource
31+
extends UmbControllerBase
32+
implements UmbPickerTreeDataSource, UmbPickerSearchableDataSource
33+
{
34+
treePickableFilter: (treeItem: UmbTreeItemModel) => boolean = (treeItem) =>
35+
!!treeItem.unique && treeItem.entityType === 'example';
36+
37+
searchPickableFilter: (searchItem: UmbSearchResultItemModel) => boolean = (searchItem) =>
38+
!!searchItem.unique && searchItem.entityType === 'example';
39+
40+
async requestTreeRoot() {
41+
const root = {
42+
unique: null,
43+
name: 'Examples',
44+
icon: 'icon-folder',
45+
hasChildren: true,
46+
entityType: 'example-root',
47+
isFolder: true,
48+
};
49+
50+
return { data: root };
51+
}
52+
53+
async requestTreeRootItems() {
54+
const rootItems = customItems.filter((item) => item.parent.unique === null);
55+
56+
const data = {
57+
items: rootItems,
58+
total: rootItems.length,
59+
};
60+
61+
return { data };
62+
}
63+
64+
async requestTreeItemsOf(args: UmbTreeChildrenOfRequestArgs) {
65+
const items = customItems.filter(
66+
(item) => item.parent.entityType === args.parent.entityType && item.parent.unique === args.parent.unique,
67+
);
68+
69+
const data = {
70+
items: items,
71+
total: items.length,
72+
};
73+
74+
return { data };
75+
}
76+
77+
async requestTreeItemAncestors() {
78+
// TODO: implement when needed
79+
return { data: [] };
80+
}
81+
82+
async requestItems(uniques: Array<string>) {
83+
const items = customItems.filter((x) => uniques.includes(x.unique));
84+
return { data: items };
85+
}
86+
87+
async search(args: UmbSearchRequestArgs) {
88+
const result = customItems.filter((item) => item.name.toLowerCase().includes(args.query.toLowerCase()));
89+
90+
const data = {
91+
items: result,
92+
total: result.length,
93+
};
94+
95+
return { data };
96+
}
97+
}
98+
99+
export { ExampleCustomPickerTreePropertyEditorDataSource as api };
100+
101+
const customItems: Array<UmbTreeItemModel> = [
102+
{
103+
unique: '1',
104+
entityType: 'example',
105+
name: 'Example 1',
106+
icon: 'icon-shape-triangle',
107+
parent: { unique: null, entityType: 'example-root' },
108+
isFolder: false,
109+
hasChildren: false,
110+
},
111+
{
112+
unique: '2',
113+
entityType: 'example',
114+
name: 'Example 2',
115+
icon: 'icon-shape-triangle',
116+
parent: { unique: null, entityType: 'example-root' },
117+
isFolder: false,
118+
hasChildren: false,
119+
},
120+
{
121+
unique: '3',
122+
entityType: 'example',
123+
name: 'Example 3',
124+
icon: 'icon-shape-triangle',
125+
parent: { unique: null, entityType: 'example-root' },
126+
isFolder: false,
127+
hasChildren: false,
128+
},
129+
{
130+
unique: '4',
131+
entityType: 'example',
132+
name: 'Example 4',
133+
icon: 'icon-shape-triangle',
134+
parent: { unique: '6', entityType: 'example-folder' },
135+
isFolder: false,
136+
hasChildren: false,
137+
},
138+
{
139+
unique: '5',
140+
entityType: 'example',
141+
name: 'Example 5',
142+
icon: 'icon-shape-triangle',
143+
parent: { unique: '6', entityType: 'example-folder' },
144+
isFolder: false,
145+
hasChildren: false,
146+
},
147+
{
148+
unique: '6',
149+
entityType: 'example-folder',
150+
name: 'Example Folder 1',
151+
parent: { unique: null, entityType: 'example-root' },
152+
isFolder: true,
153+
hasChildren: true,
154+
},
155+
];
156+
```

‎17/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/entity-data-picker.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Entity Data Picker
2+
3+
`Schema Alias: Umbraco.Plain.Json` // TODO: update when alias is final
4+
5+
`UI Alias: Umb.PropertyEditorUi.EntityDataPicker`
6+
7+
`Returns: IEnumerable<string>`
8+
9+
`Supported Data Source Types:` [picker](../../../../customizing/property-editors/property-editor-data-source-types/README.md)
10+
11+
The Entity Data Picker property editor allows editors to pick one or more entities from a configurable data source. The selected entities are stored as an array of strings, where each string represents the ID of the selected entity.
12+
13+
### With Models Builder
14+
15+
```csharp
16+
@if(Model.MyDataItems.Any()){
17+
<ul>
18+
@foreach(var item in Model.MyDataItems){
19+
<li>@item</li>
20+
}
21+
</ul>
22+
}
23+
```
24+
25+
### Without Models Builder
26+
27+
```csharp
28+
@if(Model.HasValue("MyDataItems"))
29+
{
30+
var myDataItems = Model.Value<IEnumerable<string>>("MyDataItems");
31+
<ul>
32+
@foreach(var item in myDataItems)
33+
{
34+
<li>@item</li>
35+
}
36+
</ul>
37+
}
38+
```
39+
40+
### Content Delivery API
41+
```json
42+
// Missing example
43+
```

0 commit comments

Comments
 (0)