mgr/dashboard: Add branding documentation

Explains how to brand the ui without running in merge conflicts once a source
file gets updated

Signed-off-by: Sebastian Krah <skrah@suse.com>

diff --git a/src/pybind/mgr/dashboard/HACKING.rst b/src/pybind/mgr/dashboard/HACKING.rst
index 6446aa5bba8f8d78aaf7d3da6a44b5529ed6f754..ccbcdc1da05d5fb1ed7c791415ef87a2e84ae51f 100644 (file)
--- a/src/pybind/mgr/dashboard/HACKING.rst
+++ b/src/pybind/mgr/dashboard/HACKING.rst
@@ -230,6 +230,48 @@ Example:
       Some <strong>helper</strong> html text
     </cd-helper>
 
+Frontend branding
+~~~~~~~~~~~~~~~~~
+
+Every vendor can customize the 'Ceph dashboard' to his needs. No matter if
+Logo, HTML-Template or Typescript, every file inside the frontend folder can be
+replaced.
+
+To replace files, open ``./frontend/angular.json`` and scroll to the section
+``fileReplacements`` inside the production configuration. Here you can add the
+files you wish to brand. We recommend to place the branded version of a file in
+the same directory as the original one and to add a ``.brand`` to the file
+name, right in front of the file extension. A ``fileReplacement`` could for
+example look like this:
+
+.. code:: javascript
+
+    {
+      "replace": "src/app/core/auth/login/login.component.html",
+      "with": "src/app/core/auth/login/login.component.brand.html"
+    }
+
+To serve or build the branded user interface run:
+
+    $ npm run start -- --prod
+
+or
+
+    $ npm run build -- --prod
+
+Unfortunately it's currently not possible to use multiple configurations when
+serving or buildung the ui at the same time. That means a configuration just
+for the branding ``fileReplacements`` it not an option, because you want to use
+the production configuration anyway
+(https://github.com/angular/angular-cli/issues/10612).
+Furthermore it's also not possible to use glob expressions for
+``fileReplacements``. As long as the feature hasn't been implemented, the
+vendor has to add the file replacements manually to the angular.json
+(https://github.com/angular/angular-cli/issues/12354).
+
+Nethertheless you should stick to the suggested naming scheme because it makes
+it easier for you to use glob expressions once it's supported in the future.
+
 I18N
 ----