Making a Component Theme-able

A component may be made theme-able by making slight alterations to it and creating a "wrapper" component that calls the theme support code.

The pattern of these changes has been revised since the original theme support in DSpace 7.  Don't be confused by older versions of the documentation.

Let us suppose that you are working on the "Thingamajig" component.

First:  edit the existing thingamajig.component.ts file.  In the @Component decorator, change the selector by inserting "-base".  In our case, the selector changes from "ds-thingamajig" to "ds-base-thingamajig".  The theme support code will look for this if there is no themed version of the component in the current theme.

Next:  create a new Typescript file in the same directory.  Name it themed-*.component.ts corresponding to the *.component.ts that you are working on.  It must extend themed.component, which must be imported.  In our example, name it themed-thingamajig.component.ts.

In its @Component decorator:

• Give it the original selector from the un-themed component, e.g. "ds-thingamajig".
• No need to provide a styleUrls or animations property, even if the un-themed components has one.
• Its templateUrl should be the relative path from the current directory to src/app/shared/theme-support/themed.component.  You will need to work out the number of ".." path elements from here to there.
• The imports array should include the name of the un-themed component (e.g. ThingamajigComponent) and there should be an import statement for it.

Your wrapper must expose three methods:

• getComponentName which returns the name of the un-themed component.
• importThemedComponent which returns the themed component (if any) for the current theme.
• importUnthemedComponent which returns the un-themed component.

In the case that your un-themed component contained any @Input() or @Output() decorators:

• Copy over all the @Input() properties on the wrapper component, but make sure to remove the default values
• Copy over all the @Output() properties on the wrapper component, these properties should all be initilized with new EventEmitter()
• In case the un-themed component had at least one @Input() or @Output(), override the inAndOutputNames array as well. This array should contain the names of all these properties

A complete wrapper example:

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

import { ThemedComponent } from '../../../shared/theme-support/themed.component';
import { ThingamajigComponent } from './thingamajig.component';

/**
 * Themed wrapper for {@link ThingamajigComponent}.
 */
@Component({
  selector: 'ds-thingamajig',
  templateUrl: '../../../shared/theme-support/themed.component.html',
  standalone: true,
  imports: [
    ThingamajigComponent,
  ],
})
export class ThemedThingamajigComponent extends ThemedComponent<ThingamajigComponent> {

  @Input() value: string;

  @Output() submitted: EventEmitter<void> = new EventEmitter();

  protected inAndOutputNames: (keyof CollectionDropdownComponent & keyof this)[] = [
    'value',
    'submitted', 
  ];

  protected getComponentName(): string {
    return 'ThingamajigComponent';
  }

  protected importThemedComponent(themeName: string): Promise<any> {
    return import(`../../../../themes/${themeName}/app/stuff/nonsense/things/thingamajig.component`);
  }

  protected importUnthemedComponent(): Promise<any> {
    return import('./thingamajig.component');
  }

}

Replace all the usages of the old un-themed component with the new themed wrapper component (for example in the *routes.ts files)

Finally add a themed override of this component in the custom theme. Take a look at the HeaderComponent if you need an example. Make sure to create matching html & scss files when you create the component, but leave these files empty and point the styleUrls & templateUrl to the files in src/app instead. This will ensure that the custom theme doesn't get out of sync while making it easy for other people to copy the folder to their custom theme.