From 7e35d62a13baef3aeafbe0d28cb9b02395234c40 Mon Sep 17 00:00:00 2001 From: Vladimir Masarik Date: Fri, 17 Jun 2022 14:24:03 +0200 Subject: [PATCH 1/7] docs: custom tempalte actions clearly express that the builtin actions are replaced Signed-off-by: Vladimir Masarik --- docs/features/software-templates/writing-custom-actions.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index 8e698e1a05..635a373eb3 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/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 From 1ee1a02d676199a7425c774824661acade56db48 Mon Sep 17 00:00:00 2001 From: Vladimir Masarik Date: Fri, 17 Jun 2022 14:26:56 +0200 Subject: [PATCH 2/7] docs: custom template actions update code exmaple Users don't need the container runner, and variables have to be passed in differently Signed-off-by: Vladimir Masarik --- .../writing-custom-actions.md | 41 +++++++++++-------- 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index 635a373eb3..abff0cf7c7 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -123,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 { + 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()]; -const actions = [...builtInActions, createNewFileAction()]; -return await createRouter({ - containerRunner, - catalogClient, - actions, - logger: env.logger, - config: env.config, - database: env.database, - reader: env.reader, -}); + return createRouter({ + actions, + catalogClient: catalogClient, + logger: env.logger, + config: env.config, + database: env.database, + reader: env.reader, + }); +} ``` ## List of custom action packages From 4ae8c4b0b76b20b04ca48dba6fbb33c1b20083fc Mon Sep 17 00:00:00 2001 From: Vladimir Masarik Date: Fri, 17 Jun 2022 14:49:33 +0200 Subject: [PATCH 3/7] docs: Adding templates, add template as a file example Signed-off-by: Vladimir Masarik --- docs/features/software-templates/adding-templates.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/features/software-templates/adding-templates.md b/docs/features/software-templates/adding-templates.md index db765fc7ee..821e44b0ab 100644 --- a/docs/features/software-templates/adding-templates.md +++ b/docs/features/software-templates/adding-templates.md @@ -97,6 +97,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 From 7fc1f50f57ff01c24ccdddf43871bd02afe83760 Mon Sep 17 00:00:00 2001 From: Vladimir Masarik Date: Fri, 17 Jun 2022 15:00:58 +0200 Subject: [PATCH 4/7] docs: Adding templates, added note for users that they need to refresh the location Othwise, backstage won't display the updated or newly added template, and it won't report any errors either. Signed-off-by: Vladimir Masarik --- docs/features/software-templates/adding-templates.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/features/software-templates/adding-templates.md b/docs/features/software-templates/adding-templates.md index 821e44b0ab..62604df1b7 100644 --- a/docs/features/software-templates/adding-templates.md +++ b/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 "Sheduled 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: From a6321c9b9f6a9b78ee525c6af66f1ec5b98c6d6a Mon Sep 17 00:00:00 2001 From: Vladimir Masarik Date: Fri, 17 Jun 2022 15:25:14 +0200 Subject: [PATCH 5/7] 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 --- .../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`. From e81be86682cee2a94c71aeaa593726b1a9dd190e Mon Sep 17 00:00:00 2001 From: Vladimir Masarik Date: Fri, 17 Jun 2022 16:01:37 +0200 Subject: [PATCH 6/7] docs: fix template typos Signed-off-by: Vladimir Masarik --- docs/features/software-templates/adding-templates.md | 2 +- docs/features/software-templates/writing-templates.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/features/software-templates/adding-templates.md b/docs/features/software-templates/adding-templates.md index 62604df1b7..e8176a688b 100644 --- a/docs/features/software-templates/adding-templates.md +++ b/docs/features/software-templates/adding-templates.md @@ -90,7 +90,7 @@ for use by the scaffolder. > 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 "Sheduled entity refresh" action. +> 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 diff --git a/docs/features/software-templates/writing-templates.md b/docs/features/software-templates/writing-templates.md index 5597916bee..3173a0500a 100644 --- a/docs/features/software-templates/writing-templates.md +++ b/docs/features/software-templates/writing-templates.md @@ -534,7 +534,7 @@ spec: ``` 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 +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 From fccddd80fd865c959a459c9e20375dd4270c855e Mon Sep 17 00:00:00 2001 From: Vladimir Masarik Date: Mon, 20 Jun 2022 17:25:00 +0200 Subject: [PATCH 7/7] docs: fix prettier complaints Signed-off-by: Vladimir Masarik --- docs/features/software-templates/writing-custom-actions.md | 2 +- docs/features/software-templates/writing-templates.md | 6 ++---- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index abff0cf7c7..a9e1d297f3 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -137,7 +137,7 @@ export default async function createPlugin( config: env.config, reader: env.reader, }); - + const actions = [...builtInActions, createNewFileAction()]; return createRouter({ diff --git a/docs/features/software-templates/writing-templates.md b/docs/features/software-templates/writing-templates.md index 3173a0500a..40b735764c 100644 --- a/docs/features/software-templates/writing-templates.md +++ b/docs/features/software-templates/writing-templates.md @@ -513,14 +513,12 @@ spec: title: URL endpoint type: string description: URL endpoint at which the component can be reached - default: "https://www.example.com" + default: 'https://www.example.com' enabledDB: title: Enable Database type: boolean default: false - -... - + ... steps: - id: fetch-base name: Fetch Base