docs: adding some life to the software template docs
Signed-off-by: Peter Macdonald <peterm4c@pm.me>
This commit is contained in:
Peter Macdonald
@@ -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
|
||||
<ScaffolderPage
|
||||
groups={[
|
||||
{
|
||||
title: "Recommended",
|
||||
title: 'Recommended',
|
||||
filter: entity =>
|
||||
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.
|
||||
|
||||
|
||||
|
||||
There is also an option to hide some templates.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user