diff --git a/docs/contributor/ui/README.md b/docs/contributor/ui/README.md new file mode 100644 index 000000000..b708b3a75 --- /dev/null +++ b/docs/contributor/ui/README.md @@ -0,0 +1,185 @@ +# Busola UI Documentation + +Kyma manages its modules' user interfaces (UIs) using ConfigMaps. Each ConfigMap has five parts: + + +* `general` - used to describe the CRD the UI should be looking for as well as a description of the resource in the case none exists on the cluster. +* `list` - used to set which columns to display in the table view +* `detail` - used to display the detailed view of a single resource +* `form` - used to define a GUI form when creating a new resource or editing an existing one. +* `translations` - used to define elements in different languages (English, German, etc.) + +Examples and important notes of each part are below + +### General +```yaml +resource: + kind: GcpNfsVolume + group: cloud-resources.kyma-project.io + version: v1beta1 +urlPath: gcpnfsvolumes +name: GCP NFS Volumes +scope: namespace +category: Storage +icon: shelf +description: >- + GcpNfsVolume description here +``` +It is imperative that `resource.kind` `resource.group` and `resource.version` matches its `CustomResourceDefinition`. If +there are no matches, Busola doesn't render the UI and path rendering the resource inaccessible in Busola. + + +### List +```yaml +- source: spec.fileShareName + name: spec.fileShareName + sort: true +- source: spec.location + name: spec.location + sort: true +- source: spec.tier + name: spec.tier + sort: true +- source: status.state + name: status.state + sort: true +``` + +The `source` field is where Busola pulls information from the monitored custom resource (CR). + +The `name` field is the human-readable name for the field. This field looks up the value in `Translation` and replaces it with its found value. +If no value is found in `Translation`, it displays as is. + +For example, if we have `name: spec.location`, it goes to [translations](#translations), looks up `spec.location` and replaces it with `Location`. + +[Official List Documentation](https://github.com/kyma-project/busola/blob/main/docs/extensibility/20-list-columns.md) + +[Official List and Detail Widgets](https://github.com/kyma-project/busola/blob/main/docs/extensibility/50-list-and-details-widgets.md) + +### Detail +```yaml +body: + - name: configuration + widget: Panel + source: spec + children: + - name: spec.fileShareName + source: fileShareName + widget: Labels + - name: spec.capacityGb + source: capacityGb + widget: Labels + - name: spec.location + source: location + widget: Labels + - name: spec.tier + source: tier + widget: Labels + - name: status + widget: Panel + source: status + children: + - widget: Labels + source: state + name: status.state +``` + +`widget` refers to the component interfaces built into Busola. See link below for official documentation on widgets. + +`children` are an array of child widgets. Note, the `source` in each child is relative to its parent. + +[Official Detail Documentation](https://github.com/kyma-project/busola/blob/main/docs/extensibility/30-details-summary.md) + +[Official List and Detail Widgets](https://github.com/kyma-project/busola/blob/main/docs/extensibility/50-list-and-details-widgets.md) + +### Form +```yaml +- path: spec.capacityGb + simple: true + name: spec.capacityGb + required: true +- path: spec.fileShareName + simple: true + name: spec.fileShareName + required: true +- path: spec.location + simple: true + name: spec.location + required: true +- path: spec.tier + simple: true + name: spec.tier + required: true +``` + +`simple` is a boolean used to display the field in the simple fom. By default, it is `false` + +[Official Forms Documentation](https://github.com/kyma-project/busola/blob/main/docs/extensibility/40-form-fields.md) + + +### Translations +```yaml +en: + spec.tier: Tier + spec.location: Location + spec.fileShareName: File Share Name + spec.capacityGb: Capacity (Gb) + spec.ipRange: IP Range + configuration: Configuration + status.state: State + status: Status +``` + +`translations` is optional, but it supports languages formatted for [i18next](https://www.i18next.com/). Translations prettify the `name` field of the aformentioned sections. +They are key-value pairs. + + +[Official Translations Documentation](https://github.com/kyma-project/busola/blob/main/docs/extensibility/translations-section.md) + + +# Generating the ConfigMap + +The generation of a ConfigMap is handled using `kustomize`. Kustomize combines general, list, detail, form, and translations +into a single ConfigMap. + +Because each CustomResource has its own UI that must be generated, there is a single macro in the `Makefile` to generate all the UIs. + +`make build_ui` + +For every new UI component, a new `kustomize` command should be added to the Makefile `build_ui` macro. + +[Official kustomize documentation](https://kustomize.io/) + +# Deploying to your desired provider (AWS, GCP, Azure) + +Currently, the pipeline looks at the presence of ConfigMaps files in specific directories to deploy. They are the following: + +AWS - `config/dist/skr/crd/bases/providers/aws` + +Azure - `config/dist/skr/crd/bases/providers/azure` + +GCP - `config/dist/skr/crd/bases/providers/gcp` + +Instead of manually copying over the ConfigMap into the specified directory, use the bash script `sync.sh` + +Like the `Makefile`, any new UI component should be added to `sync.sh`. + + +# Testing your UI changes without using the pipeline + +Because the UI is dictated by ConfigMaps, you can deploy directly to a cluster with kyma installed. Just ensure your ConfigMap goes into the `kyma-system` +namespace. + +You can then `kubectl apply` your ConfigMap. + +If a matching CustomResource is found, Busola renders the UI and path. + + +You can also spin up a local cluster with kyma installed via k3d. + +Official documentation and instructions can be found [here](https://kyma-project.io/#/02-get-started/01-quick-install). + + + +# Helpful Links +[Translations](https://github.com/kyma-project/busola/blob/main/docs/extensibility/translations-section.md) \ No newline at end of file