diff --git a/docs/features/software-templates/configuration.md b/docs/features/software-templates/configuration.md index 571f1150d0..a692335ffe 100644 --- a/docs/features/software-templates/configuration.md +++ b/docs/features/software-templates/configuration.md @@ -78,11 +78,11 @@ Once you have more than a few software templates you may want to customize your accomplish this by creating `groups` and passing them to your `ScaffolderPage` like below -``` +```tsx entity?.metadata?.tags?.includes('recommended') ?? false, }, @@ -96,6 +96,7 @@ top of the page above any other templates not filtered by this group or others. You can also further customize groups by passing in a `titleComponent` instead of a `title` which will be a component to use as the header instead of just the default `ContentHeader` with the `title` set as it's value. + ![Grouped Templates](../../assets/software-templates/grouped-templates.png) There is also an option to hide some templates. diff --git a/docs/features/software-templates/input-examples.md b/docs/features/software-templates/input-examples.md index bb4ecde946..84cfec28ed 100644 --- a/docs/features/software-templates/input-examples.md +++ b/docs/features/software-templates/input-examples.md @@ -12,6 +12,8 @@ It is important to remember that all examples are based on [react-jsonschema-for ### Simple input with basic validations +We can use a `pattern` to validate the input. The `pattern` is a regular expression that the input must match. + ```yaml parameters: - title: Fill in some steps @@ -28,6 +30,8 @@ parameters: #### Custom validation error message +This example shows how to customize the error message shown when the `pattern` validation fails. + ```yaml parameters: - title: Fill in some steps @@ -47,6 +51,8 @@ parameters: ### Multi line text input +If you need to insert a multi-line string, you can use the `ui:widget: textarea` option. This will create a text area input instead of a single line input. + ```yaml parameters: - title: Fill in some steps @@ -74,6 +80,8 @@ parameters: ### Array with custom titles +In the example below the user will see the the `enumNames` instead of the `enum` values, making it easier to read. + ```yaml parameters: - title: Fill in some steps @@ -103,6 +111,8 @@ parameters: ### A multiple choices list +This is a simple multiple choice list. + ```yaml parameters: - title: Fill in some steps @@ -122,6 +132,8 @@ parameters: ### Array with another types +In the example below, it will create an array of custom objects. Once you add one, you will see an object where each one contains 3 fields, "How are you?", "Is it sunny?" and "Anything else?". + ```yaml parameters: - title: Fill in some steps @@ -138,19 +150,19 @@ parameters: type: object properties: array: - title: Array string with default value + title: How are you? type: string - default: value3 + default: good enum: - - value1 - - value2 - - value3 + - good + - okay + - great flag: - title: Boolean flag + title: Is it sunny? type: boolean ui:widget: radio someInput: - title: Simple text input + title: Anything else? type: string ``` @@ -158,6 +170,8 @@ parameters: ### Boolean +This adds a simple checkbox to the form. The value will be `true` or `false`. + ```yaml parameters: - title: Fill in some steps @@ -169,6 +183,8 @@ parameters: ### Boolean Yes or No options +This example shows how to use a radio button instead of a checkbox with `Yes` or `No` options. + ```yaml parameters: - title: Fill in some steps @@ -181,6 +197,8 @@ parameters: ### Boolean multiple options +You can create multiple checkboxes with different options. The example below shows how to create a list of features that can be enabled or disabled for example. + ```yaml parameters: - title: Fill in some steps @@ -200,6 +218,8 @@ parameters: ## Markdown text blocks +Its possible to render markdown text blocks in the form. This is useful to add some help text or instructions for the user. + ```yaml parameters: - title: Fill in some steps @@ -217,7 +237,7 @@ parameters: ## Use parameters as condition in steps -Conditions use Javascript equality operators. +Its possible to conditionally run steps based on the value of a parameter. In the example below, we trigger the steps depending on the value of the `environment` parameter. ```yaml - name: Only development environments @@ -241,6 +261,8 @@ Conditions use Javascript equality operators. ## Use parameters as conditional for fields +Its also possible to conditionally show fields based on the value of a parameter. In the example below, we show the `lastName` field only if the `includeName` parameter is set to `true`. + ```yaml parameters: - title: Fill in some steps @@ -269,6 +291,9 @@ parameters: ### Multiple conditional fields with custom ordering +In this example, we show how to conditionally show multiple fields based on the value of a parameter. The `ui:order` property is used to control the order of the fields in the form. +In this case, we show the `lastName` and `address` fields only if the `includeName` and `includeAddress` parameters are set to `true`. + ```yaml parameters: - title: Fill in some steps @@ -349,12 +374,16 @@ Testing of this functionality is not yet supported using _create/edit_. In addit ::: +Its possible to use placeholders to reference remote files. This is useful when you have some standard parameters or actions that you want to reuse across multiple templates. + ### template.yaml +In our template, we use the `$yaml` placeholder to reference the `parameters.yaml` and `action.yaml` files. The `parameters.yaml` file contains some parameters that we want to use in our template, and the `action.yaml` file contains the action that we want to run. + ```yaml spec: parameters: - - $yaml: https://github.com/example/path/to/example.yaml + - $yaml: https://github.com/example/path/to/parameters.yaml # This would become the parameters as referenced in the parameters.yaml file - title: Fill in some steps properties: path: @@ -362,7 +391,7 @@ spec: type: string steps: - - $yaml: https://github.com/example/path/to/action.yaml + - $yaml: https://github.com/example/path/to/action.yaml # This would become the publish action as referenced in the action.yaml file - id: fetch name: Fetch template @@ -371,7 +400,9 @@ spec: url: ${{ parameters.path if parameters.path else '/root' }} ``` -### example.yaml +### parameters.yaml + +The `url` parameter will be added to the template. ```yaml title: Provide simple information @@ -385,6 +416,8 @@ properties: ### action.yaml +The `publish:github` action will be included in our template. + ```yaml id: publish name: Publish files diff --git a/docs/features/software-templates/writing-templates.md b/docs/features/software-templates/writing-templates.md index bc2847a81b..4f8691e948 100644 --- a/docs/features/software-templates/writing-templates.md +++ b/docs/features/software-templates/writing-templates.md @@ -4,8 +4,7 @@ title: Writing Templates description: Details around creating your own custom Software Templates --- -Templates are stored in the **Software Catalog** under a kind `Template`. You -can create your own templates with a small `yaml` definition which describes the +You can create your own templates with a small `yaml` definition which describes the template and its metadata, along with some input variables that your template will need, and then a list of actions which are then executed by the scaffolding service.