Skip to content

RHIDP-5608: Update content for Template Editor #1187

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Gerry-Forde merged 3 commits into from
May 26, 2025
Merged

RHIDP-5608: Update content for Template Editor #1187

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0d6233c
Updated content for Template Editor
pabel-rh May 22, 2025
c9104a3
Fixed broken link
pabel-rh May 22, 2025
5c1129a
Replaced templates as Software Template
pabel-rh May 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified images/rhdh/template-editor.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
16 changes: 8 additions & 8 deletions modules/customizing-templates/proc-adding-templates.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,18 @@

:_mod-docs-content-type: PROCEDURE
[id="proc-adding-templates_{context}"]
= Importing an existing template to {product}
= Importing an existing Software Template to {product}

You can add an existing template to your {product} instance by using the Catalog Processor.
You can add an existing Software Template to your {product} instance by using the Catalog Processor.

.Prerequisites

* You have created a directory or repository that contains at least one template YAML file.
* If you want to use a template that is stored in a repository such as GitHub or GitLab, you must configure a {product} integration for your provider.
* You have created a directory or repository that contains at least one Software Template YAML file.
* If you want to use a Software Template that is stored in a repository such as GitHub or GitLab, you must configure a {product} integration for your provider.

.Procedure

* In the `{my-app-config-file}` configuration file, modify the `catalog.rules` section to include a rule for templates, and configure the `catalog.locations` section to point to the template that you want to add, as shown in the following example:
* In the `{my-app-config-file}` configuration file, modify the `catalog.rules` section to include a rule for templates, and configure the `catalog.locations` section to point to the Software Template that you want to add, as shown in the following example:
+
[source,yaml]
----
Expand All @@ -28,12 +28,12 @@ catalog:
target: https://<repository_url>/example-template.yaml # <3>
# ...
----
<1> To allow new templates to be added to the catalog, you must add a `Template` rule.
<1> To allow new Software Templates to be added to the catalog, you must add a `Template` rule.
<2> If you are importing templates from a repository, such as GitHub or GitLab, use the `url` type.
<3> Specify the URL for the template.
<3> Specify the URL for the Software Template.

.Verification

. Click the *Catalog* tab in the navigation panel.
. In the *Kind* drop-down menu, select *Template*.
. Confirm that your template is shown in the list of existing templates.
. Confirm that your Software Template is shown in the list of existing Software Templates.
61 changes: 29 additions & 32 deletions modules/customizing-templates/proc-creating-templates.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,51 +4,48 @@

:_mod-docs-content-type: PROCEDURE
[id="proc-creating-templates_{context}"]
= Creating a template by using the Template Editor
= Creating a Software Template by using the Template Editor templates

You can create a template by using the Template Editor.
You can create a Software Template by using the Template Editor templates.

Alternately, you can use the Template Editor to do any of the following actions:

* *File > Open template directory*
* *File > Create template directory*
* *File > Close template editor*
* Use the *Custom Fields Explorer* button to test custom fields in your `templates.yaml` file
* View *Installed Actions Documentation*

.Procedure

. Access the Template Editor by using one of the following options:
To create a Software Template by using the Template Editor templates, complete the following steps:

. In your {product} navigation menu, click *Create...*.
. Click the overview menu and select *Manage Templates*.
+
image::rhdh/template-editor.png[Template Editor]
** Open the URL `\https://<rhdh_url>/create/edit` for your {product} instance.
** Click *Create...* in the navigation menu of the {product} console, then click the overflow menu button and select *Template editor*.
. Click *Edit Template Form*.
. Optional: Modify the YAML definition for the parameters of your template. For more information about these parameters, see <<Creating a template as a YAML file>>.
. In the *Name ** field, enter a unique name for your template.
. From the *Owner* drop-down menu, choose an owner for the template.
. Click *Next*.
. In the *Repository Location* view, enter the following information about the hosted repository that you want to publish the template to:
.. Select an available *Host* from the drop-down menu.
+
--

[NOTE]
====
Available hosts are defined in the YAML parameters by the `allowedHosts` field:

.Example YAML
[source,yaml]
----
# ...
ui:options:
allowedHosts:
- github.com
# ...
----

* The following options on the *Managed Templates* page do not create a software component in your {product} instance:
** *Template Form Playground*: Use to create and test the `templates.yaml` file
** *Custom Field Explorer*: Use to test custom fields
====
--

