diff --git a/.changeset/khaki-rivers-repeat.md b/.changeset/khaki-rivers-repeat.md new file mode 100644 index 0000000000..e6caa2d561 --- /dev/null +++ b/.changeset/khaki-rivers-repeat.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-badges': patch +--- + +Added details on how to setup the Badges plugin diff --git a/plugins/badges/README.md b/plugins/badges/README.md index bfc01ec63c..b881d100c4 100644 --- a/plugins/badges/README.md +++ b/plugins/badges/README.md @@ -10,8 +10,146 @@ link below for more details. ## Entity badges To get markdown code for the entity badges, access the `Badges` context menu -(three dots in the upper right corner) of an entity page, which will popup a -badges dialog showing all available badges for that entity. +(three dots in the upper right corner) of an entity page like this: + +![Badges Context Menu](./doc/badges-context-menu.png) + +This will popup a badges dialog showing all available badges for that entity like this: + +![Badges Dialog](./doc/badges-dialog.png) + +## Sample Badges + +Here are some samples of badges for the `artists-lookup` service in the Demo Backstage site: + +- Component: [![Link to artist-lookup in Backstage Demo, Component: artist-lookup](https://demo.backstage.io/api/badges/entity/default/component/artist-lookup/badge/pingback 'Link to artist-lookup in Backstage Demo')](https://demo.backstage.io/catalog/default/component/artist-lookup) +- Lifecycle: [![Entity lifecycle badge, lifecycle: experimental](https://demo.backstage.io/api/badges/entity/default/component/artist-lookup/badge/lifecycle 'Entity lifecycle badge')](https://demo.backstage.io/catalog/default/component/artist-lookup) +- Owner: [![Entity owner badge, owner: team-a](https://demo.backstage.io/api/badges/entity/default/component/artist-lookup/badge/owner 'Entity owner badge')](https://demo.backstage.io/catalog/default/component/artist-lookup) +- Docs: [![Entity docs badge, docs: artist-lookup](https://demo.backstage.io/api/badges/entity/default/component/artist-lookup/badge/docs 'Entity docs badge')](https://demo.backstage.io/catalog/default/component/artist-lookup/docs) + +## Usage + +### Install the package + +```bash +yarn add @backstage/plugin-badges +``` + +### Register plugin + +This plugin requires explicit registration, so you will need to add it to your App's `plugins.ts` file: + +```ts +// ... +export { badgesPlugin } from '@backstage/plugin-badges'; +``` + +If you don't have a `plugins.ts` file see: [troubleshooting](#troubleshooting) + +### Update your EntityPage + +In your `EntityPage.tsx` file located in `packages\app\src\components\catalog` we'll need to make a few changes to get the Badges context menu added to the UI. + +First we need to add the following imports: + +```ts +import { EntityBadgesDialog } from '@backstage/plugin-badges'; +import BadgeIcon from '@material-ui/icons/CallToAction'; +``` + +Next we'll update the React import that looks like this: + +```ts +import React from 'react'; +``` + +To look like this: + +```ts +import React, { ReactNode, useMemo, useState } from 'react'; +``` + +Then we have to add this chunk of code after all the imports but before any of the other code: + +```ts +const EntityLayoutWrapper = (props: { children?: ReactNode }) => { + const [badgesDialogOpen, setBadgesDialogOpen] = useState(false); + + const extraMenuItems = useMemo(() => { + return [ + { + title: 'Badges', + Icon: BadgeIcon, + onClick: () => setBadgesDialogOpen(true), + }, + ]; + }, []); + + return ( + <> + + {props.children} + + setBadgesDialogOpen(false)} + /> + + ); +}; +``` + +The last step is to wrap all the entity pages in the `EntityLayoutWrapper` like this: + +```diff +const defaultEntityPage = ( ++ + + {overviewContent} + + + + + + + + + ++ +); +``` + +Note: the above only shows an example for the `defaultEntityPage` for a full example of this you can look at [this EntityPage](https://github.com/backstage/backstage/blob/1fd9e6f601cabe42af8eb20b5d200ad1988ba309/packages/app/src/components/catalog/EntityPage.tsx#L318) + +## Troubleshooting + +If you don't have a `plugins.ts` file, you can create it with the path `packages/app/src/plugins.ts` and then import it into your `App.tsx`: + +```diff ++ import * as plugins from './plugins'; + +const app = createApp({ + apis, ++ plugins: Object.values(plugins), + bindRoutes({ bind }) { + /* ... */ + }, +}); +``` + +Or simply edit `App.tsx` with: + +```diff ++ import { badgesPlugin } from '@backstage/plugin-badges' + +const app = createApp({ + apis, ++ plugins: [badgesPlugin], + bindRoutes({ bind }) { + /* ... */ + }, +}); +``` ## Links diff --git a/plugins/badges/doc/badges-context-menu.png b/plugins/badges/doc/badges-context-menu.png new file mode 100644 index 0000000000..b25f293b5c Binary files /dev/null and b/plugins/badges/doc/badges-context-menu.png differ diff --git a/plugins/badges/doc/badges-dialog.png b/plugins/badges/doc/badges-dialog.png new file mode 100644 index 0000000000..e1deee96c4 Binary files /dev/null and b/plugins/badges/doc/badges-dialog.png differ diff --git a/plugins/badges/package.json b/plugins/badges/package.json index 16e5121132..0fcb18ca04 100644 --- a/plugins/badges/package.json +++ b/plugins/badges/package.json @@ -10,6 +10,12 @@ "main": "dist/index.esm.js", "types": "dist/index.d.ts" }, + "homepage": "https://backstage.io", + "repository": { + "type": "git", + "url": "https://github.com/backstage/backstage", + "directory": "plugins/badges" + }, "scripts": { "build": "backstage-cli plugin:build", "start": "backstage-cli plugin:serve",