diff --git a/assemblies/assembly-configuring-the-global-header.adoc b/assemblies/assembly-configuring-the-global-header.adoc index 9f17ac8ea2..33eda1f289 100644 --- a/assemblies/assembly-configuring-the-global-header.adoc +++ b/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] \ 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-displaying-company-logo-in-the-global-header.adoc b/modules/configuring-the-global-header/proc-displaying-company-logo-in-the-global-header.adoc new file mode 100644 index 0000000000..c156bcea51 --- /dev/null +++ b/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`. 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