.. In the *Owner ** field, enter an organization, user or project that the hosted repository belongs to.
.. In the *Repository ** field, enter the name of the hosted repository.
.. Click *Review*.

. Review the information for accuracy, then click *Create*.
. On the *Managed Templates* page, select any of the following options:
* *Load Template Directory*: Use to load an existing `templates.yaml` file
** In your local file manager, navigate to the folder where your `templates.yaml` file is stored and click *Select*.
* *Create New Template*: Use to create a `templates.yaml` file
** In your local file manager, navigate to the folder where you want the Template Editor to create a `templates.yaml` file and click *Select*.
.. On the *Template Editor* page, select the `templates.yaml` file.
.. On the *Fill in some steps* tab, enter text into the required fields and click *Next*.
.. On the *Repository Location* tab, enter text into the required fields and click *Review*.
.. Optional: Modify the YAML definition for the parameters of your template. For more information about these parameters, see <<Creating a Software Template as a YAML file>>.
.. Review the information for accuracy, then click *Create*.

.Verification

. Click the *Catalog* tab in the navigation panel.
. In the *Kind* drop-down menu, select *Template*.
. Confirm that your template is shown in the list of existing templates.
. Confirm that your Software Template is shown in the list of existing templates.
16 changes: 8 additions & 8 deletions modules/customizing-templates/ref-creating-templates.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@

:_mod-docs-content-type: REFERENCE
[id="ref-creating-templates_{context}"]
= Creating a template as a YAML file
= Creating a Software Template as a YAML file

You can create a template by defining a `Template` object as a YAML file.
You can create a Software Template by defining a `Template` object as a YAML file.

The `Template` object describes the template and its metadata. It also contains required input variables and a list of actions that are executed by the scaffolding service.

Expand Down Expand Up @@ -56,10 +56,10 @@ spec:
entityRef: ${{ steps['register'].output.entityRef }}
# ...
----
<1> Specify a name for the template.
<2> Specify a title for the template. This is the title that is visible on the template tile in the *Create...* view.
<3> Specify a description for the template. This is the description that is visible on the template tile in the *Create...* view.
<4> Specify the ownership of the template. The `owner` field provides information about who is responsible for maintaining or overseeing the template within the system or organization. In the provided example, the `owner` field is set to `backstage/techdocs-core`. This means that this template belongs to the `techdocs-core` project in the `backstage` namespace.
<1> Specify a name for the Software Template.
<2> Specify a title for the Software Template. This is the title that is visible on the Software Template tile in the *Create...* view.
<3> Specify a description for the Software Template. This is the description that is visible on the Software Template tile in the *Create...* view.
<4> Specify the ownership of the Software Template. The `owner` field provides information about who is responsible for maintaining or overseeing the Software Template within the system or organization. In the provided example, the `owner` field is set to `backstage/techdocs-core`. This means that this Software Template belongs to the `techdocs-core` project in the `backstage` namespace.
<5> Specify the component type. Any string value is accepted for this required field, but your organization should establish a proper taxonomy for these. {product} instances may read this field and behave differently depending on its value. For example, a `website` type component may present tooling in the {product} interface that is specific to just websites.
+
The following values are common for this field:
Expand All @@ -69,8 +69,8 @@ The following values are common for this field:
`website`:: A website.
`library`:: A software library, such as an npm module or a Java library.
--
<6> Use the `parameters` section to specify parameters for user input that are shown in a form view when a user creates a component by using the template in the {product} console. Each `parameters` subsection, defined by a title and properties, creates a new form page with that definition.
<6> Use the `parameters` section to specify parameters for user input that are shown in a form view when a user creates a component by using the Software Template in the {product} console. Each `parameters` subsection, defined by a title and properties, creates a new form page with that definition.
<7> Use the `steps` section to specify steps that are executed in the backend. These steps must be defined by using a unique step ID, a name, and an action. You can view actions that are available on your {product} instance by visiting the URL `\https://<rhdh_url>/create/actions`.
<8> Use the `output` section to specify the structure of output data that is created when the template is used. The `output` section, particularly the `links` subsection, provides valuable references and URLs that users can utilize to access and interact with components that are created from the template.
<8> Use the `output` section to specify the structure of output data that is created when the Software Template is used. The `output` section, particularly the `links` subsection, provides valuable references and URLs that users can utilize to access and interact with components that are created from the Software Template.
<9> Provides a reference or URL to the repository associated with the generated component.
<10> Provides a reference or URL that allows users to open the generated component in a catalog or directory where various components are listed.