From d04264404ec6a4f4bbb3128508c16b7a079fe797 Mon Sep 17 00:00:00 2001 From: Andreas Berger Date: Thu, 11 Sep 2025 16:07:10 +0200 Subject: [PATCH] update doc Signed-off-by: Andreas Berger --- .../software-catalog/catalog-customization.md | 60 +++++++++++++++++++ .../building-plugins/01-index.md | 9 --- .../03-common-extension-blueprints.md | 4 +- 3 files changed, 62 insertions(+), 11 deletions(-) diff --git a/docs/features/software-catalog/catalog-customization.md b/docs/features/software-catalog/catalog-customization.md index a828e6591a..559abdc3f4 100644 --- a/docs/features/software-catalog/catalog-customization.md +++ b/docs/features/software-catalog/catalog-customization.md @@ -696,3 +696,63 @@ filter: targetRef: $in: [group:default/admins, group:default/viewers] ``` + +### Configure groups, titles, and icons + +You can define and customize the tab groups that appear on the entity page, as well as enable icons for both groups and individual tabs. + +```yaml +app: + extensions: + # Entity page (new frontend system) + - page:catalog/entity: + config: + # Show icons next to group and tab titles + showIcons: true + + # Optionally override default groups and their icons + groups: + - overview: + title: Overview + icon: dashboard + - quality: + title: Quality + icon: verified + - documentation: + title: Docs + icon: description +``` + +Notes: + +- Icons for groups and tabs are resolved via the app's IconsApi. When using a string icon id (for example `"dashboard"`), ensure that the corresponding icon bundles are enabled/installed in your app (see the Icons blueprint in the frontend system documentation). +- Group icons are only rendered if `showIcons` is set to `true`. + +### Overriding or disabling a tab's group (per extension) + +Each entity content extension (tabs on the entity page) can declare a default `group` in code. You can override or disable this per installation in `app-config.yaml` using the extension's config: + +```yaml +app: + extensions: + # ... + # Example entity content extension instance id + - entity-content:example/my-content: + config: + # Move this tab to a custom group you defined above + group: custom + # Show an icon for this entity content page but only if + icon: my-icon + + # Disassociate from any group and show as a standalone tab + - entity-content:example/another-content: + config: + group: false +``` + +### Tab icons for entity content + +Entity content extensions can also declare an `icon` parameter. When provided as a string, the icon id is looked up via the IconsApi. For the icon to render: + +- The entity page must have `showIcons: true` (see configuration above). +- The icon id must be available in the app's enabled icon bundles. diff --git a/docs/frontend-system/building-plugins/01-index.md b/docs/frontend-system/building-plugins/01-index.md index 735e37c89b..d9acf76e15 100644 --- a/docs/frontend-system/building-plugins/01-index.md +++ b/docs/frontend-system/building-plugins/01-index.md @@ -198,15 +198,6 @@ const exampleEntityContent = EntityContentBlueprint.make({ params: { path: 'example', title: 'Example', - // Optional: associate this content with a group on the entity page tabs - // Use a known default group id like "overview", "quality", "documentation", - // or provide a custom string. You can also override or disable this via app-config (see note below). - // group: 'overview', - // Optional: set a tab icon. When using a string, the icon is resolved via the IconsApi. - // Ensure your app has icon bundles enabled/installed so the icon id is available. - // Note: icons are shown in the entity page tab groups only if `showIcons` is enabled in the - // catalog entity page config (page:catalog/entity) via app-config. - // icon: 'dashboard', loader: () => import('./components/ExampleEntityContent').then(m => ( diff --git a/docs/frontend-system/building-plugins/03-common-extension-blueprints.md b/docs/frontend-system/building-plugins/03-common-extension-blueprints.md index 3b8ad29da0..bb6f91a5f5 100644 --- a/docs/frontend-system/building-plugins/03-common-extension-blueprints.md +++ b/docs/frontend-system/building-plugins/03-common-extension-blueprints.md @@ -73,10 +73,10 @@ Avoid using `convertLegacyEntityCardExtension` from `@backstage/core-compat-api` Creates entity content to be displayed on the entity pages of the catalog plugin. Exported as `EntityContentBlueprint`. -Supports optional params such as `group` and `icon` in addition to `path`, `title`, `loader`, `filter`, and `routeRef`: +Supports optional params such as `group` and `icon`to: - group: string | false — associates the content with a tab group on the entity page (for example "overview", "quality", "deployment", or any custom id). You can override or disable this per-installation via app-config using `app.extensions[...].config.group`, where `false` removes the grouping. -- icon: string | ReactElement — sets the tab icon. Note: when providing a string, the icon is looked up via the app's IconsApi; make sure icon bundles are enabled/installed in your app (see the Icons blueprint reference above) so that the icon id you use is available. +- icon: string — sets the tab icon. Note: when providing a string, the icon is looked up via the app's IconsApi; make sure icon bundles are enabled/installed in your app (see the Icons blueprint reference above) so that the icon id you use is available. To render icons in the entity page tabs, the page must also have icons enabled via app configuration. Set `showIcons: true` on the catalog entity page config (created via `page:catalog/entity`). Example: