From 8623fdeca87e79e4b1769db84c4482032dbbda9c Mon Sep 17 00:00:00 2001 From: Camila Belo Date: Wed, 4 Oct 2023 15:04:19 +0200 Subject: [PATCH] refactor(search): apply review suggestions - second round Signed-off-by: Camila Belo --- .../search/search-extensions-example.drawio.svg | 4 ++++ docs/assets/search/search-extensions-example.svg | 4 ---- docs/features/search/declarative-integration.md | 13 +++---------- 3 files changed, 7 insertions(+), 14 deletions(-) create mode 100644 docs/assets/search/search-extensions-example.drawio.svg delete mode 100644 docs/assets/search/search-extensions-example.svg diff --git a/docs/assets/search/search-extensions-example.drawio.svg b/docs/assets/search/search-extensions-example.drawio.svg new file mode 100644 index 0000000000..d0b0b4a481 --- /dev/null +++ b/docs/assets/search/search-extensions-example.drawio.svg @@ -0,0 +1,4 @@ + + + +
Core Routes
EXTENSION
Core Routes...

Routes

Routes
Attachment
Point
Attachment...
Route Artifact
Route Artifact
PATH
+
ELEMENT
PATH...
Input
Input
COMPONENT
COMPONENT
Item Artifact
Item Artifact

Search Page
EXTENSION

Search Page...

Items

Items
Attachment
Point
Attachment...
Output
Output
Input
Input

Search Result Item
EXTENSION

Search Result Item...


Output
Output
id: plugin.search.page
id: plugin.search.page
at: plugin.search.page/items
at: plugin.search.page/items
id: core.router
id: core.router
id: plugin.search.result.item
id: plugin.search.result.i...
at: core.router/routes
at: core.router/routes
Target Extension
Identification
Target Extension...
Target Extension
Input Attachment Point
Target Extension...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/assets/search/search-extensions-example.svg b/docs/assets/search/search-extensions-example.svg deleted file mode 100644 index 19b208009f..0000000000 --- a/docs/assets/search/search-extensions-example.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - -
Core Routes
EXTENSION
Core Routes...

Routes

Routes
Attachment
Point
Attachment...
Route Artifact
Route Artifact
PATH
+
ELEMENT
PATH...
Input
Input
COMPONENT
COMPONENT
Item Artifact
Item Artifact

Search Page
EXTENSION

Search Page...

Items

Items
Attachment
Point
Attachment...
Output
Output
Input
Input

Search Result Item
EXTENSION

Search Result Item...


Output
Output
id: plugin.search.page
id: plugin.search.page
at: plugin.search.page/items
at: plugin.search.page/items
id: core.router
id: core.router
id: plugin.search.result.item
id: plugin.search.result.i...
at: core.router/routes
at: core.router/routes
Target Extension
Identification
Target Extension...
Target Extension
Input Attachment Point
Target Extension...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/features/search/declarative-integration.md b/docs/features/search/declarative-integration.md index 71e23e47a2..f0083e4d4b 100644 --- a/docs/features/search/declarative-integration.md +++ b/docs/features/search/declarative-integration.md @@ -13,7 +13,7 @@ In the new frontend system, everything that extends Backstage's core features is Extensions produces output artifacts and these artifacts are inputs consumed by other extensions: -![search extensions example](../../assets/search/search-extensions-example.svg) +![search extensions example](../../assets/search/search-extensions-example.drawio.svg) In the image above, a `SearchResultItem` extension outputs a component and this component is injected as input to the `SearchPage` "items" attachment point. The `SearchPage` in turn uses the search result items to compose a search page element and outputs a route path and the page element so they are used as inputs attached to the `CoreRoutes` extension. Finally, the `CoreRoutes` renders the page element when the location matches the search page path. @@ -50,8 +50,6 @@ _Example disabling the search page extension_ ```yaml # app-config.yaml app: - experimental: - packages: 'all' # enable packages auto discovery extensions: - plugin.search.page: false # ✨ ``` @@ -61,8 +59,6 @@ _Example setting the search sidebar item label_ ```yaml # app-config.yaml app: - experimental: - packages: 'all' # enable packages auto discovery extensions: - plugin.search.nav.index: # ✨ config: @@ -109,8 +105,6 @@ When a Backstage adopter doesn't want to use the custom `TechDocs` search result ```yaml # app-config.yaml app: - experimental: - packages: 'all' extensions: - plugin.search.result.item.techdocs: false # ✨ ``` @@ -120,8 +114,6 @@ Because a configuration schema was provided to the extension factory, Backstage ```yaml # app-config.yaml app: - experimental: - packages: 'all' # enable packages auto discovery extensions: - plugin.search.result.item.techdocs: config: # ✨ @@ -129,6 +121,7 @@ app: lineClamp: 3 ``` +[comment]: <> (TODO: Extract this explanation to a more central place in the future) The `createSearchResultItemExtension` function returns a Backstage's extension representation as follows: ```ts @@ -222,7 +215,7 @@ export default createPlugin({ }); ``` -### Future enhancement opportunities +### Future Enhancement Opportunities Backstage maintainers are currently working on the extension replacement feature, and with this release, adopters will also be able to replace extensions provided by plugins, so stay tuned for future updates to this documentation.