RHIDP-7614: Displaying the preferred username and Company Logo

assemblies/assembly-configuring-the-global-header.adoc

@@ -18,6 +18,11 @@ include::modules/configuring-the-global-header/proc-customize-rhdh-global-header
 
 include::modules/configuring-the-global-header/proc-mount-points.adoc[leveloffset=+1]
 
+include::modules/configuring-the-global-header/proc-displaying-company-logo-in-the-global-header.adoc[leveloffset=+1]
+
+include::modules/configuring-the-global-header/proc-displaying-preferred-username-in-profile-drop-down.adoc[leveloffset=+1]
+
 include::modules/configuring-the-global-header/con-quicklinks-and-starred-items-in-global-header.adoc[leveloffset=+1]
 
-include::modules/configuring-the-global-header/proc-enabling-quicklinks-starred-items-after-upgrade.adoc[leveloffset=+1]
+include::modules/configuring-the-global-header/proc-enabling-quicklinks-starred-items-after-upgrade.adoc[leveloffset=+1]
+

modules/configuring-the-global-header/proc-displaying-company-logo-in-the-global-header.adoc

@@ -0,0 +1,92 @@
+[id="displaying-company-logo-in-the-global-header.adoc_{context}"]
+= Displaying company logo in the global header
+
+You can configure a company logo in the global header of the {product} ({product-very-short}) to reflect your company's branding. `CompanyLogo` is part of the global header by default and offers full control over the theming, navigation behavior, sizing, and fallback options.
+
+`CompanyLogo` ensures strict display constraints to maintain design consistency:
+
+* The default maximum dimensions: `150px` wide, `40px` high.
+* The logo must retain its original proportions using `object-fit: contain`.
+* The component keeps its layout fixed and you cannot move it from its mount point.
+* `CompanyLogo` automatically scales the image down if dimensions exceed allowed size.
+
+This component also supports the following props:
+
+* `logo`: The encoded logo image.
+* `to`: The redirect path for when users click the logo.
+* `width`:	Optional width of the logo.
+* `height`: Optional height of the logo.
+
+.Procedure
+
+. To display a custom company logo in the global header, update the configuration with a mount point for `CompanyLogo`:
++
+.Example: Configuring company logo
++
+[source,yaml,subs="+attributes,+quotes"]
+----
+# ...rest of the global header configuration
+red-hat-developer-hub.backstage-plugin-global-header:
+  mountPoints:
+    - mountPoint: application/header
+      importName: GlobalHeader
+      config:
+        # Supported values: `above-main-content` | `above-sidebar`
+        position: above-main-content
+
+    - mountPoint: global.header/component
+      importName: CompanyLogo
+      config:
+        priority: 200
+        props:
+          # Path to navigate when users click the logo:
+          to: '/catalog'
+          width: 300
+          height: 200
+          #logo: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAATQAAACkCAMAAAAuT...' # Single logo for all themes
+          logo:
+            dark: 'data:image/png;base64,...' # Shown in dark theme
+            light: 'data:image/png;base64,...' # Shown in light theme
+----
++
+You can use either a single logo for all themes or theme-specific logos (light and dark). If you define both, theme-specific logos take precedence over the single logo.
+
+. (Optional) If you do not provide props to the `CompanyLogo` component, the component instead uses values defined under `app.branding` in your `{my-app-config-file}` file. You can configure both the sidebar logo and the `CompanyLogo` fallback as shown in the following configuration:
++
+.Example: Fallback configuration
++
+[source,yaml,subs="+attributes,+quotes"]
+----
+app:
+  branding:
+    fullLogoWidth: 220  # Fallback width
+    # fullLogo: "data:image/svg+xml;base64,..."
+    fullLogo:
+      light: 'data:image/svg+xml;base64,...'
+      dark: 'data:image/svg+xml;base64,...'
+----
++
+`CompanyLogo` uses the following configuration elements to control fallback and sizing behavior:
+
+* *Logo source priority*
+** If you fail to provide a logo through either the `CompanyLogo` props (`logo`, `logo.light`, `logo.dark`) or `app.branding.fullLogo`, the component displays the default {product-short} theme-specific logo.
+
+* *Logo width priority*
+** If you fail to specify the `width` using the `CompanyLogo` prop (`props.width`) or through the `app.branding.fullLogoWidth` from `{my-app-config-file}`, the component applies a default width.
+** If the `width` component that you configure results in a height greater than the default maximum height, the component automatically scales the logo down.
++
+In some cases, changing only the width might not visibly affect the logo unless you also adjust the height.
+
+* *Logo height priority*
+** If you do not specify `height` using the `CompanyLogo` prop (`props.height`), the component automatically applies a default maximum height.
++
+[NOTE]
+====
+If you increase the company logo height, the global header height also increases, but the image does not appear cropped or distorted.
+====
+
+.Verification
+. The logo appears correctly in the global header.
+. Click the logo to confirm it redirects to the path you defined in `props.to`.
+. Toggle between `light` and `dark` themes to ensure the correct logo loads in each.
+. (Optional) Temporarily remove the `CompanyLogo` props to test the fallback to `app.branding.fullLogo`.

modules/configuring-the-global-header/proc-displaying-preferred-username-in-profile-drop-down.adoc

@@ -0,0 +1,56 @@
+[id="displaying-preferred-username-in-global-header-profile-drop-down_{context}"]
+= Displaying the preferred username in the profile dropdown
+
+You can display the preferred username in the global header profile drop-down list by configuring `spec.profile.displayName` in the user entity. When not configured, the application falls back to a `metadata.title`. If neither is configured, it defaults to a user-friendly name generated by the `useProfileInfo` hook.
+
+.Procedure
+.Example when you configure `spec.profile.displayName`
+
+[source,yaml,subs="+attributes,+quotes"]
+----
+apiVersion: backstage.io/v1alpha1
+kind: User
+metadata:
+  # Required unique username
+  name: _<my_display_name>_
+  # Optional preferred title
+  title: _<display_name_title>_
+spec:
+  profile:
+    # Optional preferred display name (highest priority)
+    displayName: _<my_display_name>_
+  memberOf: [janus-authors]
+----
+
+.Example when you do not configure `spec.profile.displayname` but configure `metadata.title`
+
+[source,yaml,subs="+attributes,+quotes"]
+----
+apiVersion: backstage.io/v1alpha1
+kind: User
+metadata:
+  # Required unique username
+  name: _<my_display_name>_
+  # Optional preferred title
+  title: _<display_name_title>_
+spec:
+  memberOf: [janus-authors]
+----
+
+.Example when you do not configure the `spec.profile.displayname` and the `metadata.title`
+
+[source,yaml,subs="+attributes,+quotes"]
+----
+apiVersion: backstage.io/v1alpha1
+kind: User
+metadata:
+  # Required unique username
+  name: _<my_display_name>_
+spec:
+  memberOf: [janus-authors]
+----
+
+[NOTE]
+====
+The application falls back to `metadata.name` when you do not register the user entity.
+====