From 05f26bd9a2f32a12fc8fed135c6931c364043df2 Mon Sep 17 00:00:00 2001 From: Juan Flores Date: Wed, 5 Jul 2023 20:21:18 +0100 Subject: [PATCH 1/2] 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): From 376c8fe08d4a75d701c8e9f8ff2a6161575593b1 Mon Sep 17 00:00:00 2001 From: Juan Flores Date: Thu, 6 Jul 2023 15:51:50 +0100 Subject: [PATCH 2/2] Adding backsticks to titles to pass md linter Signed-off-by: Juan Flores --- .../software-templates/ui-options-examples.md | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/features/software-templates/ui-options-examples.md b/docs/features/software-templates/ui-options-examples.md index 403c509ebe..b402f68aee 100644 --- a/docs/features/software-templates/ui-options-examples.md +++ b/docs/features/software-templates/ui-options-examples.md @@ -8,7 +8,7 @@ description: The input props that can be specified under ui:options for differen The input props that can be specified under `ui:options` for the `EntityPicker` field extension. -### allowArbitraryValues +### `allowArbitraryValues` Whether to allow arbitrary user input. Defaults to true. @@ -38,11 +38,11 @@ entity: allowArbitraryValues: true ``` -### allowedKinds +### `allowedKinds` DEPRECATED: Use `catalogFilter` instead. -### catalogFilter +### `catalogFilter` `catalogFilter` supports filtering options by any field(s) of an entity. @@ -73,9 +73,9 @@ entity: spec.type: team ``` -For the full details on the spec.* values see [here](../software-catalog/descriptor-format.md#kind-group). +For the full details on the spec.\* values see [here](../software-catalog/descriptor-format.md#kind-group). -### defaultKind +### `defaultKind` The default entity kind. @@ -91,7 +91,7 @@ system: defaultKind: System ``` -### defaultNamespace +### `defaultNamespace` The ID of a namespace that the entity belongs to. The default value is `default`. @@ -119,11 +119,11 @@ entity: defaultNamespace: payment ``` -## OwnerPicker +## `OwnerPicker` The input props that can be specified under `ui:options` for the `OwnerPicker` field extension. -### allowArbitraryValues +### `allowArbitraryValues` Whether to allow arbitrary user input. Defaults to true. @@ -153,11 +153,11 @@ owner: allowArbitraryValues: true ``` -### allowedKinds +### `allowedKinds` DEPRECATED: Use `catalogFilter` instead. -### catalogFilter +### `catalogFilter` `catalogFilter` supports filtering options by any field(s) of an entity. @@ -188,9 +188,9 @@ owner: spec.type: team ``` -For the full details on the spec.* values see [here](../software-catalog/descriptor-format.md#kind-group). +For the full details on the spec.\* values see [here](../software-catalog/descriptor-format.md#kind-group). -### defaultNamespace +### `defaultNamespace` The ID of a namespace that the owner belongs to. The default value is `default`. @@ -226,7 +226,7 @@ owner: The input props that can be specified under `ui:options` for the `RepoUrlPicker` field extension. -### allowedHosts +### `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' @@ -244,7 +244,7 @@ repoUrl: - github.com ``` -### allowedOrganizations +### `allowedOrganizations` List of allowed organizations in the given SCM platform. You can restrict the template to publish to a set of organizations. @@ -260,7 +260,7 @@ repoUrl: - my_organization ``` -### allowedProjects +### `allowedProjects` List of allowed projects in the given SCM platform. You can restrict the template to publish to a set of projects. @@ -276,12 +276,12 @@ repoUrl: - project_1 ``` -### allowedRepos +### `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 @@ -293,7 +293,7 @@ repoUrl: - repo_2 ``` -### allowedOwners +### `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. @@ -310,10 +310,10 @@ repoUrl: - owner_2 ``` -### requestUserCredentials +### `requestUserCredentials` If defined will request user credentials to auth against the given SCM platform. - + ```yaml repoUrl: title: Repository Location