From a6321c9b9f6a9b78ee525c6af66f1ec5b98c6d6a Mon Sep 17 00:00:00 2001
From: Vladimir Masarik <vladimir.masarik@ef.com>
Date: Fri, 17 Jun 2022 15:25:14 +0200
Subject: [PATCH] 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>
---
 .../software-templates/writing-templates.md   | 60 +++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/docs/features/software-templates/writing-templates.md b/docs/features/software-templates/writing-templates.md
index ff9962d8d4..5597916bee 100644
--- a/docs/features/software-templates/writing-templates.md
+++ b/docs/features/software-templates/writing-templates.md
@@ -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`.