From 28faf83378a7a29d5f3a15b8444fcd748189c896 Mon Sep 17 00:00:00 2001 From: Fahri Gedik Date: Thu, 9 Oct 2025 15:43:19 +0300 Subject: [PATCH 1/2] Add article on changing logo in Angular ABP apps Introduces a new community article detailing how to configure and customize the application logo in Angular ABP applications. The article explains the migration of the logo provider to '@abp/ng.theme.shared', outlines the benefits of the new approach, and provides step-by-step implementation guidance. --- .../article.md | 149 ++++++++++++++++++ 1 file changed, 149 insertions(+) create mode 100644 docs/en/Community-Articles/2025-10-09-how-to-change-logo-in-angular-abp-apps/article.md diff --git a/docs/en/Community-Articles/2025-10-09-how-to-change-logo-in-angular-abp-apps/article.md b/docs/en/Community-Articles/2025-10-09-how-to-change-logo-in-angular-abp-apps/article.md new file mode 100644 index 0000000000..1f0128fa3d --- /dev/null +++ b/docs/en/Community-Articles/2025-10-09-how-to-change-logo-in-angular-abp-apps/article.md @@ -0,0 +1,149 @@ +# How to Change Logo in Angular ABP Applications + +## Introduction + +Logo application customization is one of the most common branding requirements in web applications. In ABP Framework's Angular applications, we found that developers were facing problems while they were trying to implement their application logos, especially on theme dependencies and flexibility. To overcome this, we moved the logo provider from `@volo/ngx-lepton-x.core` to `@abp/ng.theme.shared`, where it is more theme-independent and accessible. Here, we will describe our experience using this improvement and guide you on the new approach for logo configuration in ABP Angular applications. + +## Problem + +Previously, the logo configuration process in ABP Angular applications had several disadvantages: + +1. **Theme Dependency**: The `provideLogo` function was a part of the `@volo/ngx-lepton-x.core` package, so the developers had to depend on LeptonX theme packages even when they were using a different theme or wanted to extend the logo behavior. + +2. **Inflexibility**: The fact that the logo provider had to adhere to a specific theme package brought about an undesirable tight coupling of logo configuration and theme implementation. + +3. **Discoverability Issues**: Developers looking for logo configuration features would likely look in core ABP packages, but the provider was hidden in a theme-specific package, which made it harder to discover. + +4. **Migration Issues**: During theme changes or theme package updates, logo setting could get corrupted or require additional tuning. + +These made a basic operation like altering the application logo more challenging than it should be, especially for teams using custom themes or wanting to maintain theme independence. + +## Solution + +We moved the `provideLogo` function from `@volo/ngx-lepton-x.core` to `@abp/ng.theme.shared` package. This solution offers: + +- **Theme Independence**: Works with any ABP-compatible theme +- **Single Source of Truth**: Logo configuration is centralized in the environment file +- **Standard Approach**: Follows ABP's provider-based configuration pattern +- **Easy Migration**: Simple import path change for existing applications +- **Better Discoverability**: Located in a core ABP package where developers expect it + +This approach maintains ABP's philosophy of providing flexible, reusable solutions while reducing unnecessary dependencies. + +## Implementation + +Let's walk through how logo configuration works with the new approach. + +### Step 1: Configure Logo URL in Environment + +First, define your logo URL in the `environment.ts` file: + +```typescript +export const environment = { + production: false, + application: { + baseUrl: 'http://localhost:4200', + name: 'MyApplication', + logoUrl: 'https://your-domain.com/assets/logo.png', + }, + // ... other configurations +}; +``` + +The `logoUrl` property accepts any valid URL, allowing you to use: +- Absolute URLs (external images) +- Relative paths to assets folder (`/assets/logo.png`) +- Data URLs for embedded images +- CDN-hosted images + +### Step 2: Provide Logo Configuration + +In your `app.config.ts` (or `app.module.ts` for module-based apps), import and use the logo provider: + +```typescript +import { provideLogo, withEnvironmentOptions } from '@abp/ng.theme.shared'; +import { environment } from './environments/environment'; + +export const appConfig: ApplicationConfig = { + providers: [ + // ... other providers + provideLogo(withEnvironmentOptions(environment)), + ], +}; +``` + +**Important Note**: If you're migrating from an older version where the logo provider was in `@volo/ngx-lepton-x.core`, simply update the import statement: + +```typescript +// Old (before migration) +import { provideLogo, withEnvironmentOptions } from '@volo/ngx-lepton-x.core'; + +// New (current approach) +import { provideLogo, withEnvironmentOptions } from '@abp/ng.theme.shared'; +``` + +### How It Works Under the Hood + +The `provideLogo` function registers a logo configuration service that: +1. Reads the `logoUrl` from environment configuration +2. Provides it to theme components through Angular's dependency injection +3. Allows themes to access and render the logo consistently + +The `withEnvironmentOptions` helper extracts the relevant configuration from your environment object, ensuring type safety and proper configuration structure. + +### Example: Complete Configuration + +Here's a complete example showing both environment and provider configuration: + +**environment.ts:** +```typescript +export const environment = { + production: false, + application: { + baseUrl: 'http://localhost:4200', + name: 'E-Commerce Platform', + logoUrl: 'https://cdn.example.com/brand/logo-primary.svg', + }, + oAuthConfig: { + issuer: 'https://localhost:44305', + clientId: 'MyApp_App', + // ... other OAuth settings + }, + // ... other settings +}; +``` + +**app.config.ts:** +```typescript +import { ApplicationConfig } from '@angular/core'; +import { provideRouter } from '@angular/router'; +import { provideLogo, withEnvironmentOptions } from '@abp/ng.theme.shared'; +import { environment } from './environments/environment'; +import { routes } from './app.routes'; + +export const appConfig: ApplicationConfig = { + providers: [ + provideRouter(routes), + provideLogo(withEnvironmentOptions(environment)), + // ... other providers + ], +}; +``` + +### Benefits of This Approach + +1. **Separation of Concerns**: Logo configuration is separate from theme implementation +2. **Environment-Based**: Different logos for development, staging, and production +3. **Type Safety**: TypeScript ensures correct configuration structure +4. **Testing**: Easy to mock and test logo configuration +5. **Consistency**: Same logo appears across all theme components automatically + +## Conclusion + +In this article, we traversed how ABP Framework simplified logo configuration in Angular applications by moving the logo provider from `@volo/ngx-lepton-x.core` to `@abp/ng.theme.shared`. This removal of theme dependencies that are not necessary makes it easier to customize logos and theme-agnostic. + +The method we adopted allows developers to make their application logo customizable by simply defining the URL within the environment file and providing the configuration of the logo in their application configuration. This is an agile method that reduces complexity and improves discoverability. + +We implemented this improvement in the process of building ABP Framework to better the experience of developers and remove common areas of friction. Through releasing this solution publicly, we aim to make it easier for teams to make their ABP Angular applications uniform in branding, regardless of which theme they choose to use. + +If you have an older ABP version with logo configuration included in LeptonX packages, it is a simple import path migration to this new approach, so it's an easy update path for existing apps. \ No newline at end of file From e532c57f12b7650c9193f6a31fe59bb13c2b9c2b Mon Sep 17 00:00:00 2001 From: Fahri Gedik <53567152+fahrigedik@users.noreply.github.com> Date: Fri, 10 Oct 2025 14:37:06 +0300 Subject: [PATCH 2/2] Enhance logo customization with component replacement Added advanced customization options for logo component replacement in Angular ABP applications, including step-by-step instructions for implementation and a comparison with logo URL configuration. --- .../article.md | 148 +++++++++++++++++- 1 file changed, 144 insertions(+), 4 deletions(-) diff --git a/docs/en/Community-Articles/2025-10-09-how-to-change-logo-in-angular-abp-apps/article.md b/docs/en/Community-Articles/2025-10-09-how-to-change-logo-in-angular-abp-apps/article.md index 1f0128fa3d..59939beab1 100644 --- a/docs/en/Community-Articles/2025-10-09-how-to-change-logo-in-angular-abp-apps/article.md +++ b/docs/en/Community-Articles/2025-10-09-how-to-change-logo-in-angular-abp-apps/article.md @@ -130,6 +130,140 @@ export const appConfig: ApplicationConfig = { }; ``` +## Advanced: Logo Component Replacement + +For more advanced customization scenarios where you need complete control over the logo component's structure, styling, or behavior, ABP provides a component replacement mechanism. This approach allows you to replace the entire logo component with your custom implementation. + +### When to Use Component Replacement + +Consider using component replacement when: +- You need custom HTML structure around the logo +- You want to add interactive elements (e.g., dropdown menu, animations) +- You need to implement complex responsive behavior +- The simple `logoUrl` configuration doesn't meet your requirements + +### How to Replace the Logo Component + +#### Step 1: Generate a New Logo Component + +Run the following command in your Angular folder to create a new component: + +```bash +ng generate component custom-logo --inline-template --inline-style +``` + +#### Step 2: Implement Your Custom Logo + +Open the generated `custom-logo.component.ts` and implement your custom logo: + +```typescript +import { Component } from '@angular/core'; +import { RouterModule } from '@angular/router'; + +@Component({ + selector: 'app-custom-logo', + standalone: true, + imports: [RouterModule], + template: ` + + My Application Logo + + `, + styles: [` + .navbar-brand { + padding: 0.5rem 1rem; + } + + .navbar-brand img { + transition: opacity 0.3s ease; + } + + .navbar-brand:hover img { + opacity: 0.8; + } + `] +}) +export class CustomLogoComponent {} +``` + +#### Step 3: Register the Component Replacement + +Open your `app.config.ts` and register the component replacement: + +```typescript +import { ApplicationConfig } from '@angular/core'; +import { provideRouter } from '@angular/router'; +import { ReplaceableComponentsService } from '@abp/ng.core'; +import { eThemeBasicComponents } from '@abp/ng.theme.basic'; +import { CustomLogoComponent } from './custom-logo/custom-logo.component'; +import { environment } from './environments/environment'; +import { routes } from './app.routes'; + +export const appConfig: ApplicationConfig = { + providers: [ + provideRouter(routes), + // ... other providers + { + provide: 'APP_INITIALIZER', + useFactory: (replaceableComponents: ReplaceableComponentsService) => { + return () => { + replaceableComponents.add({ + component: CustomLogoComponent, + key: eThemeBasicComponents.Logo, + }); + }; + }, + deps: [ReplaceableComponentsService], + multi: true, + }, + ], +}; +``` + +Alternatively, if you're using a module-based application, you can register it in `app.component.ts`: + +```typescript +import { Component, OnInit } from '@angular/core'; +import { ReplaceableComponentsService } from '@abp/ng.core'; +import { eThemeBasicComponents } from '@abp/ng.theme.basic'; +import { CustomLogoComponent } from './custom-logo/custom-logo.component'; + +@Component({ + selector: 'app-root', + template: '', +}) +export class AppComponent implements OnInit { + constructor(private replaceableComponents: ReplaceableComponentsService) {} + + ngOnInit() { + this.replaceableComponents.add({ + component: CustomLogoComponent, + key: eThemeBasicComponents.Logo, + }); + } +} +``` + +### Component Replacement vs Logo URL Configuration + +Here's a comparison to help you choose the right approach: + +| Feature | Logo URL Configuration | Component Replacement | +|---------|------------------------|----------------------| +| **Simplicity** | Very simple, one-line configuration | Requires creating a new component | +| **Flexibility** | Limited to image URL | Full control over HTML/CSS/behavior | +| **Use Case** | Standard logo display | Complex customizations | +| **Maintenance** | Minimal | Requires component maintenance | +| **Migration** | Easy to change | Requires code changes | +| **Recommended For** | Most applications | Advanced customization needs | + +For most applications, the simple `logoUrl` configuration in the environment file is sufficient and recommended. Use component replacement only when you need advanced customization that goes beyond a simple image. + ### Benefits of This Approach 1. **Separation of Concerns**: Logo configuration is separate from theme implementation @@ -137,13 +271,19 @@ export const appConfig: ApplicationConfig = { 3. **Type Safety**: TypeScript ensures correct configuration structure 4. **Testing**: Easy to mock and test logo configuration 5. **Consistency**: Same logo appears across all theme components automatically +6. **Flexibility**: Choose between simple configuration or full component replacement based on your needs ## Conclusion -In this article, we traversed how ABP Framework simplified logo configuration in Angular applications by moving the logo provider from `@volo/ngx-lepton-x.core` to `@abp/ng.theme.shared`. This removal of theme dependencies that are not necessary makes it easier to customize logos and theme-agnostic. +In this article, we explored how ABP Framework simplified logo configuration in Angular applications by moving the logo provider from `@volo/ngx-lepton-x.core` to `@abp/ng.theme.shared`. This change eliminates unnecessary theme dependencies and makes logo customization more straightforward and theme-agnostic. + +The solution we implemented allows developers to configure their application logo simply by setting a URL in the environment file and providing the logo configuration in their application setup. For advanced scenarios requiring complete control over the logo component, ABP's component replacement mechanism provides a powerful alternative. This approach maintains flexibility while reducing complexity and improving discoverability. + +We developed this improvement while working on ABP Framework to enhance developer experience and reduce common friction points. By sharing this solution, we hope to help teams implement consistent branding across their ABP Angular applications more easily, regardless of which theme they choose to use. -The method we adopted allows developers to make their application logo customizable by simply defining the URL within the environment file and providing the configuration of the logo in their application configuration. This is an agile method that reduces complexity and improves discoverability. +If you're using an older version of ABP with logo configuration in LeptonX packages, migrating to this new approach requires only a simple import path change, making it a smooth upgrade path for existing applications. -We implemented this improvement in the process of building ABP Framework to better the experience of developers and remove common areas of friction. Through releasing this solution publicly, we aim to make it easier for teams to make their ABP Angular applications uniform in branding, regardless of which theme they choose to use. +## See Also -If you have an older ABP version with logo configuration included in LeptonX packages, it is a simple import path migration to this new approach, so it's an easy update path for existing apps. \ No newline at end of file +- [Component Replacement Documentation](https://abp.io/docs/latest/framework/ui/angular/component-replacement) +- [ABP Angular UI Customization Guide](https://abp.io/docs/latest/framework/ui/angular/customization)