Project: Backstage (App Definition and Development / Application Definition & Image Build)
File: README-alpha.md

[!WARNING] This documentation is made for those using the experimental new Frontend system. If you are not using the new frontend system, please go . This is a plugin that extends the Catalog entity page with some users and groups overview cards: Group Profile Entity Card Member List Entity Card Ownership Entity Card User Profile Entity Card Here is a Catalog group page showing the group profile, members, and ownership cards: And below is an example of how a user page looks with the user profile and ownership cards: - - - Install the `org` plugin in your Backstage app: ```bash yarn --cwd packages/app add @backstage/plugin-org ``` Enable which entity cards and tabs you would like to see on the catalog entity page: > [!IMPORTANT] > The order in which cards are listed in the configuration file will determine the order in which they appear in overview cards and tab lists on entity pages. ```yaml app: experimental: packages: all extensions: entity-card:org/group-profile entity-card:org/members-list entity-card:org/ownership entity-card:org/user-profile ``` Then start the app, navigate to an entity's page and see the cards and contents in there. The `org` plugin can be automatically discovered, and it is also possible to enable it only in certain . See packages documentation for more details. The `org` plugin exposes an external route ref that can be used to configure route bindings. | Key | Type | Description | | -- | -- | - | | `catalogIndex` | External route | A route ref to Catalog Index page. | As an example, here is an association between the external catalog index page and a regular route from another plugin: ```yaml app: routes: bindings: org.catalogIndex: catalog.catalogIndex ``` Route binding is also possible through code. For more information, see documentation. This extension allows you to view, edit, or update groups metadata, such as team avatar, name, email, parent, and child groups. | Kind | Namespace | Name | Id | | - | | | - | | `entity-card` | `org` | `group-profile` | `entity-card:org/group-profile` | Currently, this entity card extension has only one configuration: | Config key | Default value | Description | | - | - | - | | `filter` | `kind:group` | An that determines when the card should be displayed on the entity page. | This is how to configure the `group-profile` extension in the `app-config.yaml` file: ```yaml app: extensions: entity-card:org/group-profile: config: <Config-Key>: '<Config-Value>' ``` Use extension overrides for completely re-implementing the group-profile entity card extension: ```tsx import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; export default createExtensionOverrides({ extensions: [ createEntityCardExtension({ // These namespace and name are necessary so the system knows that this extension will override the default 'group-profile' entity card extension provided by the 'org' plugin namespace: 'org', name: 'group-profile', // By default, this card will show up only for groups filter: 'kind:group' // Returing a custom card component loader: () => import('./components').then(m =>

