docs(search): update official page

Signed-off-by: Camila Belo <camilaibs@gmail.com>
2023-01-22 19:43:31 +01:00
parent 5f16dddc96
commit f5fbd82b1d
1 changed files with 153 additions and 0 deletions
@@ -210,3 +210,156 @@ const highlightOverride = {
 [obj-mode]: https://nodejs.org/dist/latest-v16.x/docs/api/stream.html#stream_object_mode
 [read-stream]: https://nodejs.org/dist/latest-v16.x/docs/api/stream.html#readable-streams
 [async-gen]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of#iterating_over_async_generators
+
+## How to render search results using extensions
+
+Extensions for search results let you customize components used to render search result items, It is possible to provide your own search result item extensions or use the ones provided by plugin packages:
+
+### 1. Providing an extension in your plugin package
+
+Using the example below, you can provide an extension to be used as a default result item:
+
+```tsx
+// plugins/your-plugin/src/plugin.ts
+import { createPlugin } from '@backstage/core-plugin-api';
+import { createSearchResultListItemExtension } from '@backstage/plugin-search-react';
+
+const plugin = createPlugin({ id: 'YOUR_PLUGIN_ID' });
+
+export const YourSearchResultListItemExtension = plugin.provide(
+  createSearchResultListItemExtension({
+    name: 'YourSearchResultListItem',
+    component: () =>
+      import('./components').then(m => m.YourSearchResultListItem),
+  }),
+);
+```
+
+Additionally, you can define a predicate function that receives a result and returns whether your extension should be used to render it or not:
+
+```tsx
+// plugins/your-plugin/src/plugin.ts
+import { createPlugin } from '@backstage/core-plugin-api';
+import { createSearchResultListItemExtension } from '@backstage/plugin-search-react';
+
+const plugin = createPlugin({ id: 'YOUR_PLUGIN_ID' });
+
+export const YourSearchResultListItemExtension = plugin.provide(
+  createSearchResultListItemExtension({
+    name: 'YourSearchResultListItem',
+    component: () =>
+      import('./components').then(m => m.YourSearchResultListItem),
+    // Only results matching your type will be rendered by this extension
+    predicate: result => result.type === 'YOUR_RESULT_TYPE',
+  }),
+);
+```
+
+Remember to export your new extension:
+
+```tsx
+// plugins/your-plugin/src/index.ts
+export { YourSearchResultListItem } from './plugin.ts';
+```
+
+For more details, see the [createSearchResultListItemExtension](https://backstage.io/docs/reference/plugin-search-react.createsearchresultlistitemextension) API reference.
+
+### 2. Using an extension in your Backstage app
+
+Now that you know how a search result item is provided, let's finally see how they can be used, for example, to compose a page in your application:
+
+```tsx
+// packages/app/src/components/searchPage.tsx
+import React from 'react';
+
+import { Grid, Paper } from '@material-ui/core';
+import BuildIcon from '@material-ui/icons/Build';
+
+import {
+  Page,
+  Header,
+  Content,
+  DocsIcon,
+  CatalogIcon,
+} from '@backstage/core-components';
+import { SearchBar, SearchResult } from '@backstage/plugin-search-react';
+
+// Your search result item extension
+import { YourSearchResultListItem } from '@backstage/your-plugin';
+
+// Extensions provided by other plugin developers
+import { ToolSearchResultListItem } from '@backstage/plugin-explore';
+import { TechDocsSearchResultListItem } from '@backstage/plugin-techdocs';
+import { CatalogSearchResultListItem } from '@internal/plugin-catalog-customized';
+
+// This example omits other components, like filter and pagination
+const SearchPage = () => (
+  <Page themeId="home">
+    <Header title="Search" />
+    <Content>
+      <Grid container direction="row">
+        <Grid item xs={12}>
+          <Paper>
+            <SearchBar />
+          </Paper>
+        </Grid>
+        <Grid item xs={12}>
+          <SearchResult>
+            <YourSearchResultListItem />
+            <CatalogSearchResultListItem icon={<CatalogIcon />} />
+            <TechDocsSearchResultListItem icon={<DocsIcon />} />
+            <ToolSearchResultListItem icon={<BuildIcon />} />
+          </SearchResult>
+        </Grid>
+      </Grid>
+    </Content>
+  </Page>
+);
+
+export const searchPage = <SearchPage />;
+```
+
+> **Important**: A default result item extension should be placed as the last child, so it can be used only when no other extensions match the result being rendered. If a non-default extension is specified, the `DefaultResultListItem` component will be used.
+
+As another example, here's a search modal that renders results with extensions:
+
+```tsx
+// packages/app/src/components/searchModal.tsx
+import React from 'react';
+
+import { DialogContent, DialogTitle, Paper } from '@material-ui/core';
+import BuildIcon from '@material-ui/icons/Build';
+
+import { DocsIcon, CatalogIcon } from '@backstage/core-components';
+import { SearchBar, SearchResult } from '@backstage/plugin-search-react';
+
+// Your search result item extension
+import { YourSearchResultListItem } from '@backstage/your-plugin';
+
+// Extensions provided by other plugin developers
+import { ToolSearchResultListItem } from '@backstage/plugin-explore';
+import { TechDocsSearchResultListItem } from '@backstage/plugin-techdocs';
+import { CatalogSearchResultListItem } from '@internal/plugin-catalog-customized';
+
+export const SearchModal = ({ toggleModal }: { toggleModal: () => void }) => (
+  <>
+    <DialogTitle>
+      <Paper>
+        <SearchBar />
+      </Paper>
+    </DialogTitle>
+    <DialogContent>
+      <SearchResult onClick={toggleModal}>
+        <CatalogSearchResultListItem icon={<CatalogIcon />} />
+        <TechDocsSearchResultListItem icon={<DocsIcon />} />
+        <ToolSearchResultListItem icon={<BuildIcon />} />
+        {/* As a "default" extension, it does not define a predicate function, 
+        so it must be the last child to render results that do not match the above extensions */}
+        <YourSearchResultListItem />
+      </SearchResult>
+    </DialogContent>
+  </>
+);
+```
+
+There are other more specific search results layout components that also accept result item extensions, check their documentation: [SearchResultList](https://backstage.io/storybook/?path=/story/plugins-search-searchresultlist--with-result-item-extensions) and [SearchResultGroup](https://backstage.io/storybook/?path=/story/plugins-search-searchresultgroup--with-result-item-extensions).