Merge pull request #10576 from backstage/rugvip/scaffolder-navigation

scaffolder: add links to subroutes + rename /preview -> /edit

.changeset/cold-steaks-provide.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder': minor
+---
+
+Added a context menu to the scaffolder page that provides links to the template editor and actions reference. These links and the presence of the context menu can be toggled through the `contextMenu` prop of the scaffolder page.

.changeset/moody-sheep-marry.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-scaffolder': minor
+---
+
+The Template Preview page has been renamed to Template Editor, and is not available at the `/edit` path instead. There is a redirect in place from `/preview`.

plugins/scaffolder/api-report.md

@@ -217,6 +217,10 @@ export type RouterProps = {
     filter: (entity: Entity) => boolean;
   }>;
   defaultPreviewTemplate?: string;
+  contextMenu?: {
+    editor?: boolean;
+    actions?: boolean;
+  };
 };
 
 // @public

plugins/scaffolder/src/components/Router.tsx

@@ -15,7 +15,7 @@
  */
 
 import React, { ComponentType } from 'react';
-import { Routes, Route, useOutlet } from 'react-router';
+import { Routes, Route, useOutlet, Navigate } from 'react-router';
 import { Entity } from '@backstage/catalog-model';
 import { TemplateEntityV1beta3 } from '@backstage/plugin-scaffolder-common';
 import { ScaffolderPage } from './ScaffolderPage';
@@ -23,7 +23,7 @@ import { TemplatePage } from './TemplatePage';
 import { TaskPage } from './TaskPage';
 import { ActionsPage } from './ActionsPage';
 import { SecretsContextProvider } from './secrets/SecretsContext';
-import { TemplatePreviewPage } from './TemplatePreviewPage';
+import { TemplateEditorPage } from './TemplateEditorPage';
 
 import {
   FieldExtensionOptions,
@@ -32,6 +32,12 @@ import {
   DEFAULT_SCAFFOLDER_FIELD_EXTENSIONS,
 } from '../extensions';
 import { useElementFilter } from '@backstage/core-plugin-api';
+import {
+  actionsRouteRef,
+  editRouteRef,
+  scaffolderTaskRouteRef,
+  selectedTemplateRouteRef,
+} from '../routes';
 
 /**
  * The props for the entrypoint `ScaffolderPage` component the plugin.
@@ -49,6 +55,15 @@ export type RouterProps = {
     filter: (entity: Entity) => boolean;
   }>;
   defaultPreviewTemplate?: string;
+  /**
+   * Options for the context menu on the scaffolder page.
+   */
+  contextMenu?: {
+    /** Whether to show a link to the template editor */
+    editor?: boolean;
+    /** Whether to show a link to the actions documentation */
+    actions?: boolean;
+  };
 };
 
 /**
@@ -87,35 +102,37 @@ export const Router = (props: RouterProps) => {
   return (
     <Routes>
       <Route
-        path="/"
         element={
           <ScaffolderPage
             groups={groups}
             TemplateCardComponent={TemplateCardComponent}
+            contextMenu={props.contextMenu}
           />
         }
       />
       <Route
-        path="/templates/:templateName"
+        path={selectedTemplateRouteRef.path}
         element={
           <SecretsContextProvider>
             <TemplatePage customFieldExtensions={fieldExtensions} />
           </SecretsContextProvider>
         }
       />
-      <Route path="/tasks/:taskId" element={<TaskPageElement />} />
-      <Route path="/actions" element={<ActionsPage />} />
+      <Route path={scaffolderTaskRouteRef.path} element={<TaskPageElement />} />
+      <Route path={actionsRouteRef.path} element={<ActionsPage />} />
       <Route
-        path="/preview"
+        path={editRouteRef.path}
         element={
           <SecretsContextProvider>
-            <TemplatePreviewPage
+            <TemplateEditorPage
               defaultPreviewTemplate={defaultPreviewTemplate}
               customFieldExtensions={fieldExtensions}
             />
           </SecretsContextProvider>
         }
       />
+
+      <Route path="preview" element={<Navigate to="../edit" />} />
     </Routes>
   );
 };

plugins/scaffolder/src/components/ScaffolderPage/ScaffolderPage.tsx

@@ -39,6 +39,7 @@ import { TemplateList } from '../TemplateList';
 import { TemplateTypePicker } from '../TemplateTypePicker';
 import { catalogEntityCreatePermission } from '@backstage/plugin-catalog-common';
 import { usePermission } from '@backstage/plugin-permission-react';
+import { ScaffolderPageContextMenu } from './ScaffolderPageContextMenu';
 
 export type ScaffolderPageProps = {
   TemplateCardComponent?:
@@ -48,11 +49,16 @@ export type ScaffolderPageProps = {
     title?: React.ReactNode;
     filter: (entity: Entity) => boolean;
   }>;
+  contextMenu?: {
+    editor?: boolean;
+    actions?: boolean;
+  };
 };
 
 export const ScaffolderPageContents = ({
   TemplateCardComponent,
   groups,
+  contextMenu,
 }: ScaffolderPageProps) => {
   const registerComponentLink = useRouteRef(registerComponentRouteRef);
   const otherTemplatesGroup = {
@@ -73,7 +79,9 @@ export const ScaffolderPageContents = ({
         pageTitleOverride="Create a New Component"
         title="Create a New Component"
         subtitle="Create new software components using standard templates"
-      />
+      >
+        <ScaffolderPageContextMenu {...contextMenu} />
+      </Header>
       <Content>
         <ContentHeader title="Available Templates">
           {allowed && (

plugins/scaffolder/src/components/ScaffolderPage/ScaffolderPageContextMenu.test.tsx

@@ -0,0 +1,83 @@
+/*
+ * Copyright 2020 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import userEvent from '@testing-library/user-event';
+import { renderInTestApp } from '@backstage/test-utils';
+import { screen } from '@testing-library/react';
+import React from 'react';
+import { rootRouteRef } from '../../routes';
+import { ScaffolderPageContextMenu } from './ScaffolderPageContextMenu';
+
+describe('ScaffolderPageContextMenu', () => {
+  it('does not render anything if fully disabled', async () => {
+    await renderInTestApp(
+      <div data-testid="container">
+        <ScaffolderPageContextMenu editor={false} actions={false} />
+      </div>,
+      { mountedRoutes: { '/': rootRouteRef } },
+    );
+
+    expect(screen.getByTestId('container')).toBeEmptyDOMElement();
+  });
+
+  it('renders the editor option', async () => {
+    await renderInTestApp(
+      <div data-testid="container">
+        <ScaffolderPageContextMenu actions={false} />
+      </div>,
+      {
+        mountedRoutes: { '/': rootRouteRef },
+      },
+    );
+
+    await userEvent.click(screen.getByTestId('container').firstElementChild!);
+
+    expect(screen.queryByText('Template Editor')).toBeInTheDocument();
+    expect(screen.queryByText('Installed Actions')).not.toBeInTheDocument();
+  });
+
+  it('renders the actions option', async () => {
+    await renderInTestApp(
+      <div data-testid="container">
+        <ScaffolderPageContextMenu actions editor={false} />
+      </div>,
+      {
+        mountedRoutes: { '/': rootRouteRef },
+      },
+    );
+
+    await userEvent.click(screen.getByTestId('container').firstElementChild!);
+
+    expect(screen.queryByText('Template Editor')).not.toBeInTheDocument();
+    expect(screen.queryByText('Installed Actions')).toBeInTheDocument();
+  });
+
+  it('renders all options', async () => {
+    await renderInTestApp(
+      <div data-testid="container">
+        <ScaffolderPageContextMenu />
+      </div>,
+      {
+        mountedRoutes: { '/': rootRouteRef },
+      },
+    );
+
+    await userEvent.click(screen.getByTestId('container').firstElementChild!);
+
+    expect(screen.queryByText('Template Editor')).toBeInTheDocument();
+    expect(screen.queryByText('Installed Actions')).toBeInTheDocument();
+  });
+});

plugins/scaffolder/src/components/ScaffolderPage/ScaffolderPageContextMenu.tsx

@@ -0,0 +1,107 @@
+/*
+ * Copyright 2020 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { useRouteRef } from '@backstage/core-plugin-api';
+import IconButton from '@material-ui/core/IconButton';
+import ListItemIcon from '@material-ui/core/ListItemIcon';
+import ListItemText from '@material-ui/core/ListItemText';
+import MenuItem from '@material-ui/core/MenuItem';
+import MenuList from '@material-ui/core/MenuList';
+import Popover from '@material-ui/core/Popover';
+import { makeStyles } from '@material-ui/core/styles';
+import Description from '@material-ui/icons/Description';
+import Edit from '@material-ui/icons/Edit';
+import MoreVert from '@material-ui/icons/MoreVert';
+import React, { useState } from 'react';
+import { useNavigate } from 'react-router';
+import { rootRouteRef } from '../../routes';
+
+const useStyles = makeStyles({
+  button: {
+    color: 'white',
+  },
+});
+
+export type ScaffolderPageContextMenuProps = {
+  editor?: boolean;
+  actions?: boolean;
+};
+
+export function ScaffolderPageContextMenu(
+  props: ScaffolderPageContextMenuProps,
+) {
+  const classes = useStyles();
+  const [anchorEl, setAnchorEl] = useState<HTMLButtonElement>();
+  const pageLink = useRouteRef(rootRouteRef);
+  const navigate = useNavigate();
+
+  const showEditor = props.editor !== false;
+  const showActions = props.actions !== false;
+
+  if (!showEditor && !showActions) {
+    return null;
+  }
+
+  const onOpen = (event: React.SyntheticEvent<HTMLButtonElement>) => {
+    setAnchorEl(event.currentTarget);
+  };
+
+  const onClose = () => {
+    setAnchorEl(undefined);
+  };
+
+  return (
+    <>
+      <IconButton
+        aria-label="more"
+        aria-controls="long-menu"
+        aria-haspopup="true"
+        onClick={onOpen}
+        data-testid="menu-button"
+        color="inherit"
+        className={classes.button}
+      >
+        <MoreVert />
+      </IconButton>
+      <Popover
+        open={Boolean(anchorEl)}
+        onClose={onClose}
+        anchorEl={anchorEl}
+        anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+        transformOrigin={{ vertical: 'top', horizontal: 'right' }}
+      >
+        <MenuList>
+          {showEditor && (
+            <MenuItem onClick={() => navigate(`${pageLink()}/edit`)}>
+              <ListItemIcon>
+                <Edit fontSize="small" />
+              </ListItemIcon>
+              <ListItemText primary="Template Editor" />
+            </MenuItem>
+          )}
+          {showActions && (
+            <MenuItem onClick={() => navigate(`${pageLink()}/actions`)}>
+              <ListItemIcon>
+                <Description fontSize="small" />
+              </ListItemIcon>
+              <ListItemText primary="Installed Actions" />
+            </MenuItem>
+          )}
+        </MenuList>
+      </Popover>
+    </>
+  );
+}

plugins/scaffolder/src/components/TemplateEditorPage/TemplateEditorPage.tsx

@@ -92,7 +92,7 @@ const useStyles = makeStyles({
   },
 });
 
-export const TemplatePreviewPage = ({
+export const TemplateEditorPage = ({
   defaultPreviewTemplate = EXAMPLE_TEMPLATE_PARAMS_YAML,
   customFieldExtensions = [],
 }: {
@@ -200,7 +200,7 @@ export const TemplatePreviewPage = ({
   return (
     <Page themeId="home">
       <Header
-        title="Template Preview"
+        title="Template Editor"
         subtitle="Preview your template parameter UI"
       />
       <Content>

plugins/scaffolder/src/components/TemplateEditorPage/index.ts

@@ -13,4 +13,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export { TemplatePreviewPage } from './TemplatePreviewPage';
+export { TemplateEditorPage } from './TemplateEditorPage';

plugins/scaffolder/src/next/Router/Router.tsx

@@ -28,6 +28,7 @@ import {
 import { useElementFilter } from '@backstage/core-plugin-api';
 import { TemplateEntityV1beta3 } from '@backstage/plugin-scaffolder-common';
 import { TemplateGroupFilter } from '../TemplateListPage/TemplateGroups';
+import { selectedTemplateRouteRef } from '../../routes';
 
 /**
  * The Props for the Scaffolder Router
@@ -77,7 +78,6 @@ export const Router = (props: PropsWithChildren<NextRouterProps>) => {
   return (
     <Routes>
       <Route
-        path="/"
         element={
           <TemplateListPage
             TemplateCardComponent={TemplateCardComponent}
@@ -87,7 +87,7 @@ export const Router = (props: PropsWithChildren<NextRouterProps>) => {
       />
 
       <Route
-        path="/templates/:templateName"
+        path={selectedTemplateRouteRef.path}
         element={
           <SecretsContextProvider>
             <TemplateWizardPage customFieldExtensions={fieldExtensions} />

plugins/scaffolder/src/routes.ts

@@ -45,3 +45,9 @@ export const actionsRouteRef = createSubRouteRef({
   parent: rootRouteRef,
   path: '/actions',
 });
+
+export const editRouteRef = createSubRouteRef({
+  id: 'scaffolder/edit',
+  parent: rootRouteRef,
+  path: '/edit',
+});