docs: writing templates, add examples of how to use values

Add information on how to actually use the parameters from the UI in the actual code
so that users can fully utilize the templating power of the default templating
action.

Signed-off-by: Vladimir Masarik <vladimir.masarik@ef.com>
This commit is contained in:
Vladimir Masarik
2022-06-17 15:25:14 +02:00
parent 7fc1f50f57
commit a6321c9b9f
@@ -485,6 +485,66 @@ the value of `firstName` from the parameters). This is great for passing the
values from the form into different steps and reusing these input variables.
These template strings preserve the type of the parameter.
The `${{ parameters.firstName }}` pattern will work only in the template file.
If you want to start using values provided from the UI in your code, you will have to use
the `${{ values.firstName }}` pattern. Additionally, you have to pass
the parameters from the UI to the input of the `fetch:template` step.
```yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: v1beta3-demo
title: Test Action
description: scaffolder v1beta3 template demo
spec:
owner: backstage/techdocs-core
type: service
parameters:
- title: Fill in some steps
required:
- name
properties:
name:
title: Name
type: string
description: Unique name of your project
urlParameter:
title: URL endpoint
type: string
description: URL endpoint at which the component can be reached
default: "https://www.example.com"
enabledDB:
title: Enable Database
type: boolean
default: false
...
steps:
- id: fetch-base
name: Fetch Base
action: fetch:template
input:
url: ./template
values:
name: ${{ parameters.name }}
url: ${{ parameters.urlParameter }}
enabledDB: ${{ parameters.enabledDB }}
```
Afterwards, if you are using the builtin templating action, you can start using
the variables in your code. You can use also any other templating fuctions from
[Nunjucks](https://mozilla.github.io/nunjucks/templating.html#tags) as well.
```bash
#!/bin/bash
echo "Hi my name is ${{ values.name }}, and you can fine me at ${{ values.url }}!"
{% if values.enabledDB %}
echo "You have enabled your database!"
{% endif %}
```
As you can see above in the `Outputs` section, `actions` and `steps` can also
output things. You can grab that output using `steps.$stepId.output.$property`.