diff --git a/docs/frontend-system/architecture/03-extensions.md b/docs/frontend-system/architecture/03-extensions.md index 46bfa3d86f..061c695abb 100644 --- a/docs/frontend-system/architecture/03-extensions.md +++ b/docs/frontend-system/architecture/03-extensions.md @@ -81,8 +81,6 @@ const extension = createExtension({ Note that while the `createExtension` is public API and used in many places, it is not typically what you use when building plugins and features. Instead there are many extension creator functions exported by both the core APIs and plugins that make it easier to create extensions for more specific usages. -... TODO ... - ## Extension Data Communication between extensions happens in one direction, from one child extension through the attachment point to its parent. The child extension outputs data which is then passed as inputs to the parent extension. This data is called Extension Data, where the shape of each individual piece of data is described by an Extension Data Reference. These references are created separately from the extensions themselves, and can be shared across multiple different kinds of extensions. Each reference consists of an ID and a TypeScript type that the data needs to conform to, and represents one type of data that can be shared between extensions. @@ -137,7 +135,7 @@ const extension = createExtension({ We provide default `coreExtensionData`, which provides commonly used `ExtensionDataRef`s - e.g. for `React.JSX.Element` and `RouteRef`. They can be used when creating your own extension. For example, the React Element extension data that we defined above is already provided as `coreExtensionData.reactElement`. - +For a full list and explanations of all types of core extension data, see the [core extension data reference](../building-plugins/04-built-in-data-refs.md). ### Optional Extension Data diff --git a/docs/frontend-system/building-plugins/04-built-in-data-refs.md b/docs/frontend-system/building-plugins/04-built-in-data-refs.md new file mode 100644 index 0000000000..dacbbf30f1 --- /dev/null +++ b/docs/frontend-system/building-plugins/04-built-in-data-refs.md @@ -0,0 +1,61 @@ +--- +id: built-in-data-refs +title: Built-in data refs +sidebar_label: Built-in data refs +# prettier-ignore +description: Configuring or overriding built-in extension data references +--- + +> **NOTE: The new frontend system is in alpha and is only supported by a small number of plugins.** + +To have a better understanding of extension data references please read [the corresponding architecture section](../architecture/03-extensions.md#extension-data) first. + +## Built-in extension data references + +Data references help to define the inputs and outputs of an extension. A data ref is uniquely identified through its `id`. Through the data ref, strong typing is enforced for the input/output of the extension. + +### `reactElement` + +| id | type | +| :-----------------: | :-----------: | +| `core.reactElement` | `JSX.Element` | + +The `reactElement` data reference can be used for defining the extension input/output of React elements. Example usage could be something like this: + +```tsx +import { + coreExtensionData, + createExtensionInput, + createPageExtension, +} from '@backstage/frontend-plugin-api'; + +const homePage = createPageExtension({ + defaultPath: '/home', + routeRef: rootRouteRef, + inputs: { + props: createExtensionInput({ + children: coreExtensionData.reactElement.optional(), + }), + }, +}); +``` + +### `routePath` + +| id | type | +| :-----------------: | :------: | +| `core.routing.path` | `string` | + +The `routePath` data reference can be used for defining the extension input/output of string paths. + +### `routeRef` + +| id | type | +| :----------------: | :--------: | +| `core.routing.ref` | `RouteRef` | + +The `routeRef` data reference can be used for defining the extension input/output of route references. + +### Other data references + +There are other data refs in the frontend system you might stumble upon while building your plugin. Most of them were created for use cases inside the core of the system, but they can be used also in your plugin. diff --git a/microsite/sidebars.json b/microsite/sidebars.json index d52c00b3da..146d8db059 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -413,7 +413,8 @@ "items": [ "frontend-system/building-plugins/index", "frontend-system/building-plugins/testing", - "frontend-system/building-plugins/extension-types" + "frontend-system/building-plugins/extension-types", + "frontend-system/building-plugins/built-in-data-refs" ] }, {