All Versions


DSpace Documentation


Page tree

Current Release

This documentation covers the latest release of DSpace, version 7.x. Looking for another version? See all documentation.

Skip to end of metadata
Go to start of metadata

Angular Overview

The DSpace User Interface (UI) is built on the Angular.io framework.  All data comes from the REST API (DSpace Backend), and the final HTML pages are generated via TypeScript.

Before getting started in customizing or branding the UI, there are some basic Angular concepts to be aware of.  You do not need to know Angular or TypeScript to theme or brand the UI. But, understanding a few basic concepts will allow you to better understand the folder structure / layout of the codebase.

Angular Components: In Angular, every webpage consists of a number of "components" which define the structure of a page.  They are the main "building block" of any Angular application. Components are reusable across many pages. So, for example, there's only one "header" and "footer" component, even though they appear across all pages.

Each Component has:

  • A *.component.ts (TypeScript) file which contains the logic & name ("selector") of the component
  • A *.component.html (HTML) file which contains the HTML markup for the component (and possibly references to other embedded components).  This is also called the "template".
    • In HTML files, components are named/referenced as HTML-like tags (e.g. <ds-header>, <ds-footer>). In DSpace's UI, every component starts with "ds-" in order to distinguish it as an out-of-the-box DSpace component. 
  • A *.component.scss (Sass / CSS) file which contains the style for the component.

If you want a deeper dive into Angular concepts of Components and Templates, see https://angular.io/guide/architecture-components

Theme Technologies

The DSpace UI uses:

  • Bootstrap (v4.x) website framework for general layout & webpage components (buttons, alerts, etc)
  • Sass, a CSS preprocessor, for stylesheets. Sass is very similar to CSS (an in fact, any CSS is valid Sass). But, Sass allows you to nest CSS rules & have variables and functions.  For a brief overview on Sass, see https://sass-lang.com/guide
  • HTML5, the latest specification of the HTML language

Familiarity with these technologies (or even just CSS + HTML) is all you need to do basic theming of the DSpace UI.

Running the UI in Developer Mode

Whenever you are making changes in the User Interface, you'll want to run the User Interface locally (i.e. on localhost) in developer mode by running:

yarn start:dev

This mode has several development-specific advantages:

  • UI starts more rapidly
  • UI will use a separate "environment.dev.ts" configuration file. This lets you have development specific configs, separate from your "environment.prod.ts" or the default "environment.common.ts"
  • UI will automatically reload anytime you modify a file.  Essentially the UI will constantly "watch" for changes (as you make them) & will reload anytime you modify a file.  This lets you find issues/bugs more rapidly and also test more rapidly.

Keep in mind, you should NEVER run the UI in developer mode in production scenarios.  Production mode (yarn start) provides much better performance and ensures your site fully supports SEO, etc.

Creating a Custom Theme

Theme Directories & Design Principles

Out of the box, there are three theming layers/directories to be aware of:

  • Base Theme (src/app/ directories):  The primary look & feel of DSpace (e.g. HTML layout, header/footer, etc) is defined by the HTML5 templates under this directory. Each HTML5 template is stored in a subdirectory named for the Angular component where that template is used. The base theme includes very limited styling (CSS, etc), based heavily on default Bootstrap (4.x) styling, and only allowing for minor tweaks to improve WCAG 2.1 AA accessibility.
  • Custom Theme (src/themes/custom directories): This directory acts as the scaffolding or template for creating a new custom theme.  It provides (empty) Angular components/templates which allow you to change the theme of individual components.  Since all files are empty by default, if you enable this theme (without modifying it), it will look identical to the Base Theme.
  • DSpace Theme (src/themes/dspace directories): This is the default theme for DSpace 7.  It's a very simple example theme providing a custom color scheme & homepage on top of the Base Theme. It's important to note that this theme ONLY provides custom CSS/images to override our Base Theme. All HTML5 templates are included at the Base Theme level, as this ensures those HTML5 templates are also available to the Custom Theme.

