From 3d8637847b0047877f29cde4c043681ed129d02d Mon Sep 17 00:00:00 2001 From: "Bari, Haider" Date: Thu, 24 Oct 2024 14:49:19 +0100 Subject: [PATCH 1/5] added new section to writing custom actions md file for example template Signed-off-by: Bari, Haider --- .../writing-custom-actions.md | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index 00a171523c..23c5e87f7d 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -141,6 +141,88 @@ Prefer to use `camelCase` over `snake_case` or `kebab-case` for these actions if > We're aware that there are some exceptions to this, but try to follow as close as possible. We'll be working on migrating these in the repository over time too. + +### Template Example + +A Template Example is a predefined format or structure that can be used to create custom actions in your software templates. It serves as a blueprint to ensure consistency and standardization across different custom actions. + +#### How to Use a Template Example: + +1. Identify the custom action you want to create. +2. Refer to the Template Example to understand the required structure and components. +3. Fill in the necessary details in the template, such as action name, parameters, and logic. +4. Integrate the completed template into your software template to enable the custom action. + +#### Benefits: + +- Ensures consistency in custom actions. +- Simplifies the creation process by providing a clear structure. +- Helps in maintaining standardization across different templates. + +#### Define an Example and add to your Custom Action + +```ts title="With JSON Schema" +import { TemplateExample } from "@backstage/plugin-scaffolder-node"; +import yaml from "yaml"; + +export const AcmeExample: TemplateExample[] = [ + { + description: "Template Example for Creating an Acme file", + example: yaml.stringify({ + steps: [ + { + action: "acme:file:create", + name: "Create an Acme file.", + input: { + contents: "file contents...", + filename: "ACME.properties" + }, + }, + ], + }), + }, +]; +``` + +Add the example to the `createTemplateAction` under the object property `examples`: + +```ts title="With JSON Schema" +export const createNewFileAction = () => { + return createTemplateAction<{ contents: string; filename: string }>({ + id: 'acme:file:create', + description: 'Create an Acme file.', + examples: AcmeExample, + schema: { + input: { + required: ['contents', 'filename'], + type: 'object', + properties: { + contents: { + type: 'string', + title: 'Contents', + description: 'The contents of the file', + }, + filename: { + type: 'string', + title: 'Filename', + description: 'The filename of the file that will be created', + }, + }, + }, + }, + async handler(ctx) { + const { signal } = ctx; + await writeFile( + resolveSafeChildPath(ctx.workspacePath, ctx.input.filename), + ctx.input.contents, + { signal }, + _ => {}, + ); + }, + }); +}; +``` + ### The context object When the action `handler` is called, we provide you a `context` as the only From 4eb47d67bd5b7f983bda84b443b7b40290349844 Mon Sep 17 00:00:00 2001 From: "Bari, Haider" Date: Thu, 24 Oct 2024 15:59:42 +0100 Subject: [PATCH 2/5] updated the section for writing custom actions md file Signed-off-by: Bari, Haider --- .../writing-custom-actions.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index 23c5e87f7d..c42dbd7e7f 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -142,30 +142,31 @@ Prefer to use `camelCase` over `snake_case` or `kebab-case` for these actions if > We're aware that there are some exceptions to this, but try to follow as close as possible. We'll be working on migrating these in the repository over time too. -### Template Example +### Adding a TemplateExample -A Template Example is a predefined format or structure that can be used to create custom actions in your software templates. It serves as a blueprint to ensure consistency and standardization across different custom actions. +A TemplateExample is a predefined structure that can be used to create custom actions in your software templates. It serves as a blueprint for users to understand how to use a specific action and its fields as well as to ensure consistency and standardization across different custom actions. -#### How to Use a Template Example: +#### How to Use a TemplateExample 1. Identify the custom action you want to create. -2. Refer to the Template Example to understand the required structure and components. +2. Refer to the TemplateExample to understand the required structure and components. 3. Fill in the necessary details in the template, such as action name, parameters, and logic. 4. Integrate the completed template into your software template to enable the custom action. -#### Benefits: +#### Benefits +- Serves as templates for users to understand how to configure and use the actions. - Ensures consistency in custom actions. - Simplifies the creation process by providing a clear structure. - Helps in maintaining standardization across different templates. -#### Define an Example and add to your Custom Action +#### Define a TemplateExample and add to your Custom Action ```ts title="With JSON Schema" import { TemplateExample } from "@backstage/plugin-scaffolder-node"; import yaml from "yaml"; -export const AcmeExample: TemplateExample[] = [ +export const examples: TemplateExample[] = [ { description: "Template Example for Creating an Acme file", example: yaml.stringify({ @@ -187,11 +188,13 @@ export const AcmeExample: TemplateExample[] = [ Add the example to the `createTemplateAction` under the object property `examples`: ```ts title="With JSON Schema" +import { examples } from './acmeExample.examples'; + export const createNewFileAction = () => { return createTemplateAction<{ contents: string; filename: string }>({ id: 'acme:file:create', description: 'Create an Acme file.', - examples: AcmeExample, + examples, schema: { input: { required: ['contents', 'filename'], From aa1921f0e01f74fa59496797f4d73d74f7e4c599 Mon Sep 17 00:00:00 2001 From: "Bari, Haider" Date: Tue, 12 Nov 2024 20:52:43 +0000 Subject: [PATCH 3/5] fixed format issues Signed-off-by: Bari, Haider --- .../writing-custom-actions.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index c42dbd7e7f..51e9968435 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -141,10 +141,9 @@ Prefer to use `camelCase` over `snake_case` or `kebab-case` for these actions if > We're aware that there are some exceptions to this, but try to follow as close as possible. We'll be working on migrating these in the repository over time too. - ### Adding a TemplateExample -A TemplateExample is a predefined structure that can be used to create custom actions in your software templates. It serves as a blueprint for users to understand how to use a specific action and its fields as well as to ensure consistency and standardization across different custom actions. +A TemplateExample is a predefined structure that can be used to create custom actions in your software templates. It serves as a blueprint for users to understand how to use a specific action and its fields as well as to ensure consistency and standardization across different custom actions. #### How to Use a TemplateExample @@ -163,20 +162,20 @@ A TemplateExample is a predefined structure that can be used to create custom ac #### Define a TemplateExample and add to your Custom Action ```ts title="With JSON Schema" -import { TemplateExample } from "@backstage/plugin-scaffolder-node"; -import yaml from "yaml"; +import { TemplateExample } from '@backstage/plugin-scaffolder-node'; +import yaml from 'yaml'; export const examples: TemplateExample[] = [ { - description: "Template Example for Creating an Acme file", + description: 'Template Example for Creating an Acme file', example: yaml.stringify({ steps: [ { - action: "acme:file:create", - name: "Create an Acme file.", + action: 'acme:file:create', + name: 'Create an Acme file.', input: { - contents: "file contents...", - filename: "ACME.properties" + contents: 'file contents...', + filename: 'ACME.properties', }, }, ], From 89b2ed389e417d3d312f589a53ee79f28b57eb83 Mon Sep 17 00:00:00 2001 From: "Bari, Haider" Date: Fri, 22 Nov 2024 14:44:08 +0000 Subject: [PATCH 4/5] shorten one of the examples Signed-off-by: Bari, Haider --- .../writing-custom-actions.md | 54 +------------------ 1 file changed, 1 insertion(+), 53 deletions(-) diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index 51e9968435..7e6746f566 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -145,20 +145,6 @@ Prefer to use `camelCase` over `snake_case` or `kebab-case` for these actions if A TemplateExample is a predefined structure that can be used to create custom actions in your software templates. It serves as a blueprint for users to understand how to use a specific action and its fields as well as to ensure consistency and standardization across different custom actions. -#### How to Use a TemplateExample - -1. Identify the custom action you want to create. -2. Refer to the TemplateExample to understand the required structure and components. -3. Fill in the necessary details in the template, such as action name, parameters, and logic. -4. Integrate the completed template into your software template to enable the custom action. - -#### Benefits - -- Serves as templates for users to understand how to configure and use the actions. -- Ensures consistency in custom actions. -- Simplifies the creation process by providing a clear structure. -- Helps in maintaining standardization across different templates. - #### Define a TemplateExample and add to your Custom Action ```ts title="With JSON Schema" @@ -183,47 +169,9 @@ export const examples: TemplateExample[] = [ }, ]; ``` - Add the example to the `createTemplateAction` under the object property `examples`: -```ts title="With JSON Schema" -import { examples } from './acmeExample.examples'; - -export const createNewFileAction = () => { - return createTemplateAction<{ contents: string; filename: string }>({ - id: 'acme:file:create', - description: 'Create an Acme file.', - examples, - schema: { - input: { - required: ['contents', 'filename'], - type: 'object', - properties: { - contents: { - type: 'string', - title: 'Contents', - description: 'The contents of the file', - }, - filename: { - type: 'string', - title: 'Filename', - description: 'The filename of the file that will be created', - }, - }, - }, - }, - async handler(ctx) { - const { signal } = ctx; - await writeFile( - resolveSafeChildPath(ctx.workspacePath, ctx.input.filename), - ctx.input.contents, - { signal }, - _ => {}, - ); - }, - }); -}; -``` +`return createTemplateAction<{ contents: string; filename: string }>({id: 'acme:file:create', description: 'Create an Acme file', examples, ...};` ### The context object From d3768f94a92d160cf44f825aa3ecc248847270ab Mon Sep 17 00:00:00 2001 From: "Bari, Haider" Date: Fri, 22 Nov 2024 19:39:23 +0000 Subject: [PATCH 5/5] fixed format issues Signed-off-by: Bari, Haider --- docs/features/software-templates/writing-custom-actions.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/features/software-templates/writing-custom-actions.md b/docs/features/software-templates/writing-custom-actions.md index 7e6746f566..11e67af07f 100644 --- a/docs/features/software-templates/writing-custom-actions.md +++ b/docs/features/software-templates/writing-custom-actions.md @@ -169,6 +169,7 @@ export const examples: TemplateExample[] = [ }, ]; ``` + Add the example to the `createTemplateAction` under the object property `examples`: `return createTemplateAction<{ contents: string; filename: string }>({id: 'acme:file:create', description: 'Create an Acme file', examples, ...};`