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.

Creating a Custom Theme

Theme Directories & Configuration

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.

More information on the UI Design principles/technologies can be found at DSpace UI Design principles and guidelines

The theming configuration can be found in the src/environments/environment.*.ts.  See User Interface Configuration.

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 file (e.g. modify environment.dev.ts if running in dev mode, or environment.prod.ts if running in prod mode).  The "name" used is the name of the theme's folder, so the below 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.

   // In this example, we only show one theme enabled. It's possible to enable multiple (see below note)
   themes: [
    {
       name: 'mydspacesite'
    },
   ]

   NOTE: You can 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".