wiki/info/landscape/branding-setup.md
... ...
@@ -0,0 +1,258 @@
1
+# Rebranding and Debranding Configuration Setup
2
+
3
+This document explains how to integrate your own branding into **Sailing Analytics** or switch to the **debranded** version.
4
+It provides step-by-step guidance on configuring, extending, and testing branding functionality.
5
+
6
+---
7
+
8
+## 1. Changing Between Branding and Debranding Modes
9
+
10
+Branding configuration can be controlled via **system properties**.
11
+Add the following parameter when starting the application:
12
+
13
+```bash
14
+-Dcom.sap.sse.branding=YOUR_BRAND_NAME
15
+```
16
+
17
+* `YOUR_BRAND_NAME` corresponds to the ID you will define later in your custom branding configuration.
18
+* If no system property is specified, the **debranded version** of the application will be displayed by default.
19
+
20
+---
21
+
22
+## 2. Enabling Branding Support
23
+
24
+To enable custom branding, you need to configure:
25
+
26
+* Logos and icons
27
+* Titles and descriptions
28
+* Localized text (via `sailingServerStringMessages`)
29
+
30
+As a reference, review the project:
31
+`com.sap.sse.branding.sap`
32
+
33
+### Steps to Create and Register a Branding Project
34
+
35
+1. **Create a new web application project**
36
+
37
+ * Navigate to `File → New → Create Web Application Project`
38
+ * Place it under the `java` folder in your workspace
39
+
40
+2. **Register your bundle**
41
+
42
+ * Add the new bundle to the following files:
43
+
44
+ * `raceanalysis.product`
45
+ * Root `pom.xml` (in the `java` folder)
46
+ * `feature.xml` (within `com.sap.sse.feature`)
47
+
48
+3. **Consult workspace documentation**
49
+ More information about project and bundle requirements can be found here:
50
+ `https://wiki.sapsailing.com/wiki/info/landscape/typical-development-scenarios.md#adding-an-osgi-bundle` and
51
+ `https://wiki.sapsailing.com/wiki/info/general/workspace-bundles-projects-structure.md`
52
+
53
+---
54
+
55
+## 3. Available Branding Configuration Options
56
+
57
+Create your own configuration class, for example:
58
+
59
+```
60
+YourBrandNameBrandingConfiguration.java
61
+```
62
+
63
+This class must **implement** the `BrandingConfiguration` interface (see: `SAPBrandingConfiguration.java`).
64
+
65
+You can override methods to define your custom branding behavior.
66
+Some methods rely on `sailingServerStringMessages`, which works similarly to message resources.
67
+Localization details can be found here:
68
+`https://wiki.sapsailing.com/wiki/howto/development/i18n.md`
69
+
70
+### Overview of Key Configuration Methods
71
+
72
+| Method | Purpose |
73
+| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
74
+| `getId()` | Returns the brand ID (used in system properties). |
75
+| `getDefaultBrandingLogoURL()` | Main logo (headers, favicon, etc.). |
76
+| `getGreyTransparentLogoURL()` | Transparent logo used inside the **Race Tracking** tab. |
77
+| `getBrandTitle()` | Brand display name. |
78
+| `getSolutionsInSailingImageURL()`, `getSailingRaceManagerAppImageURL()`, `getSailInSightAppImageURL()`, etc. | Images shown in the **Solutions** tab. |
79
+| Footer getters (e.g., `getFooterCopyright()`, `getFooterLegalLink()`) | Footer links and copyright. Empty values are hidden. |
80
+| Social getters (e.g., `getSportsOn()`, `getFollowSports()`, `getFacebookLink()`) | Social links on the Home page footer. Optional. |
81
+| `getWelcomeToSailingAnalytics()`, `getWelcomeToSailingAnalyticsBody()` | Welcome widget messages. |
82
+| `getMoreLoginInformationNotificationsURL()`, `getMoreLoginInformationSettingsURL()`, etc. | Popup images for “more login information” (you need to log out in order to test it locally). |
83
+| `getInSailingContent()` | HTML/text under “YourBrandName in Sailing” in the **Solutions** tab (HTML allowed). |
84
+
85
+---
86
+
87
+## 4. Adding New Branding Attributes
88
+
89
+If you want to extend the branding (e.g., add background color or other brand-specific parameters), follow these implementation steps:
90
+
91
+### Step 1: Add New Variables and Getters
92
+
93
+Add the corresponding variables and getter methods in:
94
+
95
+* `ClientConfiguration.java`
96
+* `ClientConfigurationContextDataJSO.java`
97
+* `YourBrandNameBrandingConfiguration.java`
98
+
99
+**Example method name:**
100
+
101
+```java
102
+getSailingAnalyticsSapSailing()
103
+```
104
+
105
+### Step 2: Update the Branding Configuration Service
106
+
107
+* Modify `BrandingConfigurationServiceImpl.java` to include your new property.
108
+* Add it to the property map in `BrandingConfigurationService.java` (e.g., `SAILING_ANALYTICS_SAP_SAILING`).
109
+
110
+### Step 3: Update Localization Files
111
+
112
+If needed, modify:
113
+
114
+```
115
+BrandingStringMessages_lang.properties
116
+```
117
+
118
+to include your new configuration string (e.g., `'SAP Sailing'`).
119
+
120
+### Step 4: Clean Up Deprecated Strings
121
+
122
+Remove old occurrences of the string variable from:
123
+
124
+* `StringMessages_lang.properties`
125
+* `StringMessages.java` (client side)
126
+
127
+### Step 5: Replace with New Implementation
128
+
129
+Use your new getter where the old implementation was previously used:
130
+
131
+```java
132
+ClientConfiguration.getInstance().yourGetter()
133
+```
134
+
135
+Instead of:
136
+
137
+```java
138
+StringMessages.INSTANCE.actualStringMessage()
139
+```
140
+
141
+---
142
+
143
+## 5. Testing Your Branding Configuration
144
+
145
+**Prerequisite:** Ensure **telnet** is installed on your local machine.
146
+
147
+### Testing Steps
148
+
149
+1. **Connect via telnet**
150
+
151
+ ```bash
152
+ telnet localhost 12001
153
+ ```
154
+
155
+2. **Search for branding**
156
+
157
+ ```text
158
+ ss brand
159
+ ```
160
+
161
+3. **Toggle branding on/off**
162
+
163
+ ```text
164
+ start 108
165
+ stop 108
166
+ ```
167
+
168
+ *(ID `108` corresponds to branding.)*
169
+
170
+4. **Disconnect**
171
+
172
+ ```text
173
+ disconnect
174
+ ```
175
+
176
+ Confirm with `y` (yes).
177
+
178
+This allows you to verify how your custom branding is applied and displayed dynamically.
179
+
180
+---
181
+Here’s your full `.md` documentation version — clear, structured, and with an explanatory section at the end that describes **why** each step is needed and **how** the branding extension mechanism works internally.
182
+
183
+---
184
+## 6. Why These Steps Are Necessary
185
+
186
+### 1. Separation of Concerns
187
+
188
+Each branding-related class has a specific role in the client–server pipeline:
189
+
190
+| Component | Role | Location |
191
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
192
+| **`YourBrandNameBrandingConfiguration`** | Defines static and localized branding resources such as image URLs, localized texts, or external links. | Server-side (OSGi bundle) |
193
+| **`BrandingConfigurationServiceImpl`** | Acts as the bridge between backend branding configurations and the client. It collects active configuration data into a property map and generates the `document.clientConfigurationContext` JSON object. | Server-side |
194
+| **`ClientConfigurationContextDataJSO`** | Reads that JSON object in the browser, providing native GWT access to branding fields. | Client-side (GWT JavaScript overlay) |
195
+| **`ClientConfiguration`** | Consumes values from `ClientConfigurationContextDataJSO` and exposes convenient Java getters for UI code. | Client-side (GWT Java) |
196
+
197
+When you add a new property (e.g., `backgroundColor`), you extend all these layers so the value flows **end-to-end** — from the backend branding definition to the live UI rendering in the browser.
198
+
199
+---
200
+
201
+### 2. Why Each Step Exists
202
+
203
+* **Step 1 (New Variables/Getters):**
204
+ These getters form the “public interface” for your new property. The client cannot use or bind values unless they are exposed through `ClientConfiguration` and its JavaScript overlay `ClientConfigurationContextDataJSO`.
205
+
206
+* **Step 2 (Update Service):**
207
+ The `BrandingConfigurationServiceImpl` class generates the client-facing configuration JSON that feeds GWT. Without updating it, your new field would never reach the browser.
208
+ The property map ensures the new key appears in:
209
+
210
+ ```json
211
+ document.clientConfigurationContext={"brandTitle":"SAP","backgroundColor":"#004080",...}
212
+ ```
213
+
214
+* **Step 3 (Localization):**
215
+ When branding text differs across languages, translations are handled through `.properties` files loaded by `ResourceBundleStringMessages`. This ensures locale-dependent branding output.
216
+
217
+* **Step 4 (Cleanup):**
218
+ Legacy or hardcoded UI strings are replaced by dynamic configuration values. This avoids inconsistencies and allows true runtime branding/debranding.
219
+
220
+* **Step 5 (Replacement):**
221
+ The UI must always call `ClientConfiguration.getInstance().yourGetter()` — this guarantees the displayed text, logos, or links match the currently active branding context.
222
+
223
+---
224
+
225
+### 3. How It Works Technically
226
+
227
+1. The backend OSGi service (`BrandingConfigurationServiceImpl`) collects data from the active `BrandingConfiguration` (e.g., `SAPBrandingConfiguration`).
228
+2. It maps these fields to standardized property names (defined in `BrandingConfigurationService.BrandingConfigurationProperty`).
229
+3. It serializes them into a JSON object and injects a `<script>` into the HTML page:
230
+
231
+ ```html
232
+ <script>document.clientConfigurationContext={"brandingActive":true,"brandTitle":"SAP",...};</script>
233
+ ```
234
+4. The GWT client loads this script at startup.
235
+5. `ClientConfigurationContextDataJSO` provides Java-accessible wrappers around this JSON.
236
+6. `ClientConfiguration` instantiates itself with these values and becomes globally available through `ClientConfiguration.getInstance()`.
237
+
238
+This chain ensures that any new field you define in the backend automatically becomes available to the UI once the above steps are followed.
239
+
240
+---
241
+
242
+### 4. Summary
243
+
244
+By following this pattern:
245
+
246
+* Every new branding attribute becomes part of the unified configuration context.
247
+* The GWT client automatically receives and uses the latest configuration from the backend.
248
+* Debranding and white-labeling remain dynamically switchable at runtime.
249
+* All UI components rely on consistent, centrally managed branding information.
250
+
251
+
252
+---
253
+
254
+## 7. Conclusion
255
+
256
+By following this setup, you can create and integrate a fully customized branding layer for **Sailing Analytics**, including logos, localized texts, and design assets.
257
+The modular design allows you to extend branding attributes to reflect your organization’s visual identity while maintaining compatibility with the base system.
258
+With consistent testing (via telnet) and clear property configuration, you can reliably switch between **branded** and **debranded** experiences.