update doc

Signed-off-by: Andreas Berger <andreas@berger-ecommerce.com>
2025-09-11 16:07:10 +02:00
parent f053baa2f7
commit d04264404e
3 changed files with 62 additions and 11 deletions
@@ -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.
@@ -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 => (
        <m.ExampleEntityContent />
@@ -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: