From 0a13a11f7bfa24f6806498040f856d0933d9c394 Mon Sep 17 00:00:00 2001 From: Ivan Shmidt Date: Wed, 3 Jun 2020 16:40:13 +0200 Subject: [PATCH] Enforcing RouteRefs more: docs, templates, types --- docs/getting-started/structure-of-a-plugin.md | 14 +++-- docs/reference/createPlugin-router.md | 53 ++++++++++++++----- .../default-plugin/src/plugin.ts.hbs | 10 +++- packages/core-api/src/app/App.tsx | 15 +++++- packages/core-api/src/plugin/Plugin.tsx | 23 +++++++- packages/core-api/src/plugin/types.ts | 8 +++ 6 files changed, 102 insertions(+), 21 deletions(-) diff --git a/docs/getting-started/structure-of-a-plugin.md b/docs/getting-started/structure-of-a-plugin.md index 361546a1b6..b5f104d493 100644 --- a/docs/getting-started/structure-of-a-plugin.md +++ b/docs/getting-started/structure-of-a-plugin.md @@ -43,13 +43,19 @@ In the root folder you have some configuration for typescript and jest, the test In the `src` folder we get to the interesting bits. Check out the `plugin.ts`: ```jsx -import { createPlugin } from '@backstage/core'; +import { createPlugin, createRouteRef } from '@backstage/core'; import ExampleComponent from './components/ExampleComponent'; -export default createPlugin({ - id: 'new-plugin', +export const rootRouteRef = createRouteRef({ + icon: () => null, + path: '/{{ id }}', + title: '{{ id }}', +}); + +export const plugin = createPlugin({ + id: '{{ id }}', register({ router }) { - router.registerRoute('/new-plugin', ExampleComponent); + router.addRoute(rootRouteRef, ExampleComponent); }, }); ``` diff --git a/docs/reference/createPlugin-router.md b/docs/reference/createPlugin-router.md index fa1a9cfa5b..84755e6c4d 100644 --- a/docs/reference/createPlugin-router.md +++ b/docs/reference/createPlugin-router.md @@ -1,21 +1,48 @@ # createPlugin - router -The router that is passed to the `register` function includes makes it possible for plugins to hook into routing of the Backstage app and provide the end users with new views to navigate to. +The router that is passed to the `register` function makes it possible for plugins to hook into routing of the Backstage app and provide the end users with new views to navigate to. +This is done by utilising the following methods on the `router`: ```typescript -type RouterHooks = { - registerRoute( - path: RoutePath, - Component: ComponentType, - options?: RouteOptions, - ): void; +addRoute( + target: RouteRef, + Component: ComponentType, + options?: RouteOptions, +): void; - registerRedirect( - path: RoutePath, - target: RoutePath, - options?: RouteOptions, - ): void; -}; +addRedirect(from: RouteRef, to: RouteRef, options?: RouteOptions): void; + +/** + * @deprecated See the `addRoute` method + */ +registerRoute( + path: RoutePath, + Component: ComponentType, + options?: RouteOptions, +): void; + +/** + * @deprecated See the `addRedirect` method + */ +registerRedirect( + path: RoutePath, + target: RoutePath, + options?: RouteOptions, +): void; +``` + +## RouteRef + +Both `addRoute` and `addRedirect` methods are using mutable RouteRefs, which can be created as following: + +```ts +import { createRouteRef } from '@backstage/core'; + +const myPluginRouteRef = createRouteRef({ + icon: () => null, // You can set an icon for your route + path: '/my-plugin', + title: 'My Plugin', +}); ``` [Back to References](README.md) diff --git a/packages/cli/templates/default-plugin/src/plugin.ts.hbs b/packages/cli/templates/default-plugin/src/plugin.ts.hbs index 61d82fca53..4b5ab9811a 100644 --- a/packages/cli/templates/default-plugin/src/plugin.ts.hbs +++ b/packages/cli/templates/default-plugin/src/plugin.ts.hbs @@ -14,12 +14,18 @@ * limitations under the License. */ -import { createPlugin } from '@backstage/core'; +import { createPlugin, createRouteRef } from '@backstage/core'; import ExampleComponent from './components/ExampleComponent'; +export const rootRouteRef = createRouteRef({ + icon: () => null, + path: '/{{ id }}', + title: '{{ id }}', +}); + export const plugin = createPlugin({ id: '{{ id }}', register({ router }) { - router.registerRoute('/{{ id }}', ExampleComponent); + router.addRoute(rootRouteRef, ExampleComponent); }, }); diff --git a/packages/core-api/src/app/App.tsx b/packages/core-api/src/app/App.tsx index 282e0aa474..575dcfc59d 100644 --- a/packages/core-api/src/app/App.tsx +++ b/packages/core-api/src/app/App.tsx @@ -110,7 +110,7 @@ export class PrivateAppImpl implements BackstageApp { ); break; } - case 'redirect-route': { + case 'legacy-redirect-route': { const { path, target, options = {} } = output; const { exact = true } = options; routes.push( @@ -118,6 +118,19 @@ export class PrivateAppImpl implements BackstageApp { ); break; } + case 'redirect-route': { + const { from, to, options = {} } = output; + const { exact = true } = options; + routes.push( + , + ); + break; + } case 'feature-flag': { registeredFeatureFlags.push({ pluginId: plugin.getId(), diff --git a/packages/core-api/src/plugin/Plugin.tsx b/packages/core-api/src/plugin/Plugin.tsx index ed3179296f..b76457a7f4 100644 --- a/packages/core-api/src/plugin/Plugin.tsx +++ b/packages/core-api/src/plugin/Plugin.tsx @@ -42,12 +42,20 @@ export type RouterHooks = { options?: RouteOptions, ): void; + addRedirect(from: RouteRef, to: RouteRef, options?: RouteOptions): void; + + /** + * @deprecated See the `addRoute` method + */ registerRoute( path: RoutePath, Component: ComponentType, options?: RouteOptions, ): void; + /** + * @deprecated See the `addRedirect` method + */ registerRedirect( path: RoutePath, target: RoutePath, @@ -88,11 +96,24 @@ export class PluginImpl { options, }); }, + addRedirect(from, to, options) { + outputs.push({ + type: 'redirect-route', + from, + to, + options, + }); + }, registerRoute(path, component, options) { outputs.push({ type: 'legacy-route', path, component, options }); }, registerRedirect(path, target, options) { - outputs.push({ type: 'redirect-route', path, target, options }); + outputs.push({ + type: 'legacy-redirect-route', + path, + target, + options, + }); }, }, featureFlags: { diff --git a/packages/core-api/src/plugin/types.ts b/packages/core-api/src/plugin/types.ts index 8dcbcda0a3..fabe97434e 100644 --- a/packages/core-api/src/plugin/types.ts +++ b/packages/core-api/src/plugin/types.ts @@ -41,6 +41,13 @@ export type RouteOutput = { export type RedirectRouteOutput = { type: 'redirect-route'; + from: RouteRef; + to: RouteRef; + options?: RouteOptions; +}; + +export type LegacyRedirectRouteOutput = { + type: 'legacy-redirect-route'; path: RoutePath; target: RoutePath; options?: RouteOptions; @@ -56,6 +63,7 @@ export type FeatureFlagOutput = { export type PluginOutput = | LegacyRouteOutput | RouteOutput + | LegacyRedirectRouteOutput | RedirectRouteOutput | FeatureFlagOutput;