Add BRANDING.md documentation and support simpler brands

Signed-off-by: Scott J Dickerson <[email protected]>
konveyor · Mar 1, 2024 · 347728c · 347728c
1 parent d8ad7af
commit 347728c
Show file tree

Hide file tree

Showing 5 changed files with 181 additions and 21 deletions.
diff --git a/BRANDING.md b/BRANDING.md
@@ -0,0 +1,151 @@
+# Branding
+
+The UI supports static branding at build time. Dynamically switching brands is not
+possible with the current implementation.
+
+## Summary
+
+Each of the project modules need to do some branding enablement.
+
+- `@konveyor-ui/common` pulls in the branding assets and packages the configuration,
+  strings and assets within the common package. The other modules pull branding
+  from the common module.
+
+- `@konveyor-ui/client` uses branding from the common package:
+
+  - The location of `favicon.ico`, `manifest.json` and any other branding
+    assets that may be referenced in the `brandingStrings` are sourced from the
+    common package.
+
+  - The `brandingStrings` are used by the dev-server runtime, to fill out the
+    `index.html` template.
+
+  - The about modal and application masthead components use the branding strings
+    provided by the common module to display brand appropriate logos, titles and
+    about information. Since the common module provides all the information, it
+    is packaged directly into the app at build time.
+
+- `@konveyor-ui/server` uses the `brandingStrings` from the common package to fill
+  out the `index.html` template.
+
+## Providing alternate branding
+
+To provide an alternate branding to the build, specify the path to the branding assets
+with the `BRANDING` environment variable. Relative paths in `BRANDING` are computed
+from the project source root.
+
+Each brand requires the presence of at least the following files:
+
+- `strings.json`
+- `favicon.ico`
+- `manifest.json`
+
+With a file path of `/alt/custom-branding`, a build that uses an alternate branding
+is run as:
+
+```sh
+> BRANDING=/alt/custom-branding npm run build
+```
+
+The dev server can also be run this way. Since file watching of the branding assets
+is not implemented in the common module's build watch mode, it may be necessary to
+manually build the common module before running the dev server. When working on a
+brand, it is useful to run the dev server like this:
+
+```sh
+> export BRANDING=/alt/custom-branding
+> npm run build -w common
+> npm run start:dev
+> unset BRANDING # when you don't want to use the custom branding path anymore
+```
+
+### File details
+
+#### strings.json
+
+The expected shape of `strings.json` is defined in [branding.ts](./common/src/branding.ts).
+
+The default version of the file is [branding/strings.json](./branding/strings.json).
+
+A minimal viable example of the file is:
+
+```json
+{
+  "application": {
+    "title": "Konveyor"
+  },
+  "about": {
+    "displayName": "Konveyor"
+  },
+  "masthead": {}
+}
+```
+
+At build time, the json file is processed as an [ejs](https://ejs.co/) template. The
+variable `brandingRoot` is provided as the relative root of the branding
+assets within the build of the common module. Consider the location of `strings.json`
+in your branding directory as the base `brandingRoot` when creating a new brand.
+
+For example, to properly reference a logo within this branding structure:
+
+```
+  special-brand/
+    images/
+      masthead-logo.svg
+      about-logo.svg
+    strings.json
+```
+
+Use a url string like this:
+
+```json
+{
+  "about": {
+    "imageSrc": "<%= brandingRoot %>/images/about-logo.svg"
+  }
+}
+```
+
+and in the output of `BRANDING=special-brand npm run build -w common`, the `imageSrc`
+will be `branding/images/about-logo.svg` with all of the files in `special-branding/*`
+copied to and available to the client and server modules from
+`@konveyor-ui/common/branding/*`.
+
+#### favicon.ico
+
+A standard favorite icon file `favicon.ico` is required to be in the same directory
+as `strings.json`
+
+#### manifest.json
+
+A standard [web app manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest)
+file `manifest.json` is required to be in the same directory as `strings.json`.
+
+## Technical details
+
+All branding strings and assets are pulled in to the common module. The client and
+server modules access the branding from the common module build.
+
+The `common` module relies on rollup packaging to embed all of the brand for easy
+use. The use of branding strings in `client` and `server` modules is straight forward.
+Pulling in `strings.json` and providing the base path to the brand assets is a
+more complicated.
+
+The `common` module provides the `brandingAssetPath()` function to let the build time
+code find the root path to all brand assets. Webpack configuration files use this
+function to source the favicon.ico, manifest.json and other brand assets to be copied
+to the application bundle.
+
+The `brandingStrings` is typed and sourced from a json file. To pass typescript builds,
+a stub json file needs to be available at transpile time. By using a typescript paths
+of `@branding/strings.json`, the stub json is found at transpile time. The generated
+javascript will still import the path alias. The
+[virtual rollup plugin](https://github.com/rollup/plugins/tree/master/packages/virtual)
+further transform the javascript output by replacing the `@branding/strings.json` import
+with a dynamically built module containing the contents of the brand's `strings.json`.
+The brand json becomes a virtual module embedded in the common module.
+
+A build for a custom brand will fail (1) if the expected files cannot be read, or (2)
+if `strings.json` is not a valid JSON file. **Note:** The context of `stings.json` is
+not currently validated. If something is missing or a url is malformed, it will only
+be visible as a runtime error.
diff --git a/client/public/index.html.ejs b/client/public/index.html.ejs
@@ -2,8 +2,8 @@
 <html lang="en-US">
   <head>
     <title><%= branding.application.title %></title>
-    <meta name="description" content="<%= branding.application.description %>" />
-    <meta id="appName" name="application-name" content="<%= branding.application.name %>" />
+    <meta name="description" content="<%= branding.application.description ?? branding.application.title %>" />
+    <meta id="appName" name="application-name" content="<%= branding.application.name ?? branding.application.title %>" />
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="theme-color" content="#000000" />

diff --git a/client/src/app/layout/AppAboutModal/AppAboutModal.tsx b/client/src/app/layout/AppAboutModal/AppAboutModal.tsx
@@ -17,6 +17,9 @@ export interface AppAboutModalProps {
   onClose: () => void;
 }
 
+const TRANSPARENT_1x1_GIF =
+  "data:image/gif;base64,R0lGODlhAQABAIAAAP///wAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw== ";
+
 export const AppAboutModal: React.FC<AppAboutModalProps> = ({
   isOpen,
   onClose,
@@ -29,18 +32,21 @@ export const AppAboutModal: React.FC<AppAboutModalProps> = ({
       isOpen={isOpen}
       onClose={onClose}
       trademark="COPYRIGHT © 2022."
-      brandImageSrc={about.imageSrc ?? undefined}
+      brandImageSrc={about.imageSrc ?? TRANSPARENT_1x1_GIF}
       brandImageAlt="Logo"
       productName={about.displayName}
     >
       <TextContent>
         <Text component={TextVariants.h4}>{t("about.about")}</Text>
+
         <Text component={TextVariants.p}>
           {t("about.introduction", { brandType: about.displayName })}
         </Text>
+
         <Text component={TextVariants.p}>
           {t("about.description", { brandType: about.displayName })}
         </Text>
+
         <Text component={TextVariants.p}>
           <Trans i18nKey={"about.bottom1"}>
             {{ brandType: about.displayName }} is a project within the
@@ -54,19 +60,23 @@ export const AppAboutModal: React.FC<AppAboutModalProps> = ({
             .
           </Trans>
         </Text>
-        <Text component={TextVariants.p}>
-          <Trans i18nKey={"about.bottom2"}>
-            For more information, refer to
-            <Text
-              component={TextVariants.a}
-              href={about.documentationUrl}
-              target="_blank"
-            >
-              {{ brandType: about.displayName }} documentation
-            </Text>
-            .
-          </Trans>
-        </Text>
+
+        {about.documentationUrl ? (
+          <Text component={TextVariants.p}>
+            <Trans i18nKey={"about.bottom2"}>
+              For more information, refer to
+              <Text
+                component={TextVariants.a}
+                href={about.documentationUrl}
+                target="_blank"
+              >
+                {{ brandType: about.displayName }} documentation
+              </Text>
+              .
+            </Trans>
+          </Text>
+        ) : null}
+
         <Text component={TextVariants.p}>
           <Trans i18nKey="about.iconLibrary">
             The Icon Library used in this project is a derivative of the{" "}

diff --git a/client/src/app/logo.svg b/client/src/app/logo.svg
diff --git a/common/src/branding.ts b/common/src/branding.ts
@@ -13,14 +13,14 @@ export interface MastheadTitle {
 export interface BrandingStrings {
   application: {
     title: string;
-    name: string;
-    description: string;
+    name?: string;
+    description?: string;
   };
 
   about: {
     displayName: string;
-    imageSrc: string;
-    documentationUrl: string;
+    imageSrc?: string;
+    documentationUrl?: string;
   };
 
   masthead: {