Using custom assets

Overview

The cdsSource directive is used to manage the image source based on the current theme and color palette. It allows the image to be dynamically changed as the theme or color palette changes, ensuring the correct image is displayed to the user.

Why use the cdsSource directive?

• Visual Consistency: Ensures that images match the current theme and color palette of the application.
• Flexibility: Allows dynamic image swapping without reloading the page.
• Maintenance: Simplifies the maintenance and updating of images by centralizing the image swapping logic in a single directive.

How to use the cdsSource directive

Step 1: Include the Module in angular.json

Ensure that the assets folder is included in the angular.json file. This allows the Angular application to access the images stored in the assets folder.

angular.json

  {
    "projects": {
      "your-project-name": {
        "architect": {
          "build": {
            "options": {
              "assets": [
                {
                  "glob": "**/*",
                  "input": "node_modules/@celerofinancas/ui-oauth/src/",
                  "output": "/"
                }
              ],
              "stylePreprocessorOptions": {
                "includePaths": [
                  "node_modules",
                  "node_modules/@celerofinancas/ui-theming/styles"
                ]
              }
            }
          }
        }
      }
    }
  }

Step 2: Import the Directive

Ensure that the SourceImageDirective is imported in the module where it will be used.

app.component.ts

import { SourceImageDirective } from '@celerofinancas/ui-directives';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
  imports: [SourceImageDirective]
})
export class AppComponent {
  // Component logic here
}

Step 3: Add the Directive to the Image

Use the cdsSource directive on the <img/> element and provide the image path.

app.component.html

<!-- Example usage of the cdsSource directive -->
<img [cdsSource]="'assets/shared/logo-white.svg'"  alt="Logo White">

Customizing the Directive

TOKEN SOURCE_IMAGE_DIRECTIVE_CONFIG

To customize the SourceImageDirective, you can inject the SOURCE_IMAGE_DIRECTIVE_CONFIG token in your module. This token is used to provide custom values to the component. If is not provided, the default values will be used.

Properties

Key	Description	Default
useThemeOnPath	Should the directive use the color theme	true
usePaletteOnPath	Should the directive use the palette	true
assetsUrl	Base URL for assets	''

The SOURCE_IMAGE_DIRECTIVE_CONFIG default values are:

{
  useThemeOnPath: true,
  usePaletteOnPath: true,
  assetsUrl: ''
}

Example

To customize the SourceImageDirective, you can inject the SOURCE_IMAGE_DIRECTIVE_CONFIG token in your module.

app.config.ts

import { ApplicationConfig } from '@angular/core';

import { FINANCIAL_RECORD_DETAILS_DOCUMENTS_CONFIGS } from '@celerofinancas/ui-reports';

export const appConfig: ApplicationConfig = {
  providers: [
    {
      provide: SOURCE_IMAGE_DIRECTIVE_CONFIG,
      useValue: {
        useThemeOnPath: false, // Disable theme usage
        usePaletteOnPath: true, // Enable palette usage
        assetsUrl: 'https://cdn.my-custom-assets-url.com' // Custom assets URL
      },
    },
  ],
};

Explanation

1. Assets Configuration: In the angular.json file, the path to the assets should include the directory where the images are stored. This ensures that the images are correctly loaded and accessible by the directive.
2. Import the Directive: The SourceImageDirective should be imported and exported in the UiDirectivesModule so it can be used in other components.
3. Using the Directive: The cdsSource directive is applied to the element, and the image path is provided as a value. The directive manages the image swapping based on the current theme and color palette.

Conclusion

By following these steps, the cdsSource directive will be configured and ready to use in the project, allowing efficient and dynamic management of images based on the theme and color palette.