From 19b4358717255e7d029a839baf44d61b24d712a8 Mon Sep 17 00:00:00 2001 From: Camila Belo Date: Mon, 19 Feb 2024 09:21:50 +0100 Subject: [PATCH] refactor(org): remove disable sub-section and use table for configs Signed-off-by: Camila Belo --- plugins/org/README-alpha.md | 192 +++++++++--------------------------- 1 file changed, 47 insertions(+), 145 deletions(-) diff --git a/plugins/org/README-alpha.md b/plugins/org/README-alpha.md index fb9fe9d181..5653de5dc5 100644 --- a/plugins/org/README-alpha.md +++ b/plugins/org/README-alpha.md @@ -42,6 +42,9 @@ And below is an example of how a user page looks with the user profile and owner 2. 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-config.yaml app: @@ -85,16 +88,7 @@ Route binding is also possible through code. For more information, see [this](ht ## Extensions -### Entity Cards - -The `org` plugin provide some entity cards you can enable to customize the Software 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. - -See a complete cards list below: - -#### Entity Group Profile Card +### Entity Group Profile Card This [entity card](https://github.com/backstage/backstage/blob/master/plugins/catalog-react/api-report-alpha.md) extension allows you to view, edit, or update groups metadata, such as team avatar, name, email, parent, and child groups. @@ -102,48 +96,25 @@ This [entity card](https://github.com/backstage/backstage/blob/master/plugins/ca | ------------- | --------- | --------------- | ------------------------------- | | `entity-card` | `org` | `group-profile` | `entity-card:org/group-profile` | -##### Disable +#### Config -This card is disabled by default when you install the `org` plugin, but to ensure the card will always be disabled or enabled regardless of the extension's default definition, add the following configuration: +Currently, this entity card extension has only one configuration: + +| Config key | Default value | Description | +| ---------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `filter` | `kind:group` | An [entity filter](https://github.com/backstage/backstage/pull/21480) 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-config.yaml -# example disabling the org group profile entity card extension app: extensions: - # this is the extension id and it follows the naming pattern bellow: - # /: - # use false as value for disabling the extension and true for enabling - - entity-card:org/group-profile: false - # or - # - entity-card:org/group-profile: - # - config: - # # set 'true' for enabling it again - # disabled: true -``` - -##### Config - -There is only one configuration available for this entity card extension, which is setting an entity filter that determines when the card should be displayed on the entity page. - -Here is an example showing the `group-profile` overview card only for entities of kind group: - -```yaml -# app-config.yaml -# example setting the extension to only show up for entities with kind "group" -app: - extensions: - # this is the extension id and it follows the naming pattern bellow: - # /: - entity-card:org/group-profile: config: - # The default value is "kind:group" - # For more information about entity cards filters, check out this pull request - # https://github.com/backstage/backstage/pull/21480 - filter: 'kind:group' + : '' ``` -##### Override +#### Override Use extension overrides for completely re-implementing the group-profile entity card extension: @@ -169,7 +140,7 @@ export default createExtensionOverrides({ For more information about where to place extension overrides, see the official [documentation](https://backstage.io/docs/frontend-system/architecture/extension-overrides). -#### Entity Members List Card +### Entity Members List Card An [entity card](https://github.com/backstage/backstage/blob/master/plugins/catalog-react/api-report-alpha.md) 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. @@ -177,48 +148,25 @@ An [entity card](https://github.com/backstage/backstage/blob/master/plugins/cata | ------------- | --------- | -------------- | ------------------------------ | | `entity-card` | `org` | `members-list` | `entity-card:org/members-list` | -##### Disable +#### Config -This card is disabled by default when you install the `org` plugin, but to ensure the card will always be disabled or enabled regardless of the extension's default definition, add the following configuration: +Currently, this entity card extension has only one configuration: + +| Config key | Default value | Description | +| ---------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `filter` | `kind:group` | An [entity filter](https://github.com/backstage/backstage/pull/21480) 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-config.yaml -# example disabling the org members list entity card extension app: extensions: - # this is the extension id and it follows the naming pattern bellow: - # /: - # use false as value for disabling the extension and true for enabling - - entity-card:org/members-list: false - # or - # - entity-card:org/members-list: - # - config: - # # set 'true' for enabling it again - # disabled: true -``` - -##### Config - -There is only one configuration available for this entity card extension, which is setting an entity filter that determines when the card should be displayed on the entity page. - -Here is an example showing the `members-list` overview card only for entities of kind group: - -```yaml -# app-config.yaml -# example setting the extension to only show up for entities with kind "group" -app: - extensions: - # this is the extension id and it follows the naming pattern bellow: - # /: - entity-card:org/members-list: config: - # The default value is "kind:group" - # For more information about entity cards filters, check out this pull request - # https://github.com/backstage/backstage/pull/21480 - filter: 'kind:group' + : '' ``` -##### Override +#### Override Use extension overrides for completely re-implementing the members-list entity card extension: @@ -244,7 +192,7 @@ export default createExtensionOverrides({ For more information about where to place extension overrides, see the official [documentation](https://backstage.io/docs/frontend-system/architecture/extension-overrides). -#### Entity Ownership Card +### Entity Ownership Card An [entity card](https://github.com/backstage/backstage/blob/master/plugins/catalog-react/api-report-alpha.md) 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. @@ -252,48 +200,25 @@ An [entity card](https://github.com/backstage/backstage/blob/master/plugins/cata | ------------- | --------- | ----------- | --------------------------- | | `entity-card` | `org` | `ownership` | `entity-card:org/ownership` | -##### Disable +#### Config -This card is disabled by default when you install the `org` plugin, but to ensure the card will always be disabled or enabled regardless of the extension's default definition, add the following configuration: +Currently, this entity card extension has only one configuration: + +| Config key | Default value | Description | +| ---------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `filter` | `kind:group,user` | An [entity filter](https://github.com/backstage/backstage/pull/21480) 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-config.yaml -# example disabling the org members list entity card extension app: extensions: - # this is the extension id and it follows the naming pattern bellow: - # /: - # use false as value for disabling the extension and true for enabling - - entity-card:org/ownership: false - # or - # - entity-card:org/ownership: - # - config: - # # set 'true' for enabling it again - # disabled: true -``` - -##### Config - -There is only one configuration available for this entity card extension, which is setting an entity filter that determines when the card should be displayed on the entity page. - -Here is an example showing the `ownership` overview card only for entities of kind group or user: - -```yaml -# app-config.yaml -# example setting the extension to only show up for entities with kind "group" or "user" -app: - extensions: - # this is the extension id and it follows the naming pattern bellow: - # /: - entity-card:org/ownership: config: - # The default value is "kind:group,user" - # For more information about entity cards filters, check out this pull request - # https://github.com/backstage/backstage/pull/21480 - filter: 'kind:group,user' + : '' ``` -##### Override +#### Override Use extension overrides for completely re-implementing the ownership entity card extension: @@ -319,7 +244,7 @@ export default createExtensionOverrides({ For more information about where to place extension overrides, see the official [documentation](https://backstage.io/docs/frontend-system/architecture/extension-overrides). -#### Entity User Profile Card +### Entity User Profile Card This [entity card](https://github.com/backstage/backstage/blob/master/plugins/catalog-react/api-report-alpha.md) extension allows you to view user metadata including avatar, name, email, and team. 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. @@ -327,48 +252,25 @@ This [entity card](https://github.com/backstage/backstage/blob/master/plugins/ca | ------------- | --------- | -------------- | ------------------------------ | | `entity-card` | `org` | `user-profile` | `entity-card:org/user-profile` | -##### Disable +#### Config -This card is disabled by default when you install the `org` plugin, but to ensure the card will always be disabled or enabled regardless of the extension's default definition, add the following configuration: +Currently, this entity card extension has only one configuration: + +| Config key | Default value | Description | +| ---------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| `filter` | `kind:user` | An [entity filter](https://github.com/backstage/backstage/pull/21480) 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-config.yaml -# example disabling the org user profile entity card extension app: extensions: - # this is the extension id and it follows the naming pattern bellow: - # /: - # use false as value for disabling the extension and true for enabling - - entity-card:org/user-profile: false - # or - # - entity-card:org/user-profile: - # - config: - # # set 'true' for enabling it again - # disabled: true -``` - -##### Config - -There is only one configuration available for this entity card extension, which is setting an entity filter that determines when the card should be displayed on the entity page. - -Here is an example showing the `user-profile` overview card only for entities of kind group or user: - -```yaml -# app-config.yaml -# example setting the extension to only show up for entities with kind "user" -app: - extensions: - # this is the extension id and it follows the naming pattern bellow: - # /: - entity-card:org/user-profile: config: - # The default value is "kind:user" - # For more information about entity cards filters, check out this pull request - # https://github.com/backstage/backstage/pull/21480 - filter: 'kind:user' + : '' ``` -##### Override +#### Override Use extension overrides for completely re-implementing the user-profile entity card extension: