Page History

...

Theme Directories & Design Principles

A theme's directory should include the following files and directories

• app/ contains the theme's Angular components and should mirror the structure of src/app/

• assets/ contains the theme's custom assets, such as fonts or images

• styles/ contains the theme's global styles

• eager-theme.module.ts declares the components that should be included in the app's main bundle, such as

  • Eager components are those that should be available immediately when first loading, such as the main parts of the homepage and components that are present on every page.

  • Entry components that are registered via a decorator such as @listableObjectComponent. These must also be included in the module's providers.

• lazy-theme.module.ts declares all the components of the theme.

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

...

1. Choose a theme to start from:  As documented above, there are two "src/theme/" directories provided out of the box: "custom" or "dspace".  You should select one to use as the basis for your theme.  Which you choose is up to you, but here are a few things to consider:
   1. DSpace Theme (src/themes/dspace): This is a simple, example theme for novice users.  Primarily, in this theme, you can immediately customize the CSS, header & homepage components. You can add other components as needed (see "Adding Component Directories to your Theme" below).
      1. Advantages: This theme is small and simple. It provides an easy starting point / example for basic themes.  Future User Interface upgrades (e.g. from 7.1 → 7.2) are likely to be easier because the theme is smaller in size.
      2. Disadvantages: It has very few component directories by default. But you can always add more.  See "Adding Component Directories to your Theme" below.
   2. Custom Theme (src/themes/custom): This theme provides all available theme-able components for more advanced or complex theming options. This provides you full control over everything that is theme-able in the User Interface
      1. Advantages: All theme-able components are provided in subdirectories. This makes it easier to modify the look and feel of any area of the User Interface.
      2. Disadvantages: After creating your theme, you may wish to remove any component directories that you didn't modify (see "Removing Component Directories from your Theme" below).  Generally speaking, upgrades (e.g. from 7.1 → 7.2) are often easier if your theme includes fewer components (as your theme may require updates if any component it references change significantly).
2. Create your own theme folder OR edit the existing theme folder: Either edit the theme directory in place, or copy it (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/

      Code Block
      "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 "src/themes/amazingtheme", then the "bundleName" MUST be "amazingtheme-theme"

4. Import the new theme's eager-theme.module.ts in themes/eager-themes.module.ts. If you're switching from one theme to another, remove the old theme from the imports.

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

   Code Block
   language yml title Format for 7.2 or above (config.*.yml)
   # In this example, we only show one theme enabled. It's possible to enable multiple (see below note) themes: - name: 'mydspacesite'

   
   

   
   

   Code Block
   title Format for 7.1 or 7.0 (environment.*.ts)
   // 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"

6. 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. 

   Code Block
   # Start in dev mode (which uses config.dev.yml) yarn start:dev

   
   

7. At this point, you can start making changes to your theme.  See the following sections for examples of how to make common changes.

...

1. First, copy the Angular Component directory in question from the "Custom" theme folder (src/themes/custom) into your theme's folder. NOTE: at this time, not all components are theme-able. So, if it doesn't exist in the "Custom" theme folder, then it may not be possible to theme.
   1. For example, if you wanted to add the Footer Component to your theme, it can be found in the "Custom" theme at "src/themes/custom/app/footer". 
   2. Copy that entire folder into your theme folder, retaining the same relative path.  For example, to add the Footer Component, copy "src/themes/custom/app/footer" (and all contents) into "src/themes/[your-theme]/app/footer".

2. Now, you need to "register" that folder in your theme's lazy-theme.module.ts file.  Add an import of the new component file, or copy the corresponding import from "src/themes/custom/lazy-theme.module.ts".  For example, the Footer Component import would look like this:

   Code Block
   import { FooterComponent } from './app/footer/footer.component';

   
   

3. In that same "lazy-theme.module.ts" file, also add this imported component to the "DECLARATIONS" section.  (Again, you can optionally look in "src/themes/custom/lazy-theme.module.ts" to see how its done).  For example, the Footer Component would then be added to the list of DECLARATIONS (the order of the declarations list doesn't matter):

   Code Block
   const DECLARATIONS = [ ....  FooterComponent, .... ];

   
   

4. Some components should also be included in the theme's eager-theme.module.ts

   • Eager components should be added to the DECLARATIONS array

   • Entry components should be added to the ENTRY_COMPONENTS array

5. At this point, you should rebuild/restart your UI to ensure nothing has broken.  If you did everything correctly, no build errors will occur.  Generally speaking, it's best to add Components one by one, rebuilding in between.
6. Now, you can customize your newly added Component by following the "Customizing Other Components in your Theme" instructions above.

...

1. First you MUST remove all references to that directory/component from your theme's lazy-theme.module.ts and eager-theme.module.ts file files. 

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

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

      Code Block
      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 lazy-theme.module.ts file. So, you'd also need to remove it from the DECLARATIONS section: 

      Code Block
      const DECLARATIONS = [ ....  LoginPageComponent, .... ];

      
      

2. Finally, delete the directory in question from your theme.
3. At this point, you should rebuild/restart your UI to verify nothing has broken.  If you did everything correctly, no build errors will occur.
   1. If you failed to edit your lazy-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 lazy-theme.module.ts similar to step 1 above.

...