From 05f26bd9a2f32a12fc8fed135c6931c364043df2 Mon Sep 17 00:00:00 2001 From: Juan Flores Date: Wed, 5 Jul 2023 20:21:18 +0100 Subject: [PATCH] Docs for built in ui:fields for Scaffolder #5883 Signed-off-by: Juan Flores --- .../software-templates/ui-options-examples.md | 332 ++++++++++++++++++ .../software-templates/writing-templates.md | 4 + 2 files changed, 336 insertions(+) create mode 100644 docs/features/software-templates/ui-options-examples.md diff --git a/docs/features/software-templates/ui-options-examples.md b/docs/features/software-templates/ui-options-examples.md new file mode 100644 index 0000000000..403c509ebe --- /dev/null +++ b/docs/features/software-templates/ui-options-examples.md @@ -0,0 +1,332 @@ +--- +id: ui-options-examples +title: ui:options Examples +description: The input props that can be specified under ui:options for different pickers +--- + +## EntityPicker + +The input props that can be specified under `ui:options` for the `EntityPicker` field extension. + +### allowArbitraryValues + +Whether to allow arbitrary user input. Defaults to true. + +`allowArbitraryValues` provides input validation when selecting an entity as the values you enter will correspond to a valid entity. + +- Adding a valid entity with `allowArbitraryValues` as `false` + +```yaml +entity: + title: Entity + type: string + description: Entity of the component + ui:field: EntityPicker + ui:options: + allowArbitraryValues: false +``` + +- Adding an arbitrary entity with `allowArbitraryValues` as `true` (default value) + +```yaml +entity: + title: Entity + type: string + description: Entity of the component + ui:field: EntityPicker + ui:options: + allowArbitraryValues: true +``` + +### allowedKinds + +DEPRECATED: Use `catalogFilter` instead. + +### catalogFilter + +`catalogFilter` supports filtering options by any field(s) of an entity. + +- Get all entities of kind `Group` + +```yaml +entity: + title: Entity + type: string + description: Entity of the component + ui:field: EntityPicker + ui:options: + catalogFilter: + - kind: Group +``` + +- Get entities of kind `Group` and spec.type `team` + +```yaml +entity: + title: Entity + type: string + description: Entity of the component + ui:field: EntityPicker + ui:options: + catalogFilter: + - kind: Group + spec.type: team +``` + +For the full details on the spec.* values see [here](../software-catalog/descriptor-format.md#kind-group). + +### defaultKind + +The default entity kind. + +```yaml +system: + title: System + type: string + description: System of the component + ui:field: EntityPicker + ui:options: + catalogFilter: + kind: System + defaultKind: System +``` + +### defaultNamespace + +The ID of a namespace that the entity belongs to. The default value is `default`. + +- Listing all entities in the `default` namespace (default value) + +```yaml +entity: + title: Entity + type: string + description: Entity of the component + ui:field: EntityPicker + ui:options: + defaultNamespace: default +``` + +- Listing all entities in the `payment` namespace + +```yaml +entity: + title: Entity + type: string + description: Entity of the component + ui:field: EntityPicker + ui:options: + defaultNamespace: payment +``` + +## OwnerPicker + +The input props that can be specified under `ui:options` for the `OwnerPicker` field extension. + +### allowArbitraryValues + +Whether to allow arbitrary user input. Defaults to true. + +`allowArbitraryValues` provides input validation when selecting an owner as the values you enter will correspond to a valid owner. + +- Adding a valid owner with `allowArbitraryValues` as `false` + +```yaml +owner: + title: Owner + type: string + description: Owner of the component + ui:field: OwnerPicker + ui:options: + allowArbitraryValues: false +``` + +- Adding an arbitrary owner with `allowArbitraryValues` as `true` (default value) + +```yaml +owner: + title: Owner + type: string + description: Owner of the component + ui:field: OwnerPicker + ui:options: + allowArbitraryValues: true +``` + +### allowedKinds + +DEPRECATED: Use `catalogFilter` instead. + +### catalogFilter + +`catalogFilter` supports filtering options by any field(s) of an entity. + +- Get all entities of kind `Group` + +```yaml +owner: + title: Owner + type: string + description: Owner of the component + ui:field: OwnerPicker + ui:options: + catalogFilter: + - kind: Group +``` + +- Get entities of kind `Group` and spec.type `team` + +```yaml +owner: + title: Owner + type: string + description: Owner of the component + ui:field: OwnerPicker + ui:options: + catalogFilter: + - kind: Group + spec.type: team +``` + +For the full details on the spec.* values see [here](../software-catalog/descriptor-format.md#kind-group). + +### defaultNamespace + +The ID of a namespace that the owner belongs to. The default value is `default`. + +- Listing owners in the `default` namespace (default value) + +```yaml +owner: + title: Owner + type: string + description: Owner of the component + ui:field: OwnerPicker + ui:options: + catalogFilter: + - kind: Group + defaultNamespace: default +``` + +- Listing owners in the `payment` namespace + +```yaml +owner: + title: Owner + type: string + description: Owner of the component + ui:field: OwnerPicker + ui:options: + catalogFilter: + - kind: Group + defaultNamespace: payment +``` + +## RepoUrlPicker + +The input props that can be specified under `ui:options` for the `RepoUrlPicker` field extension. + +### allowedHosts + +The `allowedHosts` part should be set to where you wish to enable this template +to publish to. And it can be any host that is listed in your integrations' +config in `app-config.yaml`. + +- Publish only to repositories from `github.com` + +```yaml +repoUrl: + title: Repository Location + type: string + ui:field: RepoUrlPicker + ui:options: + allowedHosts: + - github.com +``` + +### allowedOrganizations + +List of allowed organizations in the given SCM platform. You can restrict the template to publish to a set of organizations. + +- Publish only to repositories from organization `my_organization` + +```yaml +repoUrl: + title: Repository Location + type: string + ui:field: RepoUrlPicker + ui:options: + allowedOrganizations: + - my_organization +``` + +### allowedProjects + +List of allowed projects in the given SCM platform. You can restrict the template to publish to a set of projects. + +- Publish only to repositories from project `project_1` + +```yaml +repoUrl: + title: Repository Location + type: string + ui:field: RepoUrlPicker + ui:options: + allowedProjects: + - project_1 +``` + +### allowedRepos + +List of allowed repos in the given SCM platform. You can restrict the template to publish to a set of repository names. + +- Publish to only `repo_1` and `repo_2` repositories + +```yaml +repoUrl: + title: Repository Location + type: string + ui:field: RepoUrlPicker + ui:options: + allowedRepos: + - repo_1 + - repo_2 +``` + +### allowedOwners + +List of allowed owners in the given SCM platform. You can restrict the template to publish to repositories owned by specific users/groups by setting the `allowedOwners` option. + +- Publish to only repositories from owner `owner_1` and `owner_2` + +```yaml +repoUrl: + title: Repository Location + type: string + ui:field: RepoUrlPicker + ui:options: + allowedOwners: + - owner_1 + - owner_2 +``` + +### requestUserCredentials + +If defined will request user credentials to auth against the given SCM platform. + +```yaml +repoUrl: + title: Repository Location + type: string + ui:field: RepoUrlPicker + ui:options: + requestUserCredentials: + secretsKey: USER_OAUTH_TOKEN + additionalScopes: + github: + - workflow:write +``` + +`secretsKey` is the key used within the template secrets context to store the credential and `additionalScopes` is any additional permission scopes to request. + +The supported `additionalScopes` values are `gerrit`, `github`, `gitlab`, `bitbucket`, and `azure`. diff --git a/docs/features/software-templates/writing-templates.md b/docs/features/software-templates/writing-templates.md index 67bcb6c179..6e7b66fcc9 100644 --- a/docs/features/software-templates/writing-templates.md +++ b/docs/features/software-templates/writing-templates.md @@ -352,6 +352,8 @@ specific set of repository names. A full example could look like this: - backstage ``` +For a list of all possible `ui:options` input props for `RepoUrlPicker`, please visit [here](./ui-options-examples.md#repourlpicker). + The `RepoUrlPicker` is a custom field that we provide part of the `plugin-scaffolder`. You can provide your own custom fields by [writing your own Custom Field Extensions](./writing-custom-field-extensions.md) @@ -472,6 +474,8 @@ owner: kind: [Group, User] ``` +For a list of all possible `ui:options` input props for `OwnerPicker`, please visit [here](./ui-options-examples.md#ownerpicker). + #### `catalogFilter` The `catalogFilter` allow you to filter the list entities using any of the [catalog api filters](https://backstage.io/docs/features/software-catalog/software-catalog-api#filtering):