diff --git a/assemblies/assembly-configuring-the-global-header.adoc b/assemblies/assembly-configuring-the-global-header.adoc index 9f17ac8ea2..bea26ed891 100644 --- a/assemblies/assembly-configuring-the-global-header.adoc +++ b/assemblies/assembly-configuring-the-global-header.adoc @@ -18,6 +18,13 @@ 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-configuring-logo-in-the-global-header.adoc[leveloffset=+1] + +include::modules/configuring-the-global-header/proc-enabling-logo-in-the-sidebar.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] \ No newline at end of file +include::modules/configuring-the-global-header/proc-enabling-quicklinks-starred-items-after-upgrade.adoc[leveloffset=+1] + diff --git a/modules/configuring-the-global-header/proc-configuring-logo-in-the-global-header.adoc b/modules/configuring-the-global-header/proc-configuring-logo-in-the-global-header.adoc new file mode 100644 index 0000000000..826c75df59 --- /dev/null +++ b/modules/configuring-the-global-header/proc-configuring-logo-in-the-global-header.adoc @@ -0,0 +1,89 @@ +[id="configuring-logo-in-the-global-header.adoc_{context}"] += Configuring the 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. + +This component supports the following props, which are provided through configuration: + +* `logo`: The base64 encoded logo image. +* `to`: The redirect path for when users click the logo is '/catalog'. +* `width`: The logo width is optional and defaults to 150 px. +* `height`: The logo height is optional and defaults to 40px. + +.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: or # Logo can be a base64 string or theme-specific object + # Example 1: Single logo for all themes + # logo: "" + + # Example 2: Theme-specific logos + # logo: + dark: 'data:image/png;base64,...' # Used in dark theme + light: 'data:image/png;base64,...' # Used in light theme +---- + +. (Optional) If you do not provide `logo` props to the `CompanyLogo` component, the component instead uses values defined under `app.branding` in your `{my-app-config-file}` file. You can configure the `CompanyLogo` as shown in the following configuration: ++ +.Example: Fallback configuration ++ +[source,yaml,subs="+attributes,+quotes"] +---- +app: + branding: + fullLogoWidth: 220 # Fallback width + fullLogo: or #fullLogo can be a base64 string or theme-specific object + + # Example 1: Single logo for all themes + #fullLogo: " + # Example 2: Theme-specific logos + #fullLogo: + dark: 'data:image/png;base64,...' # Used in dark theme + light: 'data:image/png;base64,...' # Used in light theme +---- ++ +`CompanyLogo` uses the following configuration elements to control fallback and sizing behavior: + +* *Logo source priority* +** The component selects the logo source in the following order: ++ +First, `CompanyLogo` props (logo, logo.light, logo.dark), then, `app.branding.fullLogo`. If you do not provide a logo through either, the component displays the default {product-short} theme-specific logo. + +* *Logo width priority* +** The component applies the first available value from `props.width`, then `app.branding.fullLogoWidth` from `{my-app-config-file}`. If you do not specify the `width` using either, the component applies a default width (150 px). + +[NOTE] +==== +`CompanyLogo` preserves the images aspect ratio and never crops or distorts it. If the configured width results in a height greater than the maximum allowed (default: 40px), the image is automatically scaled down. As a result, adjusting only the width may not visibly change the logo unless the height is also configured. + +Increasing the logo `height` increases the height of the global header. The component first applies the value from `props.height`. If you do not specify the `height`, the component applies a default height (40px). +==== + +.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`. diff --git a/modules/configuring-the-global-header/proc-displaying-preferred-username-in-profile-drop-down.adoc b/modules/configuring-the-global-header/proc-displaying-preferred-username-in-profile-drop-down.adoc new file mode 100644 index 0000000000..630b3a5e4b --- /dev/null +++ b/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: __ + # Optional preferred title + title: __ +spec: + profile: + # Optional preferred display name (highest priority) + displayName: __ + 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: __ + # Optional preferred title + 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: __ +spec: + memberOf: [janus-authors] +---- + +[NOTE] +==== +The application falls back to `metadata.name` when you do not register the user entity. +==== \ No newline at end of file diff --git a/modules/configuring-the-global-header/proc-enabling-logo-in-the-sidebar.adoc b/modules/configuring-the-global-header/proc-enabling-logo-in-the-sidebar.adoc new file mode 100644 index 0000000000..4fc44f4cf1 --- /dev/null +++ b/modules/configuring-the-global-header/proc-enabling-logo-in-the-sidebar.adoc @@ -0,0 +1,56 @@ +[id="proc-enabling-logo-in-the-sidebar.adoc_{context}"] += Enabling logo in the sidebar + +You can configure a logo in the sidebar of the {product} ({product-very-short}). + +.Procedure + +. To display the logo in the sidebar, set the value of the `app.sidebar.logo` parameter to `true` as shown in the following example: ++ +.Example: Enabling the logo in only the sidebar ++ +[source,yaml,subs="+attributes,+quotes"] +---- +app: + sidebar: + logo: true +---- ++ +[NOTE] +==== +To display the logo in only the sidebar, remove the `CompanyLogo` component from the configuration. +==== + +. To display the same logo in the sidebar for all themes, update the configuration as shown in the following configuration: ++ +.Example: Configuring sidebar logo for all themes ++ +[source,yaml,subs="+attributes,+quotes"] +---- +app: + sidebar: + logo: true + branding: + fullLogoWidth: 220 + fullLogo: 'data:image/svg+xml;base64,...' +---- + +. For theme-specific logos, you can configure the sidebar logo as shown in the following configuration: ++ +.Example: Theme-specific logos ++ +[source,yaml,subs="+attributes,+quotes"] +---- +app: + sidebar: + logo: true + branding: + fullLogoWidth: 220 + fullLogo: + light: 'data:image/svg+xml;base64,...' + dark: 'data:image/svg+xml;base64,...' +---- + +.Verification +. The logo appears correctly in the sidebar. +. Toggle between `light` and `dark` themes to ensure the correct logo loads in each. \ No newline at end of file