diff --git a/.changeset/stupid-bottles-bow.md b/.changeset/stupid-bottles-bow.md new file mode 100644 index 0000000000..40fa14c196 --- /dev/null +++ b/.changeset/stupid-bottles-bow.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog': patch +--- + +Added support for passing in custom filters to `CatalogIndexPage` diff --git a/docs/features/software-catalog/catalog-customization.md b/docs/features/software-catalog/catalog-customization.md index c2ffa0c22a..3dc47a610a 100644 --- a/docs/features/software-catalog/catalog-customization.md +++ b/docs/features/software-catalog/catalog-customization.md @@ -5,64 +5,232 @@ title: Catalog Customization description: How to add custom filters or interface elements to the Backstage software catalog --- -The Backstage software catalog comes with a default `CatalogIndexPage` to filter -and find catalog entities. This is already set up by default by -`@backstage/create-app`. +The Backstage software catalog comes with a default `CatalogIndexPage` to filter and find catalog entities. This is already set up by default by `@backstage/create-app`. If you want to change the default index page - to set the initially selected filter, adjust columns, add actions, or to add a custom filter to the catalog - the following sections will show you how. -If you want to change the default index page - such as to add a custom filter to -the catalog - you can create your own `CatalogIndexPage`. +## Pagination -> Note: The catalog index page is designed to have a minimal code footprint to -> support easy customization, but creating a copy does introduce a possibility -> of drifting out of date over time. Be sure to check the catalog -> [CHANGELOG](https://github.com/backstage/backstage/blob/master/plugins/catalog/CHANGELOG.md) -> periodically. +Initial support for pagination of the `CatalogIndexPage` was added in v1.21.0 of Backstage, so make sure you are on that version or newer to use this feature. To enable pagination you simply need to pass in the `pagination` prop like this: -For example, suppose that I want to allow filtering by a custom annotation added -to entities, `company.com/security-tier`. To start, I'll copy the code for the -default catalog page and create a component. - -```tsx -// imports, etc omitted for brevity. for full source see: -// https://github.com/backstage/backstage/blob/master/plugins/catalog/src/components/CatalogPage/DefaultCatalogPage.tsx -export const CustomCatalogPage = ({ - columns, - actions, - initiallySelectedFilter = 'owned', -}: CatalogPageProps) => { - const createComponentLink = useRouteRef( - catalogPlugin.externalRoutes.createComponent, - ); - return ( - - - - }> - - All your software catalog entities - - - - - - - - - - - - - - - ); -}; +```tsx title="packages/app/src/App.tsx" +} /> ``` -The `EntityListProvider` shown here provides a list of entities from the -`catalog-backend`, and a way to hook in filters. +## Initially Selected Filter -Now we're ready to create a new filter that implements the `EntityFilter` -interface: +By default the initially selected filter defaults to Owned. If you are still building up your catalog this may show an empty list to start. If you would prefer this to show All as the default, here's how you can make that change: + +```tsx title="packages/app/src/App.tsx" +} +/> +``` + +Possible options are: owned, starred, or all + +## Initially Selected Kind + +By default the initially selected Kind when viewing the Catalog is Component, but you may have reasons that you want this to be different. Let's say at your Organization they would like it to always default to Domain, here's how you would do that: + +```tsx title="packages/app/src/App.tsx" +} /> +``` + +Possible options are all the [default Kinds](system-model.md) as well as any custom Kinds that you have added. + +## Owner Picker Mode + +The Owner filter by default will only contain a list of Users and/or Groups that actually own an entity in the Catalog, now you may have reason to change this. Here's how: + +```tsx title="packages/app/src/App.tsx" +} /> +``` + +Possible options are: owners-only or all + +## Table Options + +The tables used within Backstage are built on top of [`@material-table/core`](https://material-table-core.github.io/) and the `CatalogIndexPage` has a `tableOptions` prop that allows you to customize the underlying table to a certain extent, but there are some hard coded Backstage settings that can't be changed. Here's an example of how to use this prop to disable the search filter field in the table's header: + +```tsx title="packages/app/src/App.tsx" +} +/> +``` + +There are many options that can be set using `tableOptions`, the full list of settings can be found in the [`@material-table/core` `Options` interface](https://github.com/material-table-core/core/blob/v3.1.0/types/index.d.ts#L323) (this link goes to `v3.1.0` of `@material-table/core` as that is the version currently used by Backstage). + +## Customize Columns + +By default the columns you see in the `CatalogIndexPage` were selected to be a good starting point for most but there may be reasons that you would like to customize these with more or less columns. One primary use case for this customization is if you added a custom Kind. Support for this was added in v1.23.0 of Backstage, make sure you are on that version or newer to use this feature. Here's an example of how to make this customization: + +```tsx title="packages/app/src/App.tsx" +import { + CatalogEntityPage, + CatalogIndexPage, + catalogPlugin, + {/* highlight-add-start */} + CatalogTable, + CatalogTableColumnsFunc, + {/* highlight-add-end */} +} from '@backstage/plugin-catalog'; + +{/* highlight-add-start */} +const myColumnsFunc: CatalogTableColumnsFunc = entityListContext => { + if (entityListContext.filters.kind?.value === 'MyKind') { + return [ + CatalogTable.columns.createNameColumn(), + CatalogTable.columns.createOwnerColumn(), + ]; + } + + return CatalogTable.defaultColumnsFunc(entityListContext); +}; +{/* highlight-add-end */} + +{/* highlight-remove-next-line */} +} /> +{/* highlight-add-next-line */} +} /> +``` + +> Note: the above example has been simplified and you will most likely have more code then just this in your `App.tsx` file. + +## Customize Actions + +The `CatalogIndexPage` comes with three default actions - view, edit, and star. You might want to add more. + +To do this, first you'll need to add `@mui/utils` to your `packages/app/package.json`: + +```sh +yarn --cwd packages/app add @mui/utils +``` + +Then you'll do the following: + +```tsx title="packages/app/src/App.tsx" +import { + AlertDisplay, + OAuthRequestDialog, + SignInPage, + {/* highlight-add-next-line */} + TableProps, +} from '@backstage/core-components'; + +import { + CatalogEntityPage, + CatalogIndexPage, + {/* highlight-add-next-line */} + CatalogTableRow, + catalogPlugin, +} from '@backstage/plugin-catalog'; + +{/* highlight-add-start */} +import { Typography } from '@material-ui/core'; +import OpenInNew from '@material-ui/icons/OpenInNew'; +import { visuallyHidden } from '@mui/utils'; +{/* highlight-add-end */} + +{/* highlight-add-start */} +const customActions: TableProps['actions'] = [ + ({ entity }) => { + const url = 'https://backstage.io/'; + const title = `View - ${entity.metadata.name}`; + + return { + icon: () => ( + <> + {title} + + + ), + tooltip: title, + disabled: !url, + onClick: () => { + if (!url) return; + window.open(url, '_blank'); + }, + }; + }, +]; +{/* highlight-add-end */} + +{/* highlight-remove-next-line */} +} /> +{/* highlight-add-next-line */} +} /> +``` + +> Note: the above example has been simplified and you will most likely have more code then just this in your `App.tsx` file. + +The above customization will override the existing actions. Currently the only way to keep them and add your own is to also include the existing actions in your array by copying them from the [`defaultActions`](https://github.com/backstage/backstage/blob/57397e7d6d2d725712c439f4ab93f2ac6aa27bf8/plugins/catalog/src/components/CatalogTable/CatalogTable.tsx#L113-L168). + +## Customize Filters + +There are three options you have for filters: adjusting the existing filters with props, adding or removing the default filters, or creating a brand new custom filter. The following sections cover these cases + +### Default Filter Props + +There are a set of default filters that you can use, which surface all the props mentioned earlier in this document. Here's how they can be used: + +```tsx title="packages/app/src/App.tsx" +import { DefaultFilters } from '@backstage/plugin-catalog-react'; + + + + + } + /> + } +/>; +``` + +### Removing Default Filters + +You may have reasons not use the Lifecycle, Tag, and Processing Status filters, here's an example of how you would remove them: + +```tsx title="packages/app/src/App.tsx" +import { + EntityKindPicker, + EntityTypePicker, + UserListPicker, + EntityOwnerPicker, + EntityNamespacePicker, +} from '@backstage/plugin-catalog-react'; + + + + + + + + + } + /> + } +/>; +``` + +### Custom Filters + +You can add custom filters. For example, suppose that I want to allow filtering by a custom annotation added to entities, `company.com/security-tier`. Here is how we can build a filter to support that need. + +First we need to create a new filter that implements the `EntityFilter` interface: ```ts import { EntityFilter } from '@backstage/plugin-catalog-react'; @@ -77,13 +245,9 @@ class EntitySecurityTierFilter implements EntityFilter { } ``` -The `EntityFilter` interface permits backend filters, which are passed along to -the `catalog-backend` - or frontend filters, which are applied after entities -are loaded from the backend. +The `EntityFilter` interface permits backend filters, which are passed along to the `catalog-backend` - or frontend filters, which are applied after entities are loaded from the backend. -We'll use this filter to extend the default filters in a type-safe way. Let's -create the custom filter shape extending the default somewhere alongside this -filter: +We'll use this filter to extend the default filters in a type-safe way. Let's create the custom filter shape extending the default somewhere alongside this filter: ```ts export type CustomFilters = DefaultEntityFilters & { @@ -91,11 +255,7 @@ export type CustomFilters = DefaultEntityFilters & { }; ``` -To control this filter, we can create a React component that shows checkboxes -for the security tiers. This component will make use of the -`useEntityList` hook, which accepts this extended filter type as a -[generic](https://www.typescriptlang.org/docs/handbook/2/generics.html) -parameter: +To control this filter, we can create a React component that shows checkboxes for the security tiers. This component will make use of the `useEntityList` hook, which accepts this extended filter type as a [generic](https://www.typescriptlang.org/docs/handbook/2/generics.html) parameter: ```tsx export const EntitySecurityTierPicker = () => { @@ -140,36 +300,109 @@ export const EntitySecurityTierPicker = () => { }; ``` -Now we can add the component to `CustomCatalogPage`: +Now we can add the component to `CatalogIndexPage`: -```tsx -export const CustomCatalogPage = ({ - columns, - actions, - initiallySelectedFilter = 'owned', -}: CatalogPageProps) => { - return ( +```tsx title="packages/app/src/App.tsx" +{ + /* highlight-add-start */ +} +import { DefaultFilters } from '@backstage/plugin-catalog-react'; +{ + /* highlight-add-end */ +} + +const routes = ( + + + {/* highlight-remove-next-line */} + } /> + {/* highlight-add-start */} + + + + + } + /> + } + /> + {/* highlight-add-end */} {/* ... */} - + +); +``` + +The same method can be used to customize the _default_ filters with a different interface - for such usage, the generic argument isn't needed since the filter shape remains the same as the default. + +## Advanced Customization + +For those where none of the above fits their needs you can take the option of creating a fully custom `CatalogIndexPage`. + +```tsx title="packages/app/src/components/catalog/CustomCatalogIndex.tsx" +import { + PageWithHeader, + Content, + ContentHeader, + SupportButton, +} from '@backstage/core-components'; +import { useApi, configApiRef } from '@backstage/core-plugin-api'; +import { CatalogTable } from '@backstage/plugin-catalog'; +import { + EntityListProvider, + CatalogFilterLayout, + EntityKindPicker, + EntityLifecyclePicker, + EntityNamespacePicker, + EntityOwnerPicker, + EntityProcessingStatusPicker, + EntityTagPicker, + EntityTypePicker, + UserListPicker, +} from '@backstage/plugin-catalog-react'; +import React from 'react'; + +export const CustomCatalogPage = () => { + const orgName = + useApi(configApiRef).getOptionalString('organization.name') ?? 'Backstage'; + + return ( + + + + All your software catalog entities + + - - {/* ... */} + + + ); }; ``` -Finally, we can apply our new `CustomCatalogPage`. +The above is a very basic version of a fully custom `CatalogIndexPage`, you'll want to explore the various props to see what you can all do with them. This was built off the building blocks seen in the [`DefaultCatalogPage`](https://github.com/backstage/backstage/blob/master/plugins/catalog/src/components/CatalogPage/DefaultCatalogPage.tsx) + +> Note: The catalog index page is designed to have a minimal code footprint to support easy customization, but creating a replica does introduce a possibility of drifting out of date over time. Be sure to check the catalog [CHANGELOG](https://github.com/backstage/backstage/blob/master/plugins/catalog/CHANGELOG.md) periodically. + +To use this custom `CatalogIndexPage` which we called `CustomCatalogPage`, you'll need to make the following change: ```tsx title="packages/app/src/App.tsx" const routes = ( @@ -186,7 +419,3 @@ const routes = ( ); ``` - -The same method can be used to customize the _default_ filters with a different -interface - for such usage, the generic argument isn't needed since the filter -shape remains the same as the default. diff --git a/plugins/catalog-react/api-report.md b/plugins/catalog-react/api-report.md index 57fa247171..39db26df74 100644 --- a/plugins/catalog-react/api-report.md +++ b/plugins/catalog-react/api-report.md @@ -172,6 +172,18 @@ export function defaultEntityPresentation( }, ): EntityRefPresentationSnapshot; +// @public (undocumented) +export const DefaultFilters: ( + props: DefaultFiltersProps, +) => React_2.JSX.Element; + +// @public +export type DefaultFiltersProps = { + initialKind?: string; + initiallySelectedFilter?: UserListFilterKind; + ownerPickerMode?: EntityOwnerPickerProps['mode']; +}; + // @public (undocumented) export function EntityAutocompletePicker< T extends DefaultEntityFilters = DefaultEntityFilters, diff --git a/plugins/catalog-react/src/components/DefaultFilters/DefaultFilters.tsx b/plugins/catalog-react/src/components/DefaultFilters/DefaultFilters.tsx new file mode 100644 index 0000000000..45625c716f --- /dev/null +++ b/plugins/catalog-react/src/components/DefaultFilters/DefaultFilters.tsx @@ -0,0 +1,57 @@ +/* + * Copyright 2024 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 React from 'react'; +import { UserListFilterKind } from '../../types'; +import { EntityKindPicker } from '../EntityKindPicker'; +import { EntityLifecyclePicker } from '../EntityLifecyclePicker'; +import { EntityNamespacePicker } from '../EntityNamespacePicker'; +import { + EntityOwnerPickerProps, + EntityOwnerPicker, +} from '../EntityOwnerPicker'; +import { EntityProcessingStatusPicker } from '../EntityProcessingStatusPicker'; +import { EntityTagPicker } from '../EntityTagPicker'; +import { EntityTypePicker } from '../EntityTypePicker'; +import { UserListPicker } from '../UserListPicker'; + +/** + * Props for default filters. + * + * @public + */ +export type DefaultFiltersProps = { + initialKind?: string; + initiallySelectedFilter?: UserListFilterKind; + ownerPickerMode?: EntityOwnerPickerProps['mode']; +}; + +/** @public */ +export const DefaultFilters = (props: DefaultFiltersProps) => { + const { initialKind, initiallySelectedFilter, ownerPickerMode } = props; + return ( + <> + + + + + + + + + + ); +}; diff --git a/plugins/catalog-react/src/components/DefaultFilters/index.ts b/plugins/catalog-react/src/components/DefaultFilters/index.ts new file mode 100644 index 0000000000..d7debdea37 --- /dev/null +++ b/plugins/catalog-react/src/components/DefaultFilters/index.ts @@ -0,0 +1,18 @@ +/* + * Copyright 2024 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. + */ + +export type { DefaultFiltersProps } from './DefaultFilters'; +export { DefaultFilters } from './DefaultFilters'; diff --git a/plugins/catalog-react/src/components/index.ts b/plugins/catalog-react/src/components/index.ts index a805550b1b..e544287007 100644 --- a/plugins/catalog-react/src/components/index.ts +++ b/plugins/catalog-react/src/components/index.ts @@ -15,6 +15,7 @@ */ export * from './CatalogFilterLayout'; +export * from './DefaultFilters'; export * from './EntityKindPicker'; export * from './EntityLifecyclePicker'; export * from './EntityOwnerPicker'; diff --git a/plugins/catalog/api-report.md b/plugins/catalog/api-report.md index d37cbfccc2..40d90abe40 100644 --- a/plugins/catalog/api-report.md +++ b/plugins/catalog/api-report.md @@ -233,6 +233,8 @@ export interface DefaultCatalogPageProps { // (undocumented) emptyContent?: ReactNode; // (undocumented) + filters?: ReactNode; + // (undocumented) initialKind?: string; // (undocumented) initiallySelectedFilter?: UserListFilterKind; diff --git a/plugins/catalog/src/components/CatalogPage/DefaultCatalogPage.tsx b/plugins/catalog/src/components/CatalogPage/DefaultCatalogPage.tsx index 779b347b48..d002552311 100644 --- a/plugins/catalog/src/components/CatalogPage/DefaultCatalogPage.tsx +++ b/plugins/catalog/src/components/CatalogPage/DefaultCatalogPage.tsx @@ -26,16 +26,8 @@ import { import { configApiRef, useApi, useRouteRef } from '@backstage/core-plugin-api'; import { CatalogFilterLayout, - EntityLifecyclePicker, EntityListProvider, - EntityProcessingStatusPicker, - EntityOwnerPicker, - EntityTagPicker, - EntityTypePicker, UserListFilterKind, - UserListPicker, - EntityKindPicker, - EntityNamespacePicker, EntityOwnerPickerProps, } from '@backstage/plugin-catalog-react'; import React, { ReactNode } from 'react'; @@ -47,6 +39,7 @@ import { useTranslationRef } from '@backstage/core-plugin-api/alpha'; import { CatalogTableColumnsFunc } from '../CatalogTable/types'; import { catalogEntityCreatePermission } from '@backstage/plugin-catalog-common/alpha'; import { usePermission } from '@backstage/plugin-permission-react'; +import { DefaultFilters } from '@backstage/plugin-catalog-react'; /** @internal */ export type BaseCatalogPageProps = { @@ -103,6 +96,7 @@ export interface DefaultCatalogPageProps { emptyContent?: ReactNode; ownerPickerMode?: EntityOwnerPickerProps['mode']; pagination?: boolean | { limit?: number }; + filters?: ReactNode; } export function DefaultCatalogPage(props: DefaultCatalogPageProps) { @@ -115,21 +109,19 @@ export function DefaultCatalogPage(props: DefaultCatalogPageProps) { emptyContent, pagination, ownerPickerMode, + filters, } = props; return ( - - - - - - - - - + filters ?? ( + + ) } content={