Page History

...

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/

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

   Code Block
   // 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. 

   Code Block
   # 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 next two sections for examples of how to make common changes.

Global style/font/color scheme customizations

Changes to the global Bootstrap styles (Sass/CSS), font or color scheme 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.
2. Modifying the default font: 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:

      Code Block

      // 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:

         Code Block
         title 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 SCSS file and use it in the "$font-family-sans-serif" variable

         Code Block
         // 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.d 
   1. Again, you can use entirely Bootstrap variables to adjust color schemes.  See the Bootstrap Theming Colors documentation
   2. 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.