The DSpace UI design principles & technologies are described in more detail at DSpace UI Design principles and guidelines

Getting Started

  1. Start with the "custom" theme: The best place to start with a new theme is the "custom" theme folder (src/themes/custom). This folder contains the boilerplate code for all theme-able components. It's a scaffolding for a new theme which doesn't modify any of the "base theme" (src/app/ directories). This means that by default it's a plain Bootstrap look and feel, with a few tweaks for better accessibility.
  2. Create your own theme folder OR edit the "custom" theme: Either edit the "custom" theme directory, or copy the "custom" theme folder (and all its contents) into a new folder under src/themes/ (choose whatever folder name you want)
  3. Register your theme folder (only necessary if you create a new folder in previous step): Now, we need to make the UI aware of this new theme folder, before it can be used in configuration.
    1. Modify angular.json (in the root folder), adding your theme folder's main "theme.scss" file to the "styles" list.  The below example is for a new theme folder named src/themes/mydspacesite/

      "styles": [
        "src/styles/startup.scss",
        {
           "input": "src/styles/base-theme.scss",
           "inject": false,
           "bundleName": "base-theme"
        },
        ...
        {
           "input": "src/themes/mydspacesite/styles/theme.scss",
           "inject": false,
           "bundleName": "mydspacesite-theme"
        },
      ]

      NOTE: the "bundleName" for your custom them MUST use the format "${folder-name}-theme".  E.g. if the folder is named "arc/themes/amazingtheme", then the "bundleName" MUST be "amazingtheme-theme"

  4. Enable your theme: Modify your src/environments/environment.*.ts configuration file, adding your new theme to the "themes" array in that file.  Pay close attention to modify the correct environment file (e.g. modify environment.dev.ts if running in dev mode, or environment.prod.ts if running in prod mode).  We recommend starting in "dev mode" (environment.dev.ts) as this mode lets you see your changes immediately in a browser without a full rebuild of the UI – see next step. 

    // In this example, we only show one theme enabled. It's possible to enable multiple (see below note)
    themes: [
     {
        name: 'mydspacesite'
     },
    ]
    NOTE: The "name" used is the name of the theme's folder, so the example is for enabling a theme at src/themes/mydspacesite/ globally.  You should also comment out the default "dspace" theme, if you intend to replace it entirely.
    NOTE #2: You may also choose to enable multiple themes for your site, and even specify a different theme for different Communities, Collections, Items or URL paths. See User Interface Configuration for more details on "Theme Settings" in your environment.*.ts
  5. Verify your settings by starting the UI (ideally in Dev mode): At this point, you should verify the basic settings you've made all "work".  We recommend doing your theme work while running the UI in "dev mode", as the UI will auto-restart anytime you save a new change.  This will allow you to quickly see the impact of each change in your browser. 

    # Start in dev mode (which uses environment.dev.ts)
    yarn start:dev
  6. At this point, you can start making changes to your theme.  See the following sections for examples of how to make common changes.

Global style/font/color customizations

