Versions Compared

Old Version 35

changes.mady.by.user Mark H. Wood

Saved on

compared with

New Version 36

changes.mady.by.user Tim Donohue

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Better docs on starting from dspace vs custom theme

...

Running the UI in Developer Mode

Whenever you are making testing changes in the User Interface, you'll want may wish to see you changes "live" instead of rebuilding after each change.  The easiest way to achieve this is to run the User Interface locally (i.e. on localhost) in developer mode by running:

...

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.

...

  • 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, header & 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. 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 "arc/themes/amazingtheme", then the "bundleName" MUST be "amazingtheme-theme"

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

  5. 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.
  6. 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)
  7. 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"

  8. 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
    languageyml
    titleFormat 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
    titleFormat 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"

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


  10. 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, 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. 

    Code Block
    titlehome-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

...

Components in your Theme

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

...

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

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

Adding Component Directories to your Theme

If you come across an Angular Component which is NOT in your theme but want to customize it, you can add it into your theme directory.  This involves copying the component from the "Custom" theme over into your theme.

You can add/copy over a Component Directory as follows:

  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 theme.module.ts file.  Add an import of the new component file, or copy the corresponding import from "src/themes/custom/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 "theme.module.ts" file, also add this imported component to the "DECLARATIONS" section.  (Again, you can optionally look in "src/themes/custom/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. At this point, you should rebuild your theme 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.
  5. Now, you can customize your newly added Component by following the "Customizing Other Components in your Theme" instructions above.

Removing Component Directories from your Theme

While there is no harm in keeping extra, unmodified component directories in your theme, it can be beneficial to remove component directories which are unchanged.  The main advance to keeping your theme simple/small is that it can make future upgrades easier.  Generally speaking, the fewer components you have in your theme, the less likely your theme will need modification in a future upgrade (as generally your theme might require updates if one of the components in your theme had structural/larger changes). 

You can remove a Component directory as followsTo 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:

      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 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 your theme to verify nothing has broken.  If you did everything correctly, no build 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.

...