RHIDP-4567-1 - Provide the ability to load a custom Backstage theme from a dynamic plugin (redhat-developer#801)

* RHIDP-4567-1 - Provide the ability to load a custom Backstage theme from a dynamic plugin

* RHIDP-4567-1 - Provide the ability to load a custom Backstage theme from a dynamic plugin

Author: Gerry-Forde

assemblies/assembly-customizing-the-appearance.adoc

@@ -42,6 +42,7 @@ include::modules/customizing-the-appearance/ref-customize-rhdh-default-rhdh.adoc
 
 include::modules/customizing-the-appearance/ref-customize-rhdh-default-backstage.adoc[leveloffset=+1]
 
+include::modules/customizing-the-appearance/proc-loading-custom-theme-using-dynamic-plugin.adoc[leveloffset=+1]
 
 include::modules/customizing-the-appearance/ref-customize-rhdh-custom-components.adoc[leveloffset=+1]
 

modules/customizing-the-appearance/proc-loading-custom-theme-using-dynamic-plugin.adoc

@@ -0,0 +1,44 @@
+// Module included in the following assemblies:
+// assembly-customize-rhdh-theme.adoc
+
+[id="proc-loading-custom-theme-using-dynamic-plugin-_{context}"]
+= Loading a custom {product-short} theme by using a dynamic plugin
+
+You can load a custom {product-short} theme from a dynamic plugin.
+
+.Procedure
+
+. Export a theme provider function in your dynamic plugin, for example:
++
+.Sample `myTheme.ts` fragment
+[source,javascript]
+----
+import { lightTheme } from './lightTheme'; // some custom theme
+import { UnifiedThemeProvider } from '@backstage/theme';
+export const lightThemeProvider = ({ children }: { children: ReactNode }) => (
+  <UnifiedThemeProvider theme={lightTheme} children={children} />
+);
+----
++
+For more information about creating a custom theme, see link:https://backstage.io/docs/getting-started/app-custom-theme/#creating-a-custom-theme[Backstage documentation - Creating a Custom Theme].
+
+. Configure {product-short} to load the theme in the UI by using the `themes` configuration field:
++
+.`app-config-rhdh.yaml` fragment
+[source,yaml]
+----
+dynamicPlugins:
+  frontend:
+    example.my-custom-theme-plugin:
+      themes:
+        - id: light # <1>
+          title: Light
+          variant: light
+          icon: someIconReference
+          importName: lightThemeProvider
+----
+<1> Set your theme ID by specifying the desired value. Optionally, override the default {product-short} themes by using the following ID values: `light` to replace the default light theme, or `dark` to replace the default dark theme.
+
+.Verification
+
+* The theme is available in the {product-short} *Settings* page.