Versions Compared

Old Version 1

changes.mady.by.user Tim Donohue

Saved on

compared with

New Version Current

changes.mady.by.user Tim Donohue

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  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. Below is an example for a theme named "my-theme":

    Code Block
    titlethemes/eager-themes.module.ts
    // COMMENT out the imports for any themes you are NOT using
//import { EagerThemeModule as DSpaceEagerThemeModule } from './dspace/eager-theme.module';
//import { EagerThemeModule as CustomEagerThemeModule } from './custom/eager-theme.module';

// Add a new import for your custom theme. Give its EagerThemeModule a unique name (e.g. "as [choose-a-unique-name]").
// Make sure the path points at its "eager-theme.module.ts" (see 'from' portion of the import statement).
// NOTE: You can import multiple themes if you plan to use multiple themes
import { EagerThemeModule as MyThemeEagerThemeModule } from './my-theme/eager-theme.module';

...
@NgModule({
  imports: [
    // Again, comment out any themes you are NOT using
    //DSpaceEagerThemeModule,
    //CustomEagerThemeModule,

    // Add your custom theme's EagerThemeModule to this list
    // NOTE: you can add multiple theme's to this list if you plan to use multiple themes.
    MyThemeEagerThemeModule,
  ],
})


  5. Enable your theme: Modify your config/config.*.yml configuration file, 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. 

    Format for 7.1 or 7.0 (environment.*.ts)
    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
    title
    // 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)
npm run 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. Edit your theme's existing app/navbar/navbar.component.html file. This file defines the entire <nav> which displays the navigation header across the entire DSpace site.  While much of the content in this <nav> is loaded dynamically via other Angular components, it is possible to easily add a hardcoded link to the existing header.  Find the section of this <nav> which is the <div idrole="collapsingNavmenubar">, as that's where you'll want to add your new link.  See inline comments in the example below.
     Code Block
    titlenavbar.component.html
    <nav>
...
   <!-- This DIV is where the <!-- The header links are added dynamically. 
        You should see it surrounding all linksembedded inunder the header if you view HTML source role="menubar" div tag -->
   <div idrole="collapsingNav" ... >
    <!-- The links themselves are in an unordered list (UL) --> 
    <ul menubar" class="navbar-nav" ... >   
       ...
       <!-- Add your new link at the end (or beginning) of this DIV ULtag in a new LIDIV tag -->
       <!-- NOTE: All classes used below are the same Bootstrap CSS classes used by our 'dspace' and 'custom' themes. 
            You can modify them if the link doesn't look correct in your theme. -->
       <li class="nav-item d-flex align-items-center">
      't look correct in your theme. -->
    <div class="ds-menu-item-wrapper text-md-center">
            <a<a role="menuitem" href="http://dspace.org" class="navds-menu-linkitem">DSpace.org</a>
          </div>
       </li>
    </ul>
   </div>
</nav>

  2. Obviously, you can also make additional modifications to the HTML of the header in this file, as necessary for your navigation header.  Keep in mind though that anything you remove may impact the dynamic content that is pulled into this navigation header. 
    1. An example is that the header logo for the "dspace" theme also exists in this same file. 
  3. Any changes require rebuilding your UI. If you are running in "dev mode" (npm run start:dev), then the UI will restart automatically whenever changes are detected.
...
  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. 
     Code Block
    titlefooter.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
     Code Block
    titlefooter.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'@if(showTopFooter)", which only shows that div when that variable is set to "true"
     Code Block
    titlefooter.component.html
    <footer class="text-lg-start">
   <!-- This div and everything within it only displays if showTopFooter=true -->
  <div *ngIf="showTopFooter"@if (showTopFooter) {
      <div 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" (npm run start:dev), then the UI will restart automatically whenever changes are detected.
...