/>), }), ], }); ``` For more information about where to place extension overrides, see the official . An extension that displays the names and emails of group members. By clicking the member's name, you'll be directed to the user's catalog page, and the email opens your default email program. | Kind | Namespace | Name | Id | | - | | -- | | | `entity-card` | `org` | `members-list` | `entity-card:org/members-list` | Currently, this entity card extension has only one configuration: | Config key | Default value | Description | | - | - | - | | `filter` | `kind:group` | An that determines when the card should be displayed on the entity page. | This is how to configure the `members-list` extension in the `app-config.yaml` file: ```yaml app: extensions: entity-card:org/members-list: config: <Config-Key>: '<Config-Value>' ``` Use extension overrides for completely re-implementing the members-list entity card extension: ```tsx import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; export default createExtensionOverrides({ extensions: [ createEntityCardExtension({ // These namespace and name are necessary so the system knows that this extension will override the default 'members-list' entity card extension provided by the 'org' plugin namespace: 'org', name: 'members-list', // By default, this card will show up only for groups filter: 'kind:group' // Returing a custom card component loader: () => import('./components').then(m => <m.MyCustomMembersListEntityCard />), }), ], }); ``` For more information about where to place extension overrides, see the official . An extension that displays direct or aggregated group or user ownership relationships. Each entity listed in the card links to its respective entity page in the catalog. | Kind | Namespace | Name | Id | | - | | -- | | | `entity-card` | `org` | `ownership` | `entity-card:org/ownership` | Currently, this entity card extension has only one configuration: | Config key | Default value | Description | | - | -- | - | | `filter` | `kind:group,user` | An that determines when the card should be displayed on the entity page. | This is how to configure the `ownership` extension in the `app-config.yaml` file: ```yaml app: extensions: entity-card:org/ownership: config: <Config-Key>: '<Config-Value>' ``` Use extension overrides for completely re-implementing the ownership entity card extension: ```tsx import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; export default createExtensionOverrides({ extensions: [ createEntityCardExtension({ // These namespace and name are necessary so the system knows that this extension will override the default 'ownership' entity card extension provided by the 'org' plugin namespace: 'org', name: 'ownership', // By default, this card will show up only for groups or users filter: 'kind:group,user' // Returing a custom card component loader: () => import('./components').then(m => <m.MyCustomOwnershipEntityCard />), }), ], }); ``` For more information about where to place extension overrides, see the official . This extension allows you to view user metadata including avatar, name, email, and

Clicking on the email link will open your default email program while clicking on the team link will direct you to the team page in the catalog plugin. | Kind | Namespace | Name | Id | | - | | -- | | | `entity-card` | `org` | `user-profile` | `entity-card:org/user-profile` | Currently, this entity card extension has only one configuration: | Config key | Default value | Description | | - | - | - | | `filter` | `kind:user` | An that determines when the card should be displayed on the entity page. | This is how to configure the `user-profile` extension in the `app-config.yaml` file: ```yaml app: extensions: entity-card:org/user-profile: config: <Config-Key>: '<Config-Value>' ``` Use extension overrides for completely re-implementing the user-profile entity card extension: ```tsx import { createExtensionOverrides } from '@backstage/backstage-plugin-api'; import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha'; export default createExtensionOverrides({ extensions: [ createEntityCardExtension({ // These namespace and name are necessary so the system knows that this extension will override the default 'user-profile' entity card extension provided by the 'org' plugin namespace: 'org', name: 'user-profile', // By default, this card will show up only for groups or users filter: 'kind:user' // Returing a custom card component loader: () => import('./components').then(m => <m.MyCustomOwnershipEntityCard />), }), ], }); ``` For more information about where to place extension overrides, see the official . As the extension type does not support conditional rendering, this plugin does not provide navigation items, so to use the `MyGroupsSidebarItem` component, we recommend overriding the extension and adding the item statically. [!IMPORTANT] As you can see in the example below, we are using the same attachment point, inputs and outputs as the default App/Nav extension to avoid side effects on the NavItem and NavLogo extensions. ```tsx // ... import { MyGroupsSidebarItem } from '@backstage/plugin-org'; import GroupIcon from '@material-ui/icons/People'; export default createExtensionOverrides({ extensions: [ createExtension({ // These namespace and name are necessary so the system knows that this extension will override the default app nav extension namespace: 'app', name: 'nav', // Keeping the same attachment point as in the default App/Nav extension attachTo: { id: 'app/layout', input: 'nav' }, // Keeping the same inputs as in the default App/Nav extension inputs: { items: createExtensionInput({ target: createNavItemExtension.targetDataRef, }), logos: createExtensionInput( { elements: createNavLogoExtension.logoElementsDataRef, }, { singleton: true, optional: true, }, ), }, // Keeping the same output as in the default App/Nav extension output: { element: coreExtensionData.reactElement, }, factory({ inputs }) { return { element: ( <Sidebar> {/ Code borrowed from the default extension implementation to render the logos and items inputs /} <SidebarLogo {...inputs.logos?.output.elements} /> <SidebarDivider /> {inputs.items.map((item, index) => ( <SidebarNavItem {...item.output.target} key={index} /> ))} {/ Here is where we actually modifies the default implementation by adding a static item to render a group of squad pages /} <SidebarGroup label="Menu" icon={<MenuIcon />}> {/ The MyGroupsSidebarItem provides quick access to the group(s) the logged in user is a member of directly in the sidebar. /} <MyGroupsSidebarItem singularTitle="My Squad" pluralTitle="My Squads" icon={GroupIcon} /> </SidebarGroup> </Sidebar> ), }; }, }), ], }); ```