Draft: refactor: make app branding customizable

.gitignore

@@ -28,3 +28,9 @@ content/*
 !content/content.config.sample.json
 !content/service-status.sample.json
 !content/README.md
+
+# App branding
+src/img/branding/custom/*
+!src/img/branding/custom/README.md
+src/css/branding/custom/*
+!src/css/branding/custom/README.md

README.md

@@ -238,6 +238,18 @@ After selecting it, you get a web inspector window that you can use to troublesh
 
 Using Chrome, go to `chrome://inspect/#devices`.
 
+## Branding
+
+<img alt="Opal Logo Icon" src="/src/img/Opal_Logo_Transparent_Inverse_Icon.png" width="50px"/>
+
+This application comes preconfigured with Opal-branded assets such as the Opal name, logo, etc.
+
+```text
+TBA: Describe the conditions under which Opal branding can be used in a clinical deployment, versus those that would require custom branding.
+```
+
+To rebrand the application with your organization's own name, logos and assets, refer to the [Branding Setup Guide](/docs/setup/branding.md).
+
 ## Testing
 
 ### Testing with a rooted device (Android)

REUSE.toml

@@ -26,12 +26,12 @@ path = [
     "res/**",
     "static/landingpage/Opal_Name_Logo_Transparent.png",
     "static/landingpage/opal-tiny.ico",
+    "src/img/branding/opal/Opal_Name_Logo_Transparent.png",
     "src/img/apple-touch-icon.png",
     "src/img/Opal_Logo_Black.png",
     "src/img/Opal_Logo_Transparent_Inverse_Icon.png",
     "src/img/Opal_Logo_Transparent_Inverse.png",
     "src/img/Opal_Name_Logo_Green_Transparent.png",
-    "src/img/Opal_Name_Logo_Transparent.png",
     "src/img/Opal_Name_Logo.png",
     "src/img/opal_notification.png",
     "src/img/OpalHealth_App_Apple_Icon_2.png",
@@ -70,7 +70,7 @@ SPDX-License-Identifier = "LicenseRef-FleurDeLysDuQuebec"
 
 [[annotations]]
 path = [
-    "src/img/opal-init-photo.jpg",
+    "src/img/branding/opal/init-background.jpg",
 ]
 precedence = "override"
 # See:

docs/setup/branding.md

@@ -0,0 +1,67 @@
+<!--
+SPDX-FileCopyrightText: Copyright (C) 2025 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <john.kildea@mcgill.ca>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Branding Setup Guide
+
+This project has been configured by default with assets that reflect Opal's visual branding and identity.
+However, these assets can be replaced to configure the app with your own organization's branding.
+To customize the app's branding, follow the steps below.
+
+## Images and Logos
+
+All customizable images in the app are listed in the file [branding.constants.js](/src/js/constants/branding.constants.js).
+The keys in this file (e.g. `init-logo`) can be used to search for the location of each image in the app code.
+You won't need to edit the source, but this can be useful to locate each image in the app.
+
+To replace an image with your own branded version, upload your new image to `src/img/branding/custom`.
+
+Replace the value of `src` in [branding.constants.js](/src/js/constants/branding.constants.js) with the path to your new image.
+Note that webpack has been configured to access the `src/img` directory from the root, simply as `img`.
+To avoid additional changes to webpack, all image paths should begin with `img`.
+
+```javascript
+'init-logo': {
+    src: 'img/branding/custom/my-logo.png',
+},
+```
+
+### CSS
+
+New images can be configured by overriding their CSS styles.
+
+To customize an image using CSS, create a CSS file in `src/css/branding/custom/`.
+Add an `@import` statement at the end of `src/css/branding.css` to link this file into the project.
+
+New CSS files should apply styles to an image's id. Ids are defined in [branding.constants.js](/src/js/constants/branding.constants.js).
+
+In the following example, basic styles continue to apply to the logo;
+only the width is overridden by the new style sheet.
+
+Basic CSS (`src/css/branding/opal/init-logo.css`)
+```css
+#init-logo {
+    max-height: 50%;
+    object-fit: contain;
+    width: 60%;
+    z-index: 2;
+}
+```
+
+Overriding CSS (`src/css/branding/custom/init-logo.css`)
+```css
+#init-logo {
+    width: 90%;
+}
+```
+
+Import (`src/css/branding.css`)
+```css
+@import url('branding/opal/init-logo.css');
+/* ... */
+
+/* IMPORT CUSTOM BRANDING CSS FILES HERE */
+@import url('branding/custom/init-logo.css');
+```

src/css/app.css

@@ -86,6 +86,7 @@ p {
 }
 
 @import url('./animations.css');
+@import url('./branding.css');
 @import url('./dependencies/bootstrap.dependency.css');
 @import url('./dependencies/fontawesome.dependency.css');
 @import url('./dependencies/onsenui.dependency.css');

src/css/branding.css

@@ -0,0 +1,10 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (C) 2025 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <john.kildea@mcgill.ca>
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+@import url('branding/opal/init-background.css');
+@import url('branding/opal/init-logo.css');
+
+/* IMPORT CUSTOM BRANDING CSS FILES HERE */

src/css/branding/custom/README.md

@@ -0,0 +1,11 @@
+<!--
+SPDX-FileCopyrightText: Copyright (C) 2025 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <john.kildea@mcgill.ca>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Custom Branding CSS
+
+Branding images specific to your organization can be configured here via CSS files that will override their default styles.
+
+See the [Branding Setup Guide](/docs/setup/branding.md) for instructions on creating and applying these CSS overrides.

src/css/branding/opal/init-background.css

@@ -0,0 +1,11 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (C) 2025 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <john.kildea@mcgill.ca>
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#init-background {
+    height: 100%;
+    object-fit: cover;
+    width: 100%;
+}

src/css/branding/opal/init-logo.css

@@ -0,0 +1,12 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (C) 2025 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <john.kildea@mcgill.ca>
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#init-logo {
+    max-height: 50%;
+    object-fit: contain;
+    width: 60%;
+    z-index: 2;
+}

src/css/utilities.css

@@ -75,3 +75,13 @@
 	color: #2B6197;
 	text-align: center;
 }
+
+/* See: https://www.w3schools.com/HOWTO/howto_css_center-vertical.asp */
+.center-horizontal-vertical {
+	margin: 0;
+	position: absolute;
+	top: 50%;
+	left: 50%;
+	-ms-transform: translate(-50%, -50%);
+	transform: translate(-50%, -50%);
+}

src/css/views/init-page.view.css

@@ -4,34 +4,44 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+#init-header {
+    height: 40%;
+    position: relative;
+}
+
 #listInitApp div ons-button span {
     position: absolute;
     top: 50%;
     transform: translateY(-50%) translateX(-50%);
     width: 100%;
 }
+
 .listInitApp {
     display: none;
     height: 56%;
 }
+
 .initScreenButtonDiv {
     height: 15%;
     margin: 3% auto;
     text-align: center;
     width: 90%;
 }
+
 .initScreenWhiteButton {
     background-color: #F5F5F5;
     font-size: x-large;
     height: 100%;
     position: relative;
 }
+
 .initScreenGreenButton {
     background-color: #4CAF50;
     font-size: xx-large;
     font-weight: bolder;
     height: 100%;
 }
+
 .initScreenButtonText {
     color: #757575;
     display: inline-block;

src/img/branding/custom/README.md

@@ -0,0 +1,11 @@
+<!--
+SPDX-FileCopyrightText: Copyright (C) 2025 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <john.kildea@mcgill.ca>
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Custom Branding Images
+
+Branding images specific to your organization can be added here to customize the app's look and feel.
+
+See the [Branding Setup Guide](/docs/setup/branding.md) for instructions on linking these assets to the app's UI.

src/js/app.constants.js

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import "./constants/app.constants";
+import "./constants/branding.constants.js";
 import "./constants/questionnaire.constants";
 import "./constants/request.constants";
 import "./constants/api.constants";

src/js/app.filters.js

@@ -2,6 +2,8 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
+import './filters/branding-id.filter.js';
+import './filters/branding-src.filter.js';
 import './filters/filters';
 import './filters/replaceAll.filter';
 import './filters/showHeader.filter';

src/js/constants/branding.constants.js

@@ -0,0 +1,23 @@
+// SPDX-FileCopyrightText: Copyright (C) 2025 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <john.kildea@mcgill.ca>
+//
+// SPDX-License-Identifier: Apache-2.0
+
+// For more information on this file, see `docs/setup/branding.md`.
+
+(function () {
+    'use strict';
+
+    angular
+        .module('OpalApp')
+        .constant('Branding', {
+            // INIT PAGE
+            'init-background': {
+                id: 'init-background',
+                src: 'img/branding/opal/init-background.jpg',
+            },
+            'init-logo': {
+                id: 'init-logo',
+                src: 'img/branding/opal/Opal_Name_Logo_Transparent.png',
+            },
+        });
+})();

src/js/filters/branding-id.filter.js

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: Copyright (C) 2025 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <john.kildea@mcgill.ca>
+//
+// SPDX-License-Identifier: Apache-2.0
+
+(function () {
+    'use strict';
+
+    angular
+        .module('OpalApp')
+        .filter('brandingId', BrandingId);
+
+    BrandingId.$inject = ['Branding'];
+
+    function BrandingId(Branding) {
+        return (keyword) => {
+            let id = Branding[keyword]?.id;
+            if (!id) throw `Branding id not configured for resource '${keyword}'`;
+            return id;
+        }
+    }
+})();

src/js/filters/branding-src.filter.js

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: Copyright (C) 2025 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <john.kildea@mcgill.ca>
+//
+// SPDX-License-Identifier: Apache-2.0
+
+(function () {
+    'use strict';
+
+    angular
+        .module('OpalApp')
+        .filter('brandingSrc', BrandingSrc);
+
+    BrandingSrc.$inject = ['Branding'];
+
+    function BrandingSrc(Branding) {
+        return (keyword) => {
+            let src = Branding[keyword]?.src;
+            if (!src) throw `Branding source not configured for resource '${keyword}'`;
+            return src;
+        }
+    }
+})();

src/views/init/init-screen.html

@@ -6,18 +6,14 @@
 
 <ons-page id="popoverLanguage" ng-controller="InitScreenController as init">
 
+    <!-- NETWORK BANNER -->
+    <!-- Style the network banner to make it overlap the picture-logo -->
+    <network-banner style="position:absolute; top:0; left:0; z-index:9999"></network-banner>
+
      <!-- IMAGE HEADER -->
-     <div style="position: relative; height: 40%">
-        <div style="z-index:2;width:100%" align="center">
-            <!-- Style on network banner used to make it overlap the picture-logo instead of push it down. -->
-            <network-banner style="position:absolute; top:0; left:0; z-index:9999"></network-banner>
-            <div style="position: absolute; top: 50%;transform: translateY(-50%);" align="center">
-                <img src="img/Opal_Name_Logo_Transparent.png" style="width:75%;height:auto">
-            </div>
-        </div>
-        <div style="height: 100%">
-            <img id="init-background" src="img/opal-init-photo.jpg" style="width: 100%; height: 100%; object-fit: cover">
-        </div>
+     <div id="init-header">
+         <img id="{{ 'init-logo' | brandingId }}" class="center-horizontal-vertical" ng-src="{{ 'init-logo' | brandingSrc }}">
+         <img id="{{ 'init-background' | brandingId }}" ng-src="{{ 'init-background' | brandingSrc }}">
     </div>
 
     <!-- LIST OF BUTTONS -->