diff --git a/plugins/explore-backend/README.md b/plugins/explore-backend/README.md index db7d7c7bc6..927cc47fd7 100644 --- a/plugins/explore-backend/README.md +++ b/plugins/explore-backend/README.md @@ -26,7 +26,18 @@ import { } from '@backstage/plugin-explore-backend'; import { Router } from 'express'; import { PluginEnvironment } from '../types'; -import { exploreTools } from '../path/to/your/exploreTools'; + +// List of tools you want to surface in the Explore plugin "Tools" page. +const tools: ExploreTool[] = [ + { + title: 'New Relic', + description:'new relic plugin', + url: '/newrelic', + image: 'https://i.imgur.com/L37ikrX.jpg', + tags: ['newrelic', 'proxy', 'nerdGraph'], + }, + ... +]; export default async function createPlugin( env: PluginEnvironment, @@ -83,3 +94,51 @@ async function createSearchEngine( ### Wire up the Frontend See [the explore plugin README](../explore/README.md) for more information. + +## Explore Tool Customization + +The `explore-backend` uses the `ExploreToolProvider` interface to provide a list +of tools used in your organization and/or within your Backstage instance. This +can be overriden to provide tools from any source. For example you could create +a `CustomExploreToolProvider` that queries an internal for tools in your +`packages/backend/src/plugins/explore.ts` file. + +```ts +import { + createRouter, + StaticExploreToolProvider, +} from '@backstage/plugin-explore-backend'; +import { Router } from 'express'; +import { PluginEnvironment } from '../types'; + +class CustomExploreToolProvider implements ExploreToolProvider { + async getTools( + request: GetExploreToolsRequest, + ): Promise { + const externalTools = await queryExternalTools(request); + + const tools: ExploreTool[] = [ + ...externalTools, + // Backstage Tools + { + title: 'New Relic', + description: 'new relic plugin', + url: '/newrelic', + image: 'https://i.imgur.com/L37ikrX.jpg', + tags: ['newrelic', 'proxy', 'nerdGraph'], + }, + ]; + + return { tools }; + } +} + +export default async function createPlugin( + env: PluginEnvironment, +): Promise { + return await createRouter({ + logger: env.logger, + toolProvider: new CustomExploreToolProvider(), + }); +} +``` diff --git a/plugins/explore-backend/src/tools/index.ts b/plugins/explore-backend/src/tools/index.ts index 7c34ce56b8..5e605e0142 100644 --- a/plugins/explore-backend/src/tools/index.ts +++ b/plugins/explore-backend/src/tools/index.ts @@ -14,5 +14,5 @@ * limitations under the License. */ -export { StaticExploreToolProvider } from './providers'; -export type { ExploreToolProvider } from './types'; +export { StaticExploreToolProvider } from './providers/StaticExploreToolProvider'; +export * from './types'; diff --git a/plugins/explore-backend/src/tools/providers.test.ts b/plugins/explore-backend/src/tools/providers/StaticExploreToolProvider.test.ts similarity index 97% rename from plugins/explore-backend/src/tools/providers.test.ts rename to plugins/explore-backend/src/tools/providers/StaticExploreToolProvider.test.ts index 7a219e49fd..626426eed9 100644 --- a/plugins/explore-backend/src/tools/providers.test.ts +++ b/plugins/explore-backend/src/tools/providers/StaticExploreToolProvider.test.ts @@ -15,7 +15,7 @@ */ import { ExploreTool } from '@backstage/plugin-explore-common'; -import { StaticExploreToolProvider } from './providers'; +import { StaticExploreToolProvider } from './StaticExploreToolProvider'; describe('StaticExploreToolProvider', () => { const tool1: ExploreTool = { diff --git a/plugins/explore-backend/src/tools/providers.ts b/plugins/explore-backend/src/tools/providers/StaticExploreToolProvider.ts similarity index 97% rename from plugins/explore-backend/src/tools/providers.ts rename to plugins/explore-backend/src/tools/providers/StaticExploreToolProvider.ts index 7a87824776..ad8bcafada 100644 --- a/plugins/explore-backend/src/tools/providers.ts +++ b/plugins/explore-backend/src/tools/providers/StaticExploreToolProvider.ts @@ -20,7 +20,7 @@ import { GetExploreToolsResponse, } from '@backstage/plugin-explore-common'; import { intersection, isEmpty } from 'lodash'; -import { ExploreToolProvider } from './types'; +import { ExploreToolProvider } from '../types'; const anyOf = (prop: T | T[], matches: T[]) => isEmpty(matches) diff --git a/plugins/explore/README.md b/plugins/explore/README.md index 94ab0984a0..e8bd4446d9 100644 --- a/plugins/explore/README.md +++ b/plugins/explore/README.md @@ -1,42 +1,105 @@ # explore Welcome to the explore plugin! + This plugin helps to visualize the domains and tools in your ecosystem. -## Getting started +## Setup -To install the plugin, add and bind the route in `App.tsx`: +The following sections will help you get the Explore plugin setup and running. -```typescript -import { ExplorePage, explorePlugin } from '@backstage/plugin-explore'; +### Backend -... +You need to setup the +[Explore backend plugin](https://github.com/backstage/backstage/tree/master/plugins/explore-backend) +before you move forward with any of these steps if you haven't already. -bindRoutes({ bind }) { - ... - bind(explorePlugin.externalRoutes, { - catalogEntity: catalogPlugin.routes.catalogEntity, - }); -}, +### Installation -... +Install this plugin: -} /> +```bash +# From your Backstage root directory +yarn --cwd packages/app add @backstage/plugin-explore ``` -And add a link to the sidebar in `Root.tsx`: +### Add the plugin to your `packages/app` -```typescript -import LayersIcon from '@material-ui/icons/Layers'; +Add the root page that the playlist plugin provides to your app. You can choose +any path for the route, but we recommend the following: + +```diff +// packages/app/src/App.tsx ++ import { ExplorePage, explorePlugin } from '@backstage/plugin-explore'; ... - + + } /> + }> + {entityPage} + ++ } /> + ... + +``` + +You may also want to add a link to the playlist page to your application +sidebar: + +```diff +// packages/app/src/components/Root/Root.tsx ++import LayersIcon from '@material-ui/icons/Layers'; + +export const Root = ({ children }: PropsWithChildren<{}>) => ( + + ++ + ... + +``` + +### Use earch result list item for Explore Tools + +When you have your `packages/app/src/components/search/SearchPage.tsx` file +ready to make modifications, add the following code snippet to add the +`ToolSearchResultListItem` when the type of the search results are +`tool`. + +```diff ++import { ToolSearchResultListItem } from '@backstage/plugin-explore'; + +const SearchPage = () => { + ... + + {({ results }) => ( + + {results.map(({ type, document, highlight, rank }) => { + switch (type) { + ... ++ case 'tools': ++ return ( ++ } ++ key={document.location} ++ result={document} ++ highlight={highlight} ++ rank={rank} ++ /> ++ ); + } + })} + + )} + ... + +... ``` ## Customization -Create a custom explore page in `packages/app/src/components/explore/ExplorePage.tsx`. +Create a custom explore page in +`packages/app/src/components/explore/ExplorePage.tsx`. ```tsx import { @@ -68,7 +131,7 @@ export const explorePage = ; Now register the new explore page in `packages/app/src/App.tsx`. ```diff -+ import { explorePage } from './components/explore/ExplorePage'; ++import { explorePage } from './components/explore/ExplorePage'; const routes = ( @@ -79,39 +142,3 @@ const routes = ( ); ``` - -## ToolExplorer Content Customization - -Override the `exploreToolsConfigRef` API in `/packages/app/src/apis.ts`. - -```tsx -import { exploreToolsConfigRef } from '@backstage/plugin-explore-react'; - -export const apis: AnyApiFactory[] = [ - ... - - createApiFactory({ - api: exploreToolsConfigRef, - deps: {}, - factory: () => ({ - async getTools() { - return tools; - }, - /* e.g. tools = [ - { - title: 'New Relic', - description:'new relic plugin, - url: '/newrelic', - image: 'https://i.imgur.com/L37ikrX.jpg', - tags: ['newrelic', 'proxy', 'nerdGraph'], - }, - ] - */ - }), - }), - - .... - -]; - -```