Skip to content

Commit c32653b

Browse files
SumoSourabhSumoSourabh
authored
CP-10070 Better UI generation documentation (#508)
PR URL: #508
1 parent dfb8911 commit c32653b

21 files changed

+509
-17
lines changed

‎docs/docs/References/.pages‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ arrange:
55
- Plugin_Operations.md
66
- Schemas.md
77
- Schemas_and_Autogenerated_Classes.md
8+
- Dynamic_UI_Schema_Configuration
89
- Platform_Libraries.md
910
- Logging.md
1011
- Workflows.md

‎docs/docs/References/Dynamic_UI_Schema_Configuration/.pages‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
arrange:
2+
- Overview.md
3+
- Text_Area.md
4+
- Hidden_Fields.md
5+
- Collapsible_Section.md
6+
- Validation_Messages.md

‎docs/docs/References/Dynamic_UI_Schema_Configuration/Collapsible_Section.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Collapsible Section
2+
Collapsible Section provides plugin developers capability to create properties that can be collapsed or expanded as per
3+
user choice. `Collapsible Section` allows to reduce number of properties shown on the UI at a time to help better
4+
understand the configuration.
5+
6+
The `collapsible` and `expanded` accepts a boolean value that helps in collapsing all the properties of the `array`
7+
and `object` type.
8+
9+
## Schema Configuration
10+
11+
### Attributes
12+
| Attribute | Value | Description |
13+
|:-----------:|:-------:|:---------------------------------------------------------------------------------------------------------------:|
14+
| collapsible | boolean | If `true`, the property will be allowed to collapse as per user choice. |
15+
| expanded | boolean | If `true`, the property will be expanded by default. The attribute is used when `collapsible` is set to `true`. |
16+
17+
### Where
18+
- As a Sub-schema of [dxFormProperties](../Schemas.md#dxformproperties), for `array` and `object` type properties.
19+
20+
### Applicable Data Types
21+
- object
22+
- array
23+
24+
### Usage
25+
```json title="Schema" hl_lines="4 5 6 7"
26+
{
27+
"<Property_Name>": {
28+
"type": "object",
29+
"dxFormProperties": {
30+
"collapsible": <boolean true or false>,
31+
"expanded": <boolean true or false>
32+
}
33+
}
34+
}
35+
36+
```
37+
38+
## Examples
39+
40+
???+ example "Examples"
41+
=== "Example 1"
42+
`userDetails` is an object property which is allowed to collapse and is collapsed by default. `userName` and `password` are part of the collapsed section.
43+
```json
44+
{
45+
"userDetails": {
46+
"type": "object",
47+
"dxFormProperties": {
48+
"collapsible": true,
49+
"expanded": false
50+
},
51+
"properties": {
52+
"userName": {
53+
"type": "string"
54+
},
55+
"password": {
56+
"type": "string"
57+
}
58+
}
59+
}
60+
}
61+
```
62+
![Example1](images/Dynamic_UI_Collapse_Object.gif)
63+
=== "Example 2"
64+
`addressDetails` is an array property which is allowed to collapse and is expanded by default. Each array item with `pinCode` and `number` is allowed to collapse and is collapsed by default.
65+
```json
66+
{
67+
"addressDetails": {
68+
"type": "array",
69+
"dxFormProperties": {
70+
"collapsible": true,
71+
"expanded": true
72+
},
73+
"items": {
74+
"type": "object",
75+
"dxFormProperties": {
76+
"collapsible": true,
77+
"expanded": false
78+
},
79+
"properties": {
80+
"pinCode": {
81+
"type": "string"
82+
},
83+
"number": {
84+
"type": "string"
85+
}
86+
}
87+
}
88+
}
89+
}
90+
```
91+
![Example2](images/Dynamic_UI_Collapse_Array.gif)

‎docs/docs/References/Dynamic_UI_Schema_Configuration/Hidden_Fields.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Hidden Properties
2+
Hidden Properties provides plugin developers capability to provide properties that will be shown to user once certain conditions or
3+
checks are successful based on user inputs. `Hidden Properties` help plugin developers control the flow of user inputs by
4+
showing only the required properties at first and show the remaining properties based on the user input afterward.
5+
6+
The `hideExpression` accepts an expression that evaluates to a boolean value. The expression can access values from
7+
other properties. Access values from other properties as below:
8+
9+
??? abstract "model.<property_name\>"
10+
!!! example inline ""
11+
```json
12+
{
13+
"X": "",
14+
"Y": ""
15+
}
16+
```
17+
- Use the `model.<property_name>` when the properties are `string`, `boolean`, `number` or `integer`.
18+
- To hide Y based on X, use `model.X` or `model?.X`
19+
??? abstract "field.parent.<N\>.parent.model?.<property_name\>"
20+
Use the `field.parent.<N>.parent.model?.<property_name>` when the properties are `object` or `array`.
21+
=== "Object Schema"
22+
!!! example inline ""
23+
```json
24+
{
25+
"X": "",
26+
"Y": {
27+
"Z": ""
28+
}
29+
}
30+
```
31+
- To hide Y (object itself), use `field.parent.model?.X`.
32+
- To hide Z based on X, use `field.parent.parent.model?.X`.
33+
=== "Array Schema"
34+
!!! example inline ""
35+
```json
36+
{
37+
"X": "",
38+
"Y": [
39+
{
40+
"Z": ""
41+
}
42+
]
43+
}
44+
```
45+
- To hide Y (array object) based on X, use `field.parent.model?.X`
46+
- To hide Z based on X, use `field.parent.parent.parent.model?.X`
47+
??? abstract "field.parent.<N\>.parent.model?.<root_names\>?.<property_name\>"
48+
!!! example inline ""
49+
```json
50+
{
51+
"A": {
52+
"B": ""
53+
},
54+
"X": {
55+
"Y": ""
56+
}
57+
}
58+
```
59+
- Use the `field.parent.<N>.parent.model?.<root_names>?.<property_name>` when the properties have different root object.
60+
- To hide Y based on B, use `field.parent.parent.model?.A?.B`
61+
62+
!!! info
63+
`parent.<N>.parent` - Parent repeated N times as per JSON structure
64+
65+
## Schema Configuration
66+
67+
### Attributes
68+
| Attribute | Value | Description |
69+
|:--------------:|:-------:|:--------------------------------------------------------------------:|
70+
| hideExpression | boolean | If the value evaluates to true, the property is not shown in the UI. |
71+
72+
### Where
73+
- As a Sub-schema of [dxFormProperties](../Schemas.md#dxformproperties), for all data types property.
74+
75+
### Applicable Data Types
76+
- string
77+
- integer
78+
- number
79+
- array
80+
- object
81+
- boolean
82+
83+
### Usage
84+
```json title="Schema" hl_lines="4 5 6"
85+
{
86+
"<Property_Name>": {
87+
"type": "string",
88+
"dxFormProperties": {
89+
"hideExpression": "<expression that evaluates to a boolean value>"
90+
}
91+
}
92+
}
93+
```
94+
!!! warning
95+
The expression works across a definition only. Plugin developers will not be able to use properties from multiple
96+
definitions as defined in [schemas](../Schemas_and_Autogenerated_Classes.md). For example, a property from
97+
[linkedSourceDefinition](../Schemas_and_Autogenerated_Classes.md#linkedsourcedefinition) can not be used
98+
in [snapshotDefinition](../Schemas_and_Autogenerated_Classes.md#snapshotdefinition).
99+
100+
## Examples
101+
102+
???+ example "Examples"
103+
=== "Expressions"
104+
| Expression | Description |
105+
|:---------------------------------------------------:|:---------------------------------------------------------------------------------:|
106+
| `!model.userName` | Returns true if the userName property is EMPTY. |
107+
| `model.booleanFlag` | Returns true or false based on the booleanFlag property |
108+
| `model.backupType === 'PRIMARY'` | Returns true if the backupType property is PRIMARY. |
109+
| `model.backupType !== 'PRIMARY' && !model.userName` | Return true if backupType property is not PRIMARY and userName property is EMPTY. |
110+
=== "Common Root Object"
111+
`password` is a string property which will be shown in the UI if `userName` is present and not empty.
112+
```json
113+
{
114+
"userName": {
115+
"type": "string"
116+
},
117+
"password": {
118+
"type": "string",
119+
"dxFormProperties": {
120+
"hideExpression": "!model.userName"
121+
}
122+
}
123+
}
124+
```
125+
![Common Root](images/Dynamic_UI_Common_Root.gif)
126+
=== "Different Root Object"
127+
`password` is a string property which will be shown in the UI if `userName` is present and not empty.
128+
```json
129+
{
130+
"userDetails": {
131+
"type": "object",
132+
"properties": {
133+
"userName": {
134+
"type": "string"
135+
}
136+
}
137+
},
138+
"securityDetails": {
139+
"type": "object",
140+
"properties": {
141+
"password": {
142+
"type": "string",
143+
"dxFormProperties": {
144+
"hideExpression": "!field.parent.parent.model?.userDetails?.userName"
145+
}
146+
}
147+
}
148+
}
149+
}
150+
```
151+
![Different Root](images/Dynamic_UI_Different_Root.gif)

‎docs/docs/References/Dynamic_UI_Schema_Configuration/Overview.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Overview
2+
3+
Before Delphix Engine 14.0.0.0 release, virtualization SDK only supported basic UI configuration which made UI configuration
4+
for plugin defined schema complex and cluttered. Plugin developers were not able to modify the behaviour of Delphix Engine UI
5+
based on the plugin defined schema.
6+
7+
From 14.0.0.0 onwards, plugin developers can modify the Delphix Engine UI based on the plugin defined schema.
8+
9+
`Dynamic UI Schema Configuration` creates Delphix Engine UI which helps user better understand the plugin configuration
10+
and also helps plugin developers control the flow of the configuration.
11+
12+
# Schema Attribute
13+
14+
Plugin developers need to add a single attribute [dxFormProperties](../Schemas.md#dxformproperties) to any field they would like
15+
to control the UI. Other attributes like `rows`, `hideExpression` can be provided to [dxFormProperties](../Schemas.md#dxformproperties)
16+
to create a specific type of Dynamic UI behaviour.
17+
18+
Table below lists all the allowed attributes within [dxFormProperties](../Schemas.md#dxformproperties) to create UI.
19+
20+
| Attribute | Description |
21+
|:---------------------------------------------:|:--------------------------------------------------------------------|
22+
| [Collapsible Section](Collapsible_Section.md) | Allows to collapse and expand `object` and `array` type properties. |
23+
| [Hidden Fields](Hidden_Fields.md) | Allows to hide properties based on conditions. |
24+
| [Text Area](Text_Area.md) | Convert any string field to multi line text input property. |
25+
| [Validation Messages](Validation_Messages.md) | Add custom validation messages to user inputs. |
26+
27+
# Version Compatibility
28+
29+
| Dynamic UI Schema Configuration | Earliest Supported vSDK Version | Latest Supported vSDK Version | Earliest Supported DE Version | Latest Supported DE Version |
30+
|:---------------------------------------------:|:--------------------------------------------:|:-----------------------------------------------:|:-----------------------------:|:-----------------------------------------------------------------:|
31+
| [Collapsible Section](Collapsible_Section.md) | [4.0.2](https://pypi.org/project/dvp/4.0.2/) | [Latest Release](https://pypi.org/project/dvp/) | 14.0.0.0 | [Latest Release](https://cd.delphix.com/docs/latest/new-features) |
32+
| [Hidden Fields](Hidden_Fields.md) | [4.0.2](https://pypi.org/project/dvp/4.0.2/) | [Latest Release](https://pypi.org/project/dvp/) | 14.0.0.0 | [Latest Release](https://cd.delphix.com/docs/latest/new-features) |
33+
| [Text Area](Text_Area.md) | [4.0.2](https://pypi.org/project/dvp/4.0.2/) | [Latest Release](https://pypi.org/project/dvp/) | 14.0.0.0 | [Latest Release](https://cd.delphix.com/docs/latest/new-features) |
34+
| [Validation Messages](Validation_Messages.md) | [4.0.2](https://pypi.org/project/dvp/4.0.2/) | [Latest Release](https://pypi.org/project/dvp/) | 14.0.0.0 | [Latest Release](https://cd.delphix.com/docs/latest/new-features) |
35+

‎docs/docs/References/Dynamic_UI_Schema_Configuration/Text_Area.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Text Area
2+
Text Area Property provides plugin developers capability to create properties in Delphix engine UI which is used
3+
for `multi line text` input. `Text Area` allows users to enter large amount of text, for example a shell script or comments.
4+
5+
All `string` type properties can be converted to `Text Area` properties by providing `rows` configuration to adjust the height of the property.
6+
7+
* The number of visible lines or `rows` count does not limit the number of input lines.
8+
* A user can input `n` number of lines but at a time UI will only show lines as provided in `rows` configuration.
9+
* A user can scroll to see all the lines.
10+
11+
## Schema Configuration
12+
13+
### Attributes
14+
| Attribute | Value | Description |
15+
|:---------:|:------:|:---------------------------------------------------------------:|
16+
| rows | number | Specifies the height and number of visible lines for text area. |
17+
18+
### Where
19+
* As a Sub-schema of [dxFormProperties](../Schemas.md#dxformproperties), for `string` type property.
20+
21+
### Applicable Data Types
22+
* string
23+
24+
### Usage
25+
```json title="Schema" hl_lines="4 5 6"
26+
{
27+
"<Property_Name>": {
28+
"type": "string",
29+
"dxFormProperties": {
30+
"rows": 5
31+
}
32+
}
33+
}
34+
```
35+
36+
## Examples
37+
???+ example "Examples"
38+
=== "Example 1"
39+
`userName` is a string property which will be shown in the UI as a Single line.
40+
```json
41+
{
42+
"userName": {
43+
"type": "string"
44+
}
45+
}
46+
```
47+
![Example1](images/Dynamic_UI_Simple_String.png)
48+
=== "Example 2"
49+
`textAreaField` is a string property which will be shown in the UI as a Text Area with 20 visible lines.
50+
```json
51+
{
52+
"textAreaField": {
53+
"type": "string",
54+
"dxFormProperties": {
55+
"rows": 20
56+
}
57+
}
58+
}
59+
```
60+
![Example2](images/Dynamic_UI_Text_Area.gif)

0 commit comments

Comments
 (0)