Home.md
... ...
@@ -39,6 +39,7 @@ SAP is at the center of today’s technology revolution, developing innovations
39 39
* [[Whitelabelling|wiki/howto/whitelabelling]]
40 40
* [[Secured Settings|wiki/howto/development/secured-settings]]
41 41
* [[Webdesign|wiki/info/landscape/webdesign]]
42
+* [[Branding Setup|wiki/info/landscape/branding-setup]]
42 43
43 44
### Architecture and Infrastructure
44 45
* [[Workspace, Bundles, Projects|wiki/info/general/workspace-bundles-projects-structure]]
wiki/info/landscape/branding-setup.md
... ...
@@ -0,0 +1,245 @@
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 `Eclipse → File → New → Plug-in Development → Plug-in Project`
38
+ * Place it under the `java` folder in your workspace
39
+ * A branding bundle must register its implementation of `BrandingConfiguration` in the **OSGi Service Registry**. So, provide an `Activator` that registers your Branding Service.
40
+
41
+2. **Register your bundle**
42
+
43
+ * Add the new bundle to the following files:
44
+
45
+ * `raceanalysis.product`
46
+ * `pom.xml` in the `git/java` folder
47
+ * `feature.xml` (within `com.sap.sse.feature`)
48
+
49
+ More information about project and bundle requirements can be found here:
50
+ [Adding an OSGi bundle](https://wiki.sapsailing.com/wiki/info/landscape/typical-development-scenarios.md#adding-an-osgi-bundle) and
51
+ [Bundles structure](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`). All current configuration methods' purpose is explained in the Javadoc on the interface itself: see `java/com.sap.sse.branding/src/com/sap/sse/branding/shared/BrandingConfiguration.java` implementation.
64
+
65
+You can override methods to define your custom branding behavior.
66
+Some methods rely on `SailingServerStringMessages`, which works similarly to message resources. Provide English and German (de) messages together for any new text added to branding.
67
+Localization details can be found here:
68
+[Translation and i18n](https://wiki.sapsailing.com/wiki/howto/development/i18n.md).
69
+
70
+## 4. Adding New Branding Attributes
71
+
72
+If you want to extend the branding (e.g., add background color or other brand-specific parameters), follow these implementation steps:
73
+
74
+### Step 1: Add New Variables and Getters
75
+
76
+Add the corresponding variables and getter methods in:
77
+
78
+* `ClientConfiguration.java`
79
+* `ClientConfigurationContextDataJSO.java`
80
+* `YourBrandNameBrandingConfiguration.java`
81
+
82
+**Example method name:**
83
+
84
+```java
85
+getSailingAnalyticsSapSailing()
86
+```
87
+
88
+### Step 2: Update the Branding Configuration Service
89
+
90
+* Modify `BrandingConfigurationServiceImpl.java` to include your new property.
91
+* Add it to the property map in `BrandingConfigurationService.java` (e.g., `SAILING_ANALYTICS_SAP_SAILING`).
92
+
93
+### Step 3: Update Localization Files
94
+
95
+If needed, modify:
96
+
97
+```
98
+BrandingStringMessages_lang.properties
99
+```
100
+
101
+to include your new configuration string (e.g., `'SAP Sailing'`).
102
+
103
+### Step 4: Clean Up Deprecated Strings
104
+
105
+Remove old occurrences of the string variable from:
106
+
107
+* `StringMessages_lang.properties`
108
+* `StringMessages.java` (client side)
109
+
110
+### Step 5: Replace with New Implementation
111
+
112
+Use your new getter where the old implementation was previously used:
113
+
114
+```java
115
+ClientConfiguration.getInstance().yourGetter()
116
+```
117
+
118
+Instead of:
119
+
120
+```java
121
+StringMessages.INSTANCE.actualStringMessage()
122
+```
123
+
124
+---
125
+
126
+## 5. Testing Your Branding Configuration
127
+
128
+**Prerequisite:** Ensure **telnet** is installed on your local machine.
129
+
130
+### Testing Steps
131
+
132
+1. **Connect via telnet**
133
+
134
+ ```bash
135
+ telnet localhost 12001
136
+ ```
137
+
138
+2. **Search for branding**
139
+
140
+ ```text
141
+ osgi> ss brand
142
+ Framework is active.
143
+
144
+ id State Bundle
145
+ 108 ACTIVE com.sap.sse.branding.sap (1.2.3)
146
+ ```
147
+
148
+3. **Toggle branding on/off**
149
+
150
+ ```text
151
+ start 108
152
+ stop 108
153
+ ```
154
+
155
+ *(ID `108` corresponds to branding for this example.)*
156
+
157
+4. **Disconnect**
158
+
159
+ ```text
160
+ disconnect
161
+ ```
162
+
163
+ Confirm with `y` (yes).
164
+
165
+This allows you to verify how your custom branding is applied and displayed dynamically.
166
+
167
+---
168
+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.
169
+
170
+---
171
+## 6. Why These Steps Are Necessary
172
+
173
+### 1. Separation of Concerns
174
+
175
+Each branding-related class has a specific role in the client–server pipeline:
176
+
177
+| Component | Role | Location |
178
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
179
+| **`YourBrandNameBrandingConfiguration`** | Defines static and localized branding resources such as image URLs, localized texts, or external links. | Server-side (OSGi bundle) |
180
+| **`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 |
181
+| **`ClientConfigurationContextDataJSO`** | Reads that JSON object in the browser, providing native GWT access to branding fields. | Client-side (GWT JavaScript overlay) |
182
+| **`ClientConfiguration`** | Consumes values from `ClientConfigurationContextDataJSO` and exposes convenient Java getters for UI code. | Client-side (GWT Java) |
183
+
184
+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.
185
+
186
+---
187
+
188
+### 2. Why Each Step Exists
189
+
190
+* **Step 1 (New Variables/Getters):**
191
+ 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`.
192
+
193
+* **Step 2 (Update Service):**
194
+ The `BrandingConfigurationServiceImpl` class generates the client-facing configuration JSON that feeds GWT. Without updating it, your new field would never reach the browser.
195
+ The property map ensures the new key appears in:
196
+
197
+ ```json
198
+ document.clientConfigurationContext={"brandTitle":"SAP","backgroundColor":"#004080",...}
199
+ ```
200
+
201
+* **Step 3 (Localization):**
202
+ When branding text differs across languages, translations are handled through `.properties` files loaded by `ResourceBundleStringMessages`. This ensures locale-dependent branding output.
203
+
204
+* **Step 4 (Cleanup):**
205
+ Legacy or hardcoded UI strings are replaced by dynamic configuration values. This avoids inconsistencies and allows true runtime branding/debranding.
206
+
207
+* **Step 5 (Replacement):**
208
+ The UI must always call `ClientConfiguration.getInstance().yourGetter()` — this guarantees the displayed text, logos, or links match the currently active branding context.
209
+
210
+---
211
+
212
+### 3. How It Works Technically
213
+
214
+1. The backend OSGi service (`BrandingConfigurationServiceImpl`) collects data from the active `BrandingConfiguration` (e.g., `SAPBrandingConfiguration`).
215
+2. It maps these fields to standardized property names (defined in `BrandingConfigurationService.BrandingConfigurationProperty`).
216
+3. It serializes them into a JSON object and injects a `<script>` into the HTML page:
217
+
218
+ ```html
219
+ <script>document.clientConfigurationContext={"brandingActive":true,"brandTitle":"SAP",...};</script>
220
+ ```
221
+4. The GWT client loads this script at startup.
222
+5. `ClientConfigurationContextDataJSO` provides Java-accessible wrappers around this JSON.
223
+6. `ClientConfiguration` instantiates itself with these values and becomes globally available through `ClientConfiguration.getInstance()`.
224
+
225
+This chain ensures that any new field you define in the backend automatically becomes available to the UI once the above steps are followed.
226
+
227
+---
228
+
229
+### 4. Summary
230
+
231
+By following this pattern:
232
+
233
+* Every new branding attribute becomes part of the unified configuration context.
234
+* The GWT client automatically receives and uses the latest configuration from the backend.
235
+* Debranding and white-labeling remain dynamically switchable at runtime.
236
+* All UI components rely on consistent, centrally managed branding information.
237
+
238
+
239
+---
240
+
241
+## 7. Conclusion
242
+
243
+By following this setup, you can create and integrate a fully customized branding layer for **Sailing Analytics**, including logos, localized texts, and design assets.
244
+The modular design allows you to extend branding attributes to reflect your organization’s visual identity while maintaining compatibility with the base system.
245
+With consistent testing (via telnet) and clear property configuration, you can reliably switch between **branded** and **debranded** experiences.