Merge pull request #12111 from VladMasarik/docs-tempalte

Docs update custom template actions

docs/features/software-templates/adding-templates.md

@@ -86,6 +86,13 @@ contains more information about the required fields.
 Once we have a `template.yaml` ready, we can then add it to the software catalog
 for use by the scaffolder.
 
+> Note: When you add or modify a template, you will need to refresh the location entity.
+> Otherwise, Backstage won't display the template in the available templates,
+> or it will keep showing the old template. You can refresh the location instance by
+> going into `Catalog` web page, choosing `Locations` instead of `Components`, and selecting the correct location entity.
+> From there, you can click on the refresh icon representing "Scheduled entity refresh" action.
+> Afterwards, you should see your template updated.
+
 You can add the template files to the catalog through
 [static location configuration](../software-catalog/configuration.md#static-location-configuration),
 for example:
@@ -97,6 +104,8 @@ catalog:
       target: https://github.com/backstage/software-templates/blob/main/scaffolder-templates/react-ssr-template/template.yaml
       rules:
         - allow: [Template]
+    - type: file
+      target: template.yaml # Backstage will expect the file to be in packages/backend/template.yaml
 ```
 
 Or you can add the template using the `catalog-import` plugin, which unless

docs/features/software-templates/writing-custom-actions.md

@@ -9,8 +9,9 @@ by writing custom actions which can be used along side our
 [built-in actions](./builtin-actions.md).
 
 > Note: When adding custom actions, the actions array will **replace the
-> built-in actions too**. To ensure you can continue to include the builtin
-> actions, see below to include them during registration of your action.
+> built-in actions too**. Meaning, you will no longer be able to use them.
+> If you want to continue using the builtin actions, include them in the actions
+> array when registering your custom actions, as seen below.
 
 ## Writing your Custom Action
 
@@ -122,27 +123,32 @@ will set the available actions that the scaffolder has access to.
 ```ts
 import { createBuiltinActions } from '@backstage/plugin-scaffolder-backend';
 import { ScmIntegrations } from '@backstage/integration';
+import { createNewFileAction } from './actions/custom';
 
-const integrations = ScmIntegrations.fromConfig(env.config);
+export default async function createPlugin(
+  env: PluginEnvironment,
+): Promise<Router> {
+  const catalogClient = new CatalogClient({ discoveryApi: env.discovery });
+  const integrations = ScmIntegrations.fromConfig(env.config);
 
-const builtInActions = createBuiltinActions({
-  containerRunner,
-  integrations,
-  catalogClient,
-  config: env.config,
-  reader: env.reader,
-});
+  const builtInActions = createBuiltinActions({
+    integrations,
+    catalogClient,
+    config: env.config,
+    reader: env.reader,
+  });
 
-const actions = [...builtInActions, createNewFileAction()];
-return await createRouter({
-  containerRunner,
-  catalogClient,
-  actions,
-  logger: env.logger,
-  config: env.config,
-  database: env.database,
-  reader: env.reader,
-});
+  const actions = [...builtInActions, createNewFileAction()];
+
+  return createRouter({
+    actions,
+    catalogClient: catalogClient,
+    logger: env.logger,
+    config: env.config,
+    database: env.database,
+    reader: env.reader,
+  });
+}
 ```
 
 ## List of custom action packages

docs/features/software-templates/writing-templates.md

@@ -485,6 +485,64 @@ 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 functions 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`.