Changes to the global Bootstrap variables or styles will apply to all pages / Angular components across the entire site.

  1. Global style changes: All global style changes can be made in your theme's styles folder (e.g. src/themes/mydspacesite/styles). There are four main files in that folder:
    1. _theme_sass_variable_overrides.scss - May be used to override Bootstrap's default Sass variables.  This is the file you may wish to use for most  style changes. There are a large number of Bootstrap variables available which control everything from fonts, colors and the base style for all Bootstrap web components.  For a full list of Bootstrap variables you can override in this file, see the node_modules/bootstrap/scss/_variables.scss file (which is installed in your source directory when you run "yarn install"). More information may also be found in the Bootstrap Sass documentation at https://getbootstrap.com/docs/4.0/getting-started/theming/#sass
    2. _theme_css_variable_overrides.scss - May be used to override DSpace's default CSS variables. DSpace's UI uses CSS variables for all its components. These variables all start with "--ds-*", and are listed in src/styles/_custom_variables.scss. You can also use this file to add your own, custom CSS variables which you want to use for your theme.  If you create custom variables, avoid naming them with a "--ds-*" or a "--bs-*" prefix, as those are reserved for DSpace and Bootstrap variables.
    3. _global-styles.scss - May be used to modify the global CSS/SCSS for the site.  This file may be used to override the default global style contained in src/styles/_global-styles.scss .  Keep in mind, many styles can be more quickly changed by simply updating a variable in one of the above "*_variable_overrides.scss" files.  So, it's often easier to use those first, where possible.
    4. theme.scss - This just imports all the necessary Sass files to create the theme. It's unnecessary to modify directly, unless you with to add new Sass files to your theme.
  2. Modifying the default font:  By default, DSpace uses Bootstrap's "native font stack", which just uses system UI fonts. However, the font used in your site can be quickly updated via Bootstrap variables in your theme's _theme_sass_variable_overrides.scss file. 
    1. One option is to add a new import statement and modify the "$font-family-sans-serif" variable:

      // Import the font (from a URL)
      @import url('https://fonts.googleapis.com/css?family=Source+Sans+Pro');
      
      // Configure Bootstrap to use this font (and list a number of backup fonts to use on various systems)
      $font-family-sans-serif: 'Source Sans Pro', -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" !default;
    2. If your font requires installing local files, you can do the following
      1. Copy your font file(s) in your theme's assets/fonts/ folder
      2. Create a new ".scss" file specific to your font in that folder, e.g. assets/fonts/open-sans.scss, and use the "@font-face" CSS rule to load that font:

        open-sans.scss
        @font-face {
          font-family: "Open Sans";
          src: url("/assets/fonts/OpenSans-Regular-webfont.woff2") format("woff2"),
               url("/assets/fonts/OpenSans-Regular-webfont.woff") format("woff");
        }
      3. Then, import that new "open-sans.scss" file and use it in the "$font-family-sans-serif" variable

        // Import the font via the custom SCSS file
        @import '../assets/fonts/open-sans';
        
        // Configure Bootstrap to use this font (and list a number of backup fonts to use on various systems) 
        $font-family-sans-serif: 'Open Sans', -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol" !default;
    3. Keep in mind, as changing the font just requires adjusting Bootstrap Sass variables, there are a lot of Bootstrap guides out there that can help you make more advanced changes
  3. Modifying default color scheme: The colors used in your site can be quickly updated via Bootstrap variables in your theme's _theme_sass_variable_overrides.scss file. 
    1. Again, you can use entirely Bootstrap variables to adjust color schemes.  See the Bootstrap Theming Colors documentation
    2. A list of all Bootstrap color variables can be found in the node_modules/bootstrap/scss/_variables.scss file
    3. Additional examples can be found in the out-of-the-box "dspace" theme, which adjusts the default Bootstrap colors slightly for both accessibility & to match the DSpace logo.
  4. Any changes require rebuilding your UI. If you are running in "dev mode" (yarn start:dev), then the UI will restart automatically whenever changes are detected.

