Skip to content

Commit afc5129

Browse files
cyrngfmauNeko
cyrng
and
fmauNeko
authored
feat(metadata): add optional editor hints for metadata (#370)
Co-authored-by: Florian Maunier <fmaunier@kuzzle.io>
1 parent ac878ad commit afc5129

File tree

14 files changed

+447
-69
lines changed

14 files changed

+447
-69
lines changed

‎doc/2/concepts/metadatadetails/clock-picker.png‎

117 KB
Loading

‎doc/2/concepts/metadatadetails/dropdown-of-values.png‎

111 KB
Loading

‎doc/2/concepts/metadatadetails/index.md‎

Lines changed: 252 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,252 @@
1+
---
2+
code: false
3+
type: page
4+
title: Metadata details
5+
description: structure of metadataDetails
6+
---
7+
8+
# Metadata details
9+
10+
Defining metadata details is a way to enhance the user experience by improving the metadata management workflow on an asset or a device. There are multiple features you can use :
11+
12+
- [Translation](#translations-mandatory) (**_mandatory_**)
13+
- [Group](#group-optional) (**_optional_**)
14+
- [Editor hint](#editor-hint-optional) (change UI elements) (**_optional_**)
15+
16+
## Translations (_mandatory_)
17+
18+
This property allows to add a localized user-friendly name and description to the metadata. Those will be automatically substitued according to the user's language.
19+
20+
**Example**
21+
22+
```js
23+
{
24+
metadataMappings: {
25+
company: { type: "keyword" },
26+
},
27+
metadataDetails: {
28+
locales: {
29+
en: {
30+
friendlyName: "Manufacturer",
31+
description: "The company that manufactured the plane",
32+
},
33+
fr: {
34+
friendlyName: "Fabricant",
35+
description: "L'entreprise qui a fabriqué l'avion",
36+
},
37+
},
38+
},
39+
}
40+
```
41+
42+
## Group (_optional_)
43+
44+
This property allows to group metadata together.
45+
46+
First, create a `metadataGroups` object at the same level as `metadataDetails`, using the group's name as a key and mapping them to their localization details. Then in the `metadataDetails` object, specify the group of the metadata by using the `group` property.
47+
48+
**Example**
49+
50+
```js
51+
{
52+
metadataMappings: {
53+
company: { type: "keyword" },
54+
},
55+
metadataDetails: {
56+
company: {
57+
group: "companyInfo",
58+
},
59+
},
60+
metadataGroups: {
61+
companyInfo: {
62+
locales: {
63+
en: {
64+
groupFriendlyName: "Company Information",
65+
description: "All company related informations",
66+
},
67+
fr: {
68+
groupFriendlyName: "Informations sur l'entreprise",
69+
description: "Toutes les informations relatives a l'entreprise",
70+
},
71+
},
72+
},
73+
},
74+
}
75+
```
76+
77+
## Editor hint (_optional_)
78+
79+
This property allows to specify the frontend whether it should display a custom widget to edit the metadata, like a dropdown of values, a clock picker or date picker with or without time, make a metadata read-only, and so on.
80+
81+
You have to set the enum type associated to the hint you want and fill the properties with your values.
82+
83+
This is the list of the available hints:
84+
85+
- [Read only](#read-only)
86+
- [Dropdown of values](#dropdown-of-values)
87+
- [Date/Datetime/Clock picker](#datedatetimeclock-picker)
88+
89+
<h3 id="read-only" style="color: #e94e77">Read only <a href="#read-only" class="heading-anchor-link">#</a></h3>
90+
91+
The read-only feature allows to prevent users to edit a metadata.
92+
93+
**NOTE:** The readOnly property can be set with **any** Enum type.
94+
95+
Enum type: `BASE`
96+
97+
:warning: Set to BASE if you **only** want the readOnly property.
98+
99+
<table>
100+
<thead>
101+
<tr>
102+
<th style="background-color: #e94e77" colspan="4" align="center">PROPERTIES</th>
103+
</tr>
104+
<tr>
105+
<th>Name</th>
106+
<th>Type</th>
107+
<th>Description</th>
108+
<th>Optional</th>
109+
</tr>
110+
</thead>
111+
<tbody>
112+
<tr>
113+
<td>readOnly</td>
114+
<td><code>boolean</code></td>
115+
<td>It displays or not the edit button</td>
116+
<td>Yes</td>
117+
</tr>
118+
</tbody>
119+
</table>
120+
121+
**Example**
122+
123+
```js
124+
{
125+
metadataMappings: {
126+
network: { type: "keyword" },
127+
},
128+
metadataDetails: {
129+
network: {
130+
editorHint: {
131+
type: EditorHintEnum.BASE,
132+
readOnly: true,
133+
},
134+
},
135+
}
136+
},
137+
```
138+
139+
<h3 id="dropdown-of-values" style="color: #e94e77">Dropdown of values <a href="#dropdown-of-values" class="heading-anchor-link">#</a></h3>
140+
141+
The dropdown feature allows to display a list of values to choose in a dropdown.
142+
143+
Enum type: `OPTION_SELECTOR`
144+
145+
<table>
146+
<thead>
147+
<tr>
148+
<th style="background-color: #e94e77" colspan="4" align="center">PROPERTIES</th>
149+
</tr>
150+
<tr>
151+
<th>Name</th>
152+
<th>Type</th>
153+
<th>Description</th>
154+
<th>Optional</th>
155+
</tr>
156+
</thead>
157+
<tbody>
158+
<tr>
159+
<td>values</td>
160+
<td><code>string[] | number[] | boolean[]</code></td>
161+
<td>A list that represents all the values displayed in a dropdown.</td>
162+
<td>No</td>
163+
</tr>
164+
<tr>
165+
<td>customValueAllowed</td>
166+
<td><code>boolean</code></td>
167+
<td>Allows users to add custom values.</td>
168+
<td>Yes</td>
169+
</tr>
170+
</tbody>
171+
</table>
172+
173+
**Example**
174+
175+
```js
176+
{
177+
metadataMappings: {
178+
company: { type: "keyword" },
179+
},
180+
metadataDetails: {
181+
company: {
182+
editorHint: {
183+
type: EditorHintEnum.OPTION_SELECTOR,
184+
values: ["red", "blue"],
185+
customValueAllowed: true,
186+
},
187+
}
188+
},
189+
},
190+
```
191+
192+
**Visual**
193+
194+
![dropdown-of-values](./dropdown-of-values.png)
195+
196+
<h3 id="datedatetimeclock-picker" style="color: #e94e77">Date/Datetime/Clock picker <a href="#datedatetimeclock-picker" class="heading-anchor-link">#</a></h3>
197+
198+
This feature allows to display either a date picker with or without a time picker, or a clock picker.
199+
200+
Enum type: `DATETIME`
201+
202+
<table>
203+
<thead>
204+
<tr>
205+
<th style="background-color: #e94e77" colspan="4" align="center">PROPERTIES</th>
206+
</tr>
207+
<tr>
208+
<th>Name</th>
209+
<th>Type</th>
210+
<th>Description</th>
211+
<th>Optional</th>
212+
</tr>
213+
</thead>
214+
<tbody>
215+
<tr>
216+
<td>date</td>
217+
<td><code>boolean</code></td>
218+
<td>If true, displays a date picker, otherwise displays a clock picker.</td>
219+
<td>No</td>
220+
</tr>
221+
<tr>
222+
<td>time</td>
223+
<td><code>boolean</code></td>
224+
<td>If `date` is true, setting this to true will add time picking to the date picker.</td>
225+
<td>Yes</td>
226+
</tr>
227+
</tbody>
228+
</table>
229+
230+
**Example**
231+
232+
```js
233+
{
234+
metadataMappings: {
235+
date: { type: "date" },
236+
},
237+
metadataDetails: {
238+
date: {
239+
editorHint: {
240+
type: EditorHintEnum.DATETIME,
241+
date: true,
242+
time: true,
243+
customTimeZoneAllowed: true,
244+
},
245+
}
246+
},
247+
},
248+
```
249+
250+
**Visual**
251+
252+
![clock-picker](./clock-picker.png)

‎doc/2/concepts/models/index.md‎

Lines changed: 29 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,11 @@ A sensor model contains the following information:
2222
- `decoder`: (optional) instance of a [Decoder] to normalize the data
2323
- `metadataMappings`: (optional) metadata mappings (See [Collection Mappings](https://docs.kuzzle.io/core/2/guides/main-concepts/data-storage/#collection-mappings))
2424
- `defaultMetadata`: (optional) default metadata values
25-
- `metadataDetails`: (optional) Metadata group and translations. You can use it to keep consistency on translations between your apps
26-
- `metadataGroups`: (optional) Groups list with translations for group name. You can use it to group metadatas by their concerns
25+
- `metadataDetails`: (optional) Translations, metadata group and editor hint.
26+
- Translations: you can use it to keep consistency on translations between your apps.
27+
- Group: metadata can be displayed grouped, you need to define `metadataGroups` to use it.
28+
- Editor hint: it unlock functionalities depending on the metadata type you define.
29+
- `metadataGroups`: (optional) Map of group names to their translations. You can use it to group metadata.
2730

2831
It is possible to create new models on the Kuzzle IoT Platform using either:
2932

@@ -58,7 +61,6 @@ The API also allows to:
5861
- list available models `device-manager/models:listDevices`
5962
- get a model `device-manager/models:getDevices`
6063

61-
6264
## Measure Model
6365

6466
A measure model contains the following information:
@@ -77,27 +79,27 @@ It is possible to create new models on the Kuzzle IoT Platform using either:
7779

7880
```typescript
7981
await sdk.query({
80-
controller: 'device-manager/models',
81-
action: 'writeMeasure',
82-
body: {
83-
type: 'light',
84-
valuesMappings: {
85-
light: { type: 'integer' },
82+
controller: "device-manager/models",
83+
action: "writeMeasure",
84+
body: {
85+
type: "light",
86+
valuesMappings: {
87+
light: { type: "integer" },
88+
},
89+
valuesDetails: {
90+
light: {
91+
en: {
92+
friendlyName: "Light intensity",
93+
unit: "lux",
8694
},
87-
valuesDetails: {
88-
light: {
89-
en: {
90-
friendlyName: 'Light intensity',
91-
unit: 'lux',
92-
},
93-
fr: {
94-
friendlyName: 'Intensité lumineuse',
95-
unit: 'lux',
96-
},
97-
},
95+
fr: {
96+
friendlyName: "Intensité lumineuse",
97+
unit: "lux",
9898
},
9999
},
100-
});
100+
},
101+
},
102+
});
101103
```
102104

103105
The API also allows to:
@@ -115,9 +117,12 @@ An asset model contains the following information:
115117
- `engineGroup`: engine group to which the model belongs.
116118
- `measures`: received measurements
117119
- `metadataMappings`: (optional) metadata mappings (See [Collection Mappings](https://docs.kuzzle.io/core/2/guides/main-concepts/data-storage/#collection-mappings))
118-
- `defaultMetadata`: (optional) default metadata values-
119-
- `metadataDetails`: (optional) Metadata group and translations. You can use it to keep consistency on translations between your apps
120-
- `metadataGroups`: (optional) Groups list with translations for group name. You can use it to group metadatas by their concerns
120+
- `defaultMetadata`: (optional) default metadata values-
121+
- `metadataDetails`: (optional) Translations, metadata group and editor hint.
122+
- Translations: you can use it to keep consistency on translations between your apps.
123+
- Group: metadata can be displayed grouped, you need to define `metadataGroups` to use it.
124+
- Editor hint: it unlock functionalities depending on the metadata type you define.
125+
- `metadataGroups`: (optional) Map of group names to their translations. You can use it to group metadata.
121126
- `tooltipModels`: (optional) Tooltip model list, each containing labels and tooltip content to be shown. You can use it to create templates that displays relevant information in dashboards
122127

123128
It is possible to create new models on the Kuzzle IoT Platform using either:

‎doc/2/controllers/models/update-asset/index.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ Method: PUT
4848
description: string;
4949
};
5050
};
51-
readOnly?: boolean;
51+
editorHint?: BaseEditorHint | OptionsSelectorDefinition | DatetimeEditorHint;
5252
};
5353
*/
5454
},
@@ -137,8 +137,8 @@ Method: PUT
137137

138138
- `metadataMappings`: Mappings of the metadata in Elasticsearch format
139139
- `defaultValues`: Default values for the metadata
140-
- `metadataDetails`: Metadata group and translations
141-
- `metadataGroups`: Groups list with translations for group name
140+
- `metadataDetails`: Translations, metadata group and editor hint
141+
- `metadataGroups`: Groups list with translations for group name
142142
- `tooltipModels`: Tooltip model list, containing each labels and tooltip content to display
143143
- `measures`: Array of measure definition. Each item defines `type` and `name` properties for the measure.
144144

@@ -164,4 +164,4 @@ Method: PUT
164164

165165
## Errors
166166

167-
Updating an asset with metadata mappings can cause conflicts, in this case a [ MappingsConflictsError ](../../../errors/mappings-conflicts/index.md) will be thrown with the HTTP code **409**.
167+
Updating an asset with metadata mappings can cause conflicts, in this case a [ MappingsConflictsError ](../../../errors/mappings-conflicts/index.md) will be thrown with the HTTP code **409**.

‎doc/2/controllers/models/write-asset/index.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ Method: POST
4040
},
4141
"metadataDetails": {
4242
/*
43-
Metadata details including tanslations and group.
43+
Metadata details including tanslations, group and editor hint.
4444
[name: string]: {
4545
group?: string;
4646
locales: {
@@ -49,7 +49,7 @@ Method: POST
4949
description: string;
5050
};
5151
};
52-
readOnly?: boolean;
52+
editorHint?: BaseEditorHint | OptionsSelectorDefinition | DatetimeEditorHint;
5353
};
5454
*/
5555
},
@@ -133,8 +133,8 @@ Method: POST
133133
- `model`: Asset model name
134134
- `metadataMappings`: Mappings of the metadata in Elasticsearch format
135135
- `defaultValues`: Default values for the metadata
136-
- `metadataDetails`: Metadata group and translations
137-
- `metadataGroups`: Groups list with translations for group name
136+
- `metadataDetails`: Translations, metadata group, and editor hint (See [ MetadataDetails ](../../../concepts/metadatadetails/index.md))
137+
- `metadataGroups`: Groups list with translations for group name
138138
- `tooltipModels`: Tooltip model list, containing each labels and tooltip content to display
139139
- `measures`: Array of measure definition. Each item define a `type` and `name` properties for the measure.
140140

@@ -160,4 +160,4 @@ Method: POST
160160

161161
## Errors
162162

163-
Writing an asset with metadata mappings can cause conflicts, in this case a [ MappingsConflictsError ](../../../errors/mappings-conflicts/index.md) will be thrown with the HTTP code **409**.
163+
Writing an asset with metadata mappings can cause conflicts, in this case a [ MappingsConflictsError ](../../../errors/mappings-conflicts/index.md) will be thrown with the HTTP code **409**.

0 commit comments

Comments
 (0)