Skip to content

Commit aaafc8e

Browse files
Sobyt483Sobyt483
authored
feat: add generic-ui docs (#19)
1 parent cd909fa commit aaafc8e

File tree

2 files changed

+271
-2
lines changed

2 files changed

+271
-2
lines changed

‎README.md‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,36 @@ This library helps you to setup FE application using `@openmfp/portal-ui-lib` by
55

66
![Build Status](https://github.com/platform-mesh/portal-ui-lib/actions/workflows/pipeline.yaml/badge.svg)
77

8-
## Build
8+
## Getting Started
9+
10+
### Build
911

1012
Run `npm run build` to build the project. The build artifacts will be stored in the `dist/` directory.
1113

12-
## Running unit tests
14+
### Running unit tests
1315

1416
Run `nom run test` to execute the unit tests via Jest.
17+
18+
## Generic UI Feature
19+
20+
There is a possibility to reuse generic ui components in form of web components, without building the micro frontend.
21+
Please follow our [generic ui guide](./docs/readme-generic-ui.md) for this task.
22+
23+
### Angular Configuration
24+
25+
Configure the angular build process (in the `angular.json` file) to include the content of the assets
26+
from `@platform-mesh/portal-ui-lib` library into the project assets, as shown below:
27+
28+
```
29+
{
30+
// ... the rest of the angular.json configuration
31+
"assets": [
32+
{
33+
"glob": "**",
34+
"input": "node_modules/@platform-mesh/portal-ui-lib/assets/",
35+
"output": "/assets/"
36+
},
37+
]
38+
// ... other configured assets
39+
}
40+
```

‎docs/readme-generic-ui.md‎

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
# Generic UI Components
2+
3+
A reusable set of Angular components for building consistent and maintainable micro frontends across the application.
4+
This library provides generic implementations for common UI patterns like list views and detail views.
5+
6+
## Web Components
7+
8+
The generic ui consists of the following components:
9+
10+
- `generic-list-view`: Component for displaying and managing lists of resources, as well as creation, and deletion of the resources.
11+
- `generic-detail-view`: Component for displaying individual resource.
12+
13+
## Configuration
14+
15+
### Generic List View
16+
17+
In order to use the generic list view, you need to adjust the node’s `content-configuration` to include the following:
18+
19+
- node properties
20+
21+
- `"url": "/assets/platform-mesh-portal-ui-wc.js#generic-list-view"`: pointing to the web component.
22+
- `"webcomponent": {"selfRegistered": true}`: indicating Luigi framework to register as a webcomponent.
23+
- `"navigationContext": "accounts"`: providing the navigation context for easy navigation between the entity and list views.
24+
25+
- context resource definition `"context"`
26+
27+
- in the `"resourceDefinition"` the given fields need to be specified: `group, plural, singular, kind, scope, namespace` describing
28+
properties of the resource.
29+
- in the `"ui"` part of the `"resourceDefinition"` we can specify `"logoUrl"` for the resource as well as the definitions of the
30+
corresponding views
31+
32+
- `"listView"`: contains `"fields"` definitions that will be translated to the columns of the table list view, `"label"` corresponds to
33+
the column name, whereas `"property"` is a json path of the property of a resource to be read.
34+
- `"detailView"`: similarly describes the fields which are to show up on the detailed view.
35+
- `"createView`: section additionally provides possibility to add the `"required"` flag to the filed definition,
36+
indicating that the field needs to be provided while creating an instance of that resource, with the `"values": ["account"]`
37+
there is a possibility to provide a list of values to select from. Also, it's possible to specify a GraphQL query to retrieve a dynamic list of values to select from using the `"dynamicValuesDefinition"`. You need to provide `"gqlQuery"` and `"operation"`, as well as `"key"` - a JSON path to the property that will be used as the displayed value, and `"value"` — a JSON path to the actual value.
38+
39+
#### Example Content Configuration for an Accounts Node
40+
Below is an example content-configuration for an accounts node using the generic list view.
41+
42+
```json
43+
{
44+
"name": "accounts",
45+
"luigiConfigFragment": {
46+
"data": {
47+
"nodes": [
48+
{
49+
"pathSegment": "accounts",
50+
"navigationContext": "accounts",
51+
"label": "Accounts",
52+
"entityType": "main",
53+
"loadingIndicator": {
54+
"enabled": false
55+
},
56+
"keepSelectedForChildren": true,
57+
"url": "/assets/platform-mesh-portal-ui-wc.js#generic-list-view",
58+
"webcomponent": {
59+
"selfRegistered": true
60+
},
61+
"context": {
62+
"resourceDefinition": {
63+
"group": "core.platform-mesh.io",
64+
"plural": "accounts",
65+
"singular": "account",
66+
"kind": "Account",
67+
"scope": "Cluster",
68+
"namespace": null,
69+
"ui": {
70+
"logoUrl": "https://www.kcp.io/icons/logo.svg",
71+
"listView": {
72+
"fields": [
73+
{
74+
"label": "Name",
75+
"property": "metadata.name"
76+
},
77+
{
78+
"label": "Display Name",
79+
"property": "spec.displayName"
80+
},
81+
{
82+
"label": "Type",
83+
"property": "spec.type"
84+
}
85+
]
86+
},
87+
"detailView": {
88+
"fields": [
89+
{
90+
"label": "Description",
91+
"property": "spec.description"
92+
},
93+
{
94+
"label": "Display Name",
95+
"property": "spec.displayName"
96+
}
97+
]
98+
},
99+
"createView": {
100+
"fields": [
101+
{
102+
"label": "Name",
103+
"property": "metadata.name",
104+
"required": true
105+
},
106+
{
107+
"label": "Type",
108+
"property": "spec.type",
109+
"required": true,
110+
"values": ["account"]
111+
},
112+
{
113+
"label": "Display Name",
114+
"property": "spec.displayName"
115+
},
116+
{
117+
"label": "Description",
118+
"property": "spec.description"
119+
},
120+
{
121+
"label": "City",
122+
"property": "spec.city",
123+
"required": true,
124+
"dynamicValuesDefinition": {
125+
"operation": "cities",
126+
"gqlQuery": "subscription { cities { data { id name } } }",
127+
"value": "data.id",
128+
"key": "data.name",
129+
}
130+
}
131+
]
132+
}
133+
}
134+
}
135+
},
136+
"children": [
137+
{
138+
"pathSegment": ":accountId",
139+
"hideFromNav": true,
140+
"keepSelectedForChildren": false,
141+
"defineEntity": {
142+
"id": "account",
143+
"contextKey": "accountId",
144+
"dynamicFetchId": "account"
145+
},
146+
"context": {
147+
"accountId": ":accountId",
148+
"resourceId": ":accountId"
149+
}
150+
}
151+
]
152+
}
153+
]
154+
}
155+
}
156+
}
157+
```
158+
159+
### Generic Detail View
160+
161+
To use the generic detail view, update the node’s `content-configuration` to include the following:
162+
163+
- node properties
164+
165+
- `"url": "/assets/platform-mesh-portal-ui-wc.js#generic-detail-view"`: pointing to the web component
166+
- `"webcomponent": {"selfRegistered": true}`: indicating Luigi framework to register as a webcomponent
167+
168+
- context resource definition
169+
170+
- because below provided example is a child of the list view node's child indicated by `"entityType": "main.account"`, the context data is
171+
inherited automatically via Luigi feature
172+
173+
#### Example Content Configuration for an Account Resource
174+
Below is a sample content-configuration for displaying an account resource using the generic detail view:
175+
176+
```json
177+
{
178+
"name": "overview",
179+
"luigiConfigFragment": {
180+
"data": {
181+
"nodes": [
182+
{
183+
"entityType": "main.account",
184+
"pathSegment": "dashboard",
185+
"label": "Dashboard",
186+
"url": "/assets/platform-mesh-portal-ui-wc.js#generic-detail-view",
187+
"webcomponent": {
188+
"selfRegistered": true
189+
},
190+
"defineEntity": {
191+
"id": "dashboard"
192+
},
193+
"compound": {
194+
"children": []
195+
}
196+
}
197+
]
198+
}
199+
}
200+
}
201+
202+
```
203+
204+
In case the detail view is an independent node provide context data:
205+
206+
```json
207+
{
208+
"context": {
209+
"resourceDefinition": {
210+
"group": "core.platform-mesh.io",
211+
"plural": "accounts",
212+
"singular": "account",
213+
"kind": "Account",
214+
"scope": "Cluster",
215+
"namespace": null,
216+
"ui": {
217+
"logoUrl": "https://www.kcp.io/icons/logo.svg",
218+
"detailView": {
219+
"fields": [
220+
{
221+
"label": "Description",
222+
"property": "spec.description"
223+
},
224+
{
225+
"label": "Display Name",
226+
"property": "spec.displayName"
227+
}
228+
]
229+
}
230+
}
231+
}
232+
}
233+
}
234+
```
235+
236+
## Defaults
237+
238+
In case neither `"detailView"`, nor `"listView` is provided, the default values will be used. In case no `"createView"` details are provided
239+
there is no possibility of creating a resource.
240+
241+
## Support
242+
243+
For issues or questions, please refer to the [project documentation and community resources](https://openmfp.org/docs/community).

0 commit comments

Comments
 (0)