From bb2ca14a7449458377c9d4fc4b9ae14f7a4c03b8 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Wed, 25 Oct 2023 14:48:17 +0200 Subject: [PATCH] docs/frontend-system: switch order between plugins and extensions Signed-off-by: Patrik Oldsberg --- docs/frontend-system/architecture/01-index.md | 8 ++++---- docs/frontend-system/architecture/02-app.md | 6 +++--- .../architecture/{04-extensions.md => 03-extensions.md} | 0 .../architecture/{03-plugins.md => 04-plugins.md} | 0 4 files changed, 7 insertions(+), 7 deletions(-) rename docs/frontend-system/architecture/{04-extensions.md => 03-extensions.md} (100%) rename docs/frontend-system/architecture/{03-plugins.md => 04-plugins.md} (100%) diff --git a/docs/frontend-system/architecture/01-index.md b/docs/frontend-system/architecture/01-index.md index 972bd39a4d..757a3c338e 100644 --- a/docs/frontend-system/architecture/01-index.md +++ b/docs/frontend-system/architecture/01-index.md @@ -26,14 +26,14 @@ The diagram below provides an overview of the different building blocks, and the This is the app instance itself that you create and use as the root of your Backstage frontend application. It does not have any direct functionality in and of itself, but is simply responsible for wiring things together. -### Plugins - -Plugins provide the actual features inside an app. The size of a plugin can range from a tiny component to an entire new system in which other plugins can be composed and integrated. Plugins can be completely standalone, or build on top of each other to extend existing plugins and augment their features. Plugins can communicate with each other by composing their extensions, or by sharing APIs and routes. - ### Extensions Extensions are the building blocks that build out both the visual and non-visual structure of the application. There are both built-in extensions provided by the app itself, as well as extensions provided by plugins. Each extension is attached to a parent with which it shares data, and can have any number of children of its own. It is up to the app to wire together all extensions into a single tree known as the app extension tree. It is from this structure that the entire app can then be instantiated and rendered. +### Plugins + +Plugins provide the actual features inside an app. The size of a plugin can range from a tiny component to an entire new system in which other plugins can be composed and integrated. Plugins can be completely standalone, or build on top of each other to extend existing plugins and augment their features. Plugins can communicate with each other by composing their extensions, or by sharing Utility APIs and routes. + ### Extension Overrides In addition to the built-in extensions and extensions provided by plugins, it is also possible to install extension overrides. This is a collection of extensions with high priority that can replace existing extensions. They can for example be used to override an individual extension provided by a plugin, or install a completely new extensions, such as a new app theme. diff --git a/docs/frontend-system/architecture/02-app.md b/docs/frontend-system/architecture/02-app.md index 4bbcec225e..6fa8242061 100644 --- a/docs/frontend-system/architecture/02-app.md +++ b/docs/frontend-system/architecture/02-app.md @@ -33,12 +33,12 @@ const rootEl = document.getElementById('root')!; ReactDOM.createRoot(rootEl).render(app); ``` -We call `createApp` to create a new app instance, which is responsible for wiring together all of the features that we provide to the app. It also provides a set of built-in [Extensions](./04-extensions.md) that help build out the foundations of the app, as well as defaults for many other systems such as [Utility API](./06-utility-apis.md) implementations, components, icons, themes, and how to load configuration. No real work is done at the point of creating the app though, it's all deferred to the rendering of the element returned from `app.createRoot()`. +We call `createApp` to create a new app instance, which is responsible for wiring together all of the features that we provide to the app. It also provides a set of built-in [Extensions](./03-extensions.md) that help build out the foundations of the app, as well as defaults for many other systems such as [Utility API](./06-utility-apis.md) implementations, components, icons, themes, and how to load configuration. No real work is done at the point of creating the app though, it's all deferred to the rendering of the element returned from `app.createRoot()`. -It is possible to explicitly install features when creating the app, although typically these will instead be discovered automatically which we'll explore later on. Nevertheless these features are what build out the actual functionality of the app by providing [Extensions](./04-extensions.md). These extensions are wired together by the app into a tree structure known as the app extension tree. Each node in this tree receives data from its child nodes, and pass along data to its parent. The following diagram illustrates the shape of a small app extension tree. +It is possible to explicitly install features when creating the app, although typically these will instead be discovered automatically which we'll explore later on. Nevertheless these features are what build out the actual functionality of the app by providing [Extensions](./03-extensions.md). These extensions are wired together by the app into a tree structure known as the app extension tree. Each node in this tree receives data from its child nodes, and pass along data to its parent. The following diagram illustrates the shape of a small app extension tree. ![frontend system app structure diagram](../../assets/frontend-system/architecture-app.drawio.svg) -Each node in this tree is an extension with a parent node, children. The colored shapes represent extension data inputs and output, where each color is one unique type of data. You can see that there are both extensions that output data that is ignored by the parent, as well as extensions that accept inputs but do not have any children. There are a couple of different tools at your disposal when creating and extension that lets you define different requirements for your inputs and output, which we will cover in greater details in the [Extensions](./04-extensions.md) section. +Each node in this tree is an extension with a parent node, children. The colored shapes represent extension data inputs and output, where each color is one unique type of data. You can see that there are both extensions that output data that is ignored by the parent, as well as extensions that accept inputs but do not have any children. There are a couple of different tools at your disposal when creating and extension that lets you define different requirements for your inputs and output, which we will cover in greater details in the [Extensions](./03-extensions.md) section. A common type of data that is shared between extensions is React elements and components. These can in turn be rendered by each other in their own React components, which ends up forming a parallel tree of React components that is similar in shape to that of the app extension tree. At the top of the app extension tree is a built-in root extension that among other things outputs a React element. This element also ends up being the root of the parallel React tree, and is rendered by the React element returned by `app.createRoot()`. diff --git a/docs/frontend-system/architecture/04-extensions.md b/docs/frontend-system/architecture/03-extensions.md similarity index 100% rename from docs/frontend-system/architecture/04-extensions.md rename to docs/frontend-system/architecture/03-extensions.md diff --git a/docs/frontend-system/architecture/03-plugins.md b/docs/frontend-system/architecture/04-plugins.md similarity index 100% rename from docs/frontend-system/architecture/03-plugins.md rename to docs/frontend-system/architecture/04-plugins.md