Customize Logo in Header

  1. Copy your logo to your theme's assets/image/ folder. Anything in this theme folder will be deployed to /assets/[theme-name]/images/ URL  path.
  2. Edit your theme's app/header/header.component.ts file. Swap the "templateUrl" property that your theme is using the local copy of "header.component.html"

    header.component.ts
    @Component({
      selector: 'ds-header',
      // styleUrls: ['header.component.scss'],
      styleUrls: ['../../../../app/header/header.component.scss'],
      // Uncomment the templateUrl which references the "header.component.html" file in your theme directory
      templateUrl: 'header.component.html',
      // Comment out the templateUrl which references the default "src/app/header/header.component.html" file.
      //templateUrl: '../../../../app/header/header.component.html',
    })
  3. Your theme's version of the header.component.html file will be empty by default. Copy over the default HTML code from src/app/header/header.component.html into your version of this file.
  4. Then, modify your copy of header.component.html to use your logo. In this example, we're assuming your theme name is "mytheme" and the logo file is named "my-logo.svg"

    <header>
      <div class="container">
        <div class="d-flex flex-row justify-content-between">
          <a class="navbar-brand my-2" routerLink="/home">
            <!-- Modify the logo on the next line -->
            <img src="/assets/mytheme/images/my-logo.svg" [attr.alt]="'menu.header.image.logo' | translate"/>
          </a>
          ...
    </header>
  5. Obviously, you can also make additional modifications to the HTML of the header in this file!  You'll also see that the header references several other DSpace UI components (e.g. <ds-search-navbar> is the search icon in the header). You can easily comment out these tags to disable them, or move them around to change where that component appears in the header.
  6. Any changes require rebuilding your UI. If you are running in "dev mode" (yarn start:dev), then the UI will restart automatically whenever changes are detected.

Customize Footer

  1. First, you'll want to decide if you want to modify just the footer's HTML, or the footer's styles (CSS/Sass), or both. 
    1. If you want to modify the HTML, you'll need to create a copy of "footer.component.html" in your theme, where you place your changes.
    2. If you want to modify the styles, you'll need to create a copy of "footer.component.scss" in your theme, where you place your changes.
  2. Edit your theme's app/footer/footer.component.ts file. Swap the "templateUrl" and "styleUrls" properties, based on which you want to modify in your theme. 

    footer.component.ts
    @Component({
      selector: 'ds-footer',
      // If you want to modify styles, then...
      // Uncomment the styleUrls which references the "footer.component.scss" file in your theme's directory
      // and comment out the one that references the default "src/app/footer/footer.component.scss"
      styleUrls: ['footer.component.scss'],
      //styleUrls: ['../../../../app/footer/footer.component.scss'],
      // If you want to modify HTML, then...
      // Uncomment the templateUrl which references the "footer.component.html" file in your theme's directory
      // and comment out the one that references the default "src/app/footer/footer.component.html"
      templateUrl: 'footer.component.html'
      //templateUrl: '../../../../app/footer/footer.component.html'
    })
  3. Now, based on what you want to modify, you will need to either update your theme's copy of footer.component.html or footer.component.scss or both.
    1. To change footer HTML: Your theme's version of the footer.component.html file will be empty by default. Copy over the default HTML code from src/app/footer/footer.component.html into your version of this file.
    2. To change footer Styles: Your theme's version of the footer.component.scss file will be empty by default. Copy over the default Sass code from src/app/footer/footer.component.scss into your version of this file.
  4. Modify the HTML or Sass as you see fit.
    1. If you want to add images, add them to your theme's assets/images folder.  Then reference them at the /assets/[theme-name]/images/ URL path.
    2. Keep in mind, all Bootstrap variables, utility classes & styles can be used in these files. Take advantage of Bootstrap when you can do so.
  5. DSpace also has a option to display a two-level footer, which is becoming more common these days.  By default. DSpace just displays a small, bottom footer.  But, you can enable a top footer (above that default footer) by add this line into your theme's footer.component.ts

    footer.component.ts
    export class FooterComponent extends BaseComponent {
       // This line will enable the top footer in your theme
       showTopFooter = true;
    }

    This top footer appears in the footer.component.html within a div.  Notice the "*ngIf='showTopFooter'", which only shows that div when that variable is set to "true"

    footer.component.html
    <footer class="text-lg-start">
      <!-- This div and everything within it only displays if showTopFooter=true -->
      <div *ngIf="showTopFooter" class="top-footer">
        ...
      </div>
      <!-- The bottom footer always displays -->
      <div class="bottom-footer ...">
        ...
      </div>
    </footer>
  6. Any changes require rebuilding your UI. If you are running in "dev mode" (yarn start:dev), then the UI will restart automatically whenever changes are detected.

Customize Home Page News

  1. First, you'll want to decide if you want to modify just the Home Page News HTML, or styles (CSS/Sass), or both. 
    1. If you want to modify the HTML, you'll need to create a copy of "home-news.component.html" in your theme, where you place your changes.
    2. If you want to modify the styles, you'll need to create a copy of "home-news.component.scss" in your theme, where you place your changes.
  2. Edit your theme's app/home-page/home-news/home-news.component.ts file. Swap the "templateUrl" and "styleUrls" properties, based on which you want to modify in your theme. 

    home-news.component.ts
    @Component({
      selector: 'ds-home-news',
      // If you want to modify styles, then...
      // Uncomment the styleUrls which references the "home-news.component.scss" file in your theme's directory
      // and comment out the one that references the default "src/app/home-page/home-news/home-news.component.scss"
      styleUrls: ['./home-news.component.scss'],
      //styleUrls: ['../../../../../app/home-page/home-news/home-news.component.scss'],
      // If you want to modify HTML, then...
      // Uncomment the templateUrl which references the "home-news.component.html" file in your theme's directory
      // and comment out the one that references the default "src/app/home-page/home-news/home-news.component.html"
      templateUrl: './home-news.component.html'
      //templateUrl: '../../../../../app/home-page/home-news/home-news.component.html'
    })
  3. Now, based on what you want to modify, you will need to either update your theme's copy of home-news.component.html or home-news.component.scss or both.
    1. To change HTML: Your theme's version of the home-news.component.html file will be empty by default. Copy over the default HTML code from src/app/home-page/home-news/home-news.component.html into your version of this file.
    2. To change Styles: Your theme's version of the home-news.component.scss file will be empty by default. Copy over the default Sass code from src/app/home-page/home-news/home-news.component.scss into your version of this file.
  4. Modify the HTML or Sass as you see fit.
    1. If you want to add images, add them to your theme's assets/images folder.  Then reference them at the /assets/[theme-name]/images/ URL path.
    2. Keep in mind, all Bootstrap variables, utility classes & styles can be used in these files. Take advantage of Bootstrap when you can do so.
  5. Any changes require rebuilding your UI. If you are running in "dev mode" (yarn start:dev), then the UI will restart automatically whenever changes are detected.

Customize other UI Components

By now, if you've followed this entire guide, you'll notice a pattern!  Customizing specific DSpace UI components requires just three steps:

  1. Configure your theme to use its copies of files: Modify the corresponding *.component.ts in your theme. 
    1. If you want to modify component style, replace the "styleUrls" in that file to point at the copy of *.component.scss in your theme.
    2. If you want to modify component HTML, replace the "template" in that file to point at the copy of *.component.html in your theme.
  2. Copy the default UI code into your theme file(s)
    1. If you want to modify component style, copy the default *.component.scss code (from src/app/) into your theme's component.scss file.
    2. If you want to modify component HTML, copy the default *.component.html code (from src/app/) into your theme's component.html file.
  3. Modify those theme-specific files  
    1. If you want to add images, add them to your theme's assets/images folder.  Then reference them at the /assets/[theme-name]/images/ URL path.
    2. Keep in mind, all Bootstrap variables, utility classes & styles can be used in these files. Take advantage of Bootstrap when you can do so.
  4. Remember to either rebuild the UI after each change, or run in dev mode (yarn start:dev) while you are doing theme work.

Customize UI labels using Internationalization (i18n) files

Much of the text (like headers and labels) displayed by the DSpace UI is captured in translation files to support the use of DSpace in multiple languages. This model of multi-language support is called internationalization (abbreviated i18n). The default set of these i18n files are stored in src/assets/i18n and named using the language code, so en.json5 is the English translation, fr.json5  is the French translation, etc.

If you would like to change the text displayed in the UI, you will need to edit the i18n translation files. For example, to change the label for the browse menu when viewing the UI in English (which defaults to "All of DSpace"), you would edit src/assets/i18n/en.json5 and change the value for menu.section.browse_global .

The following approach to capture i18n changes within a theme is only supported in DSpace 7.1 or above.

While editing the default i18n files directly is effective, the recommended approach is to capture i18n changes in your theme. This ensures that your changes to the default values are easy to find and review and also removes the risk of losing your changes when upgrading to newer versions of DSpace.

To capture i18n changes in your theme, you will need to:

  1. Create an i18n directory under src/themes/[theme-name]/assets
  2. For each language you would like to update, add a file to the new i18n directory following the naming scheme in the default i18n directory (en.json5 for English, fr.json5 for French, etc)
  3. In each translation file add only the settings that you wish to add or override

There is an example of this configuration in the custom theme, which you can find in src/themes/custom/assets/i18n

Once you have changes in place within your theme, they need to be applied by executing a script.

  1. In a terminal window, change to the /scripts directory

  2. Execute:

    yarn merge-i18n -s src/themes/[theme-name]/assets/i18n

The merge-i18n script will merge the changes captured in your theme with the default settings, resulting in updated versions of the default i18n files. Any setting you included in your theme will override the default setting. Any new properties will be added. Files will be merged based on file name, so en.json5 in your theme will be merged with the en.json5 file in the default i18n directory.

Extending other Themes

This is only supported in 7.1 and above

Themes can extend other themes using the "extends" configuration.  See User Interface Configuration for more examples.

Extending another theme means that you inherit all the settings of the extended theme.  So, if the current theme does NOT specify a component style, its ancestor theme(s) will be checked recursively for their styles before falling back to the default.  In other words, this "extends" setting allows for a theme to inherit all styles/components from the extended theme, and only override those styles/components you wish to override.

Here's a basic example:

'themes' section in environment.*.ts
{
    name: 'custom-A',
    extends: 'custom-B',
    handle: '10673/34',
},
{
    name: 'custom-B',
    extends: 'custom',
    handle: '10673/2',
},

In the above example:

  • When the object at Handle '10673/2' (and any child objects) is viewed, the 'custom-B' theme will be used.  By default, you'll have the same styles as the extended 'custom' theme.  However, you can override individual styles in your 'custom-B' theme.
  • When the object at Handle '10673/34' (and any child objects) is viewed, the 'custom-A' theme will be used. By default, your overall theme will be based on the 'custom' theme (in this case a "grandparent" theme).  But, you can override those styles in your 'custom-B' theme or 'custom-A' theme. 
    • The order of priority is 'custom-A', then 'custom-B', then 'custom'.  If a style/component is in 'custom-A' it will be used. If not, 'custom-B' will be checked and if it's there, that version will be used.  If not in either 'custom-A' or 'custom-B', then the style/component from 'custom' will be used.  If the style/component is not in ANY of those themes, then the default (base theme) style will be used.

Removing Subdirectories / Components from your Theme

Optionally, you may decide you want to keep your theme directory "simple" and only include components that you've modified. 

NOTE: It's NOT required to remove any directories out of your theme. For novice developers, it may be easier to simply keep all the directories, as it ensures they are always available, in case you wish to modify them at a later date.

To do so is a two step process:

  1. First you MUST remove all references to that directory/component from your theme's  theme.module.ts file. 
    1. For example, to delete the "./app/login-page" directory, you'd want to find which component(s) use that directory in your theme.module.ts file. 

    2. If you search that file, you'd fine this reference:

      import { LoginPageComponent } from './app/login-page/login-page.component';
    3. That means you not only need to remove that "import" statement.  You'd also need to remove all other references to "LoginPageComponent" in that same theme.module.ts file. So, you'd also need to remove it from the DECLARATIONS section: 

      const DECLARATIONS = [ 
        ....   
        LoginPageComponent, 
        ....
      ];
  2. Finally, delete the directory in question from your theme.
  3. At this point, you should rebuild your theme to verify nothing has broken.  If you did everything correctly, no errors will occur.
    1. If you failed to edit your theme.module.ts correctly, you may see "Cannot find module [path-to-module]" errors which reference the directories that Angular/Node can no longer find in your theme.  Either restore those directories, or remove the reference(s) from the theme.module.ts similar to step 1 above.


Additional Theming Resources

  • No labels

2 Comments

  1. If you need to custom Entities components, there is currently a way to achieve it. Unlike basic and themed components, the "trick" here is to reference your component as an Entry Component. I think it is related with the way entity components list works. This part of the  code might be refactored in a subsequent release, so this is kind of a temporary solution.

    Imagine that you want to override the default Project item page component.

    First you are required to edit file with the entry components:
    /dspace/dspace-angular/src/themes/themed-entry-component.module.ts


    and add your custom theme mydspacesite:

    /dspace/dspace-angular/src/themes/themed-entry-component.module.ts
    import { ENTRY_COMPONENTS as MYDSPACESITE } from './mydspacesite/entry-components';const ENTRY_COMPONENTS = [
    ...CUSTOM,
    ...MYDSPACESITE,
    ];


    then, at your theme you need to specify which are the entry components:
    /dspace/dspace-angular/src/themes/mydspacesite/entry-components.ts


    /dspace/dspace-angular/src/themes/mydspacesite/entry-components.ts
    import { ProjectComponent } from './app/+item-page/simple/item-types/project/project.component';
    
    export const ENTRY_COMPONENTS = [
      ProjectComponent,
    ];


    and you need to create the required component in the the destination folder - /dspace/dspace-angular/src/themes/mydspacesite/app/+item-page/simple/item-types/project/ .

    You will have a typical component structure with the .ts, the .scss and the .html file.

    Your /dspace/dspace-angular/src/themes/mydspacesite/app/+item-page/simple/item-types/project/project.component.ts
    If you just want to use the same features as the default component and just want to edit the html part, the content of this file will be something like this:

    /dspace/dspace-angular/src/themes/mydspacesite/app/+item-page/simple/item-types/project/project.component.ts
    import { ChangeDetectionStrategy, Component } from '@angular/core';
    import { ViewMode } from '../../../../../../../app/core/shared/view-mode.model';
    import { listableObjectComponent } from '../../../../../../../app/shared/object-collection/shared/listable-object/listable-object.decorator';
    import { Context } from '../../../../../../../app/core/shared/context.model';
    import { ProjectComponent as BaseComponent } from '../../../../../../../app/entity-groups/research-entities/item-pages/project/project.component';
    
    @listableObjectComponent('Project', ViewMode.StandalonePage, Context.Any, 'mydspacesite')
    
    @Component({
    selector: 'ds-project',
      // styleUrls: ['./project.component.scss'],
      styleUrls: ['../../../../../../../app/entity-groups/research-entities/item-pages/project/project.component.scss'],
      templateUrl: './project.component.html',
      // templateUrl: ['../../../../../../../app/entity-groups/research-entities/item-pages/project/project.component.html'],
      changeDetection: ChangeDetectionStrategy.OnPush
    })
    
    /**
    * The component for displaying metadata and relations of an item of the type Project
    */
    export class ProjectComponent extends BaseComponent {
    }

    One important aspect is that you are required to use the annotation @listableObjectComponent for your custom component - mydspacesite:

    /dspace/dspace-angular/src/themes/mydspacesite/app/+item-page/simple/item-types/project/project.component.ts
    @listableObjectComponent('Project', ViewMode.StandalonePage, Context.Any, 'mydspacesite')


    You can custom your project.component.html:

    /dspace/dspace-angular/src/themes/mydspacesite/app/+item-page/simple/item-types/project/project.component.html
    <div class="d-flex flex-row">
      <h2 class="item-page-title-field mr-auto">
        {{'project.page.titleprefix' | translate}}<ds-metadata-values [mdValues]="object?.allMetadata(['dc.title'])"></ds-metadata-values>
      </h2>
      <div class="pl-2">
        <ds-dso-page-edit-button [pageRoute]="itemPageRoute" [dso]="object" [tooltipMsg]="'project.page.edit'"></ds-dso-page-edit-button>
      </div>
    </div>
    
    (...)


    then, the last step is to add your component to the theme theme.module.ts file:

    /dspace/dspace-angular/src/themes/mydspacesite/theme.module.ts
    (...)
    
    import { MyDSpacePageModule } from '../../app/+my-dspace-page/my-dspace-page.module';
    import { ProjectComponent } from './app/+item-page/simple/item-types/project/project.component';
    import { PublicationComponent } from './app/+item-page/simple/item-types/publication/publication.component';
    
    (...)
    
    const DECLARATIONS = [
      ProjectComponent,
      PublicationComponent,
      HomeNewsComponent,
    
    (...)


    Kudos for Art Lowel (Atmire) for helping out with this!
  2. The following was provided by Art Lowel (Atmire) in slack. - I've copied it here to ensure it persists.

    Only the components you find in the custom theme folder are themeable out of the box. (This is ignoring the ones  with @listableObject or @metadataRepresentationComponent decorators, as they are themeable using a different mechanism)

    The reason for this is that every component we want to make themeable can’t just be referenced by name somewhere else as that would be a hard link to one specific theme.
    Instead we need to replace it with a component with the logic to determine which, if any themed version of the original component should be loaded.

    Because we didn’t have the time replace every single component with a themeable counterpart, we decided to focus on the basics: e.g. nearly every page component is themeable out of the box, that way, even if you can’t theme some specific component that’s part of the page, you can theme the page, and inside, use a hard reference to something else.

    Is it even possible to customize the components that haven’t been included in the “custom” theme?

    Yes, anything can be customized. If you don’t need different versions of the component you want to customize for different themes, you can simply modify the original component file. Granted, that will make it slightly more trouble if you upgrade to a newer version of DSpace later, but usually it’s not that big a problem.

    If you do need different themed versions of the same component, or you want to ensure that all your customizations are kept in the theme folder, you can make that component themeable. You can find plenty of examples on how to do so in #1042. It boils down to:

    • In the same folder as the original component create a component called Themed${Original Component Name} that extends ThemedComponent Example
    • Use a selector called ds-themed${orignal selector} Example
    • Use the original themed.component.html file as the templateUrl. Example
    • Implement getComponentName() by returning the name of the original component as a string: Example
    • Implement importUnthemedComponent() by returning an import() call for the original component. Use a relative path. This tells us where to find the file in case no themed version was found. Example
    • Implement importThemedComponent() by returning an import() call for themed versions of the component. This should be a relative path to where themed versions of that component would be located. Use the themeName variable in lieu of the actual name. Example
    • Optionally, if the original component had in or outputs, override inAndOutputNames, and provide an array of the names of those in and outputs as strings. This is necessary to connect up the wires after the dynamic component has loaded. e.g. ['shouldShowRouteLoader', 'shouldShowFullscreenLoader'], which refers to these inputs on RootComponent
    • Replace any existing reference to the original component with a reference to the themed version: e.g. swap <ds-root> with <ds-themed-root> in app.component.html
    • In the custom theme folder, create a component with the same name as the original component, in the same relative position. Example
    • Import the original component as BaseComponent. Example
    • Extend BaseComponent. Example
    • And comment out the styleUrls and templateUrl and replace them with references to the originals
    • Finally add the new component to the DECLARATIONS array in the theme module

    If you do go down the route of making additional components themeable, we’d appreciate it if you contribute them, even if it’s only one component at a time. That way, the next person that needs it doesn’t have to go through the trouble of doing it themselves.