All Versions
- DSpace 7.x (Current Release)
- DSpace 8.x (Unreleased)
- DSpace 6.x (EOL)
- DSpace 5.x (EOL)
- More Versions...
Contribute to the DSpace Development Fund
The newly established DSpace Development Fund supports the development of new features prioritized by DSpace Governance. For a list of planned features see the fund wiki page.
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:
*.component.ts
(TypeScript) file which contains the logic & name ("selector") of the component*.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".<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. *.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
The DSpace UI uses:
Familiarity with these technologies (or even just CSS + HTML) is all you need to do basic theming of the DSpace UI.
Whenever you are testing changes in the User Interface, 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:
yarn start:dev
This mode has several development-specific advantages:
Keep in mind, you should NEVER run the UI in developer mode in production scenarios. Production mode provides much better performance and ensures your site fully supports SEO, etc.
A theme's directory should include the following files and directories
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.
that are registered via a decorator such as @listableObjectComponent
. These must also be included in the module's providers
.
lazy-theme.module.ts
Out of the box, there are three theming layers/directories to be aware of:
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.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.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
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).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 Interfacesrc/themes/
(choose whatever folder name you want)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 "src/themes/amazingtheme", then the "bundleName" MUST be "amazingtheme-theme"
eager-theme.module.ts
in themes/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, ], })
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.
# In this example, we only show one theme enabled. It's possible to enable multiple (see below note) themes: - name: 'mydspacesite'
// In this example, we only show one theme enabled. It's possible to enable multiple (see below note) themes: [ { name: 'mydspacesite' }, ]
src/themes/mydspacesite/
globally. You should also comment out the default "dspace" theme, if you intend to replace it entirely.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.
# Start in dev mode (which uses config.dev.yml) yarn start:dev
Changes to the global Bootstrap variables or styles will apply to all pages / Angular components across the entire site.
styles
folder (e.g. src/themes/mydspacesite/styles
). There are four main files in that folder:_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_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._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.theme.scss
- This just imports all the necessary Sass files to create the theme. It's unnecessary to modify directly, unless you with to add new Sass files to your theme._theme_sass_variable_overrides.scss
file. One option is to add a new import statement and modify the "$font-family-sans-serif" variable:
// 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;
assets/fonts/
folderCreate 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:
@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"); }
Then, import that new "open-sans.scss" file and use it in the "$font-family-sans-serif" variable
// 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;
_theme_sass_variable_overrides.scss
file. node_modules/bootstrap/scss/_variables.scss
fileCSS custom properties vs. SASS variables
Support for theme switching at runtime requires that components use CSS custom properties (which vary at runtime) rather than SASS variables (which are fixed at build time). Thus, SASS variables will be undefined in individual components' stylesheets. The Bootstrap SASS variables are mapped to CSS properties for use in these places. For example, $red
is mapped to --bs-red
and may be referenced as var("--bs-red")
.
assets/images/
folder. Anything in this theme folder will be deployed to /assets/[theme-name]/images/
URL path.Edit your theme's app/header/header.component.ts
file. Swap the "templateUrl" property that your theme is using the local copy of "header.component.html"
@Component({ selector: 'ds-header', // styleUrls: ['header.component.scss'], styleUrls: ['../../../../app/header/header.component.scss'], // Uncomment the templateUrl which references the "header.component.html" file in your theme directory templateUrl: 'header.component.html', // Comment out the templateUrl which references the default "src/app/header/header.component.html" file. //templateUrl: '../../../../app/header/header.component.html', })
header.component.html
file will be empty by default. Copy over the default HTML code from src/app/header/header.component.html
into your version of this file.Then, modify your copy of header.component.html to use your logo. In this example, we're assuming your theme name is "mytheme" and the logo file is named "my-logo.svg"
<header> <div class="container"> <div class="d-flex flex-row justify-content-between"> <a class="navbar-brand my-2" routerLink="/home"> <!-- Modify the logo on the next line --> <img src="/assets/mytheme/images/my-logo.svg" [attr.alt]="'menu.header.image.logo' | translate"/> </a> ... </header>
<ds-search-navbar>
is the search icon in the header). You can easily comment out these tags to disable them, or move them around to change where that component appears in the header.src/app/navbar/navbar.component.html
) is used everywhere else. The Navbar component can be customized in the same way as the Header Component. Just edit the logo path in the "navbar.component.html".This provides a basic example of adding in a hardcoded link to the header menu (displayed on every page in DSpace).
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 id="collapsingNav">, as that's where you'll want to add your new link. See inline comments in the example below.
<nav> ... <!-- This DIV is where the header links are added dynamically. You should see it surrounding all links in the header if you view HTML source --> <div id="collapsingNav" ... > <!-- The links themselves are in an unordered list (UL) --> <ul class="navbar-nav" ... > ... <!-- Add your new link at the end (or beginning) of this UL in a new LI 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"> <div class="text-md-center"> <a href="http://dspace.org" class="nav-link">DSpace.org</a> </div> </li> </ul> </div> </nav>
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.
@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' })
footer.component.html
or footer.component.scss
or both.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.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.assets/images
folder. Then reference them at the /assets/[theme-name]/images/
URL path.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
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'
", which only shows that div when that variable is set to "true"
<footer class="text-lg-start"> <!-- This div and everything within it only displays if showTopFooter=true --> <div *ngIf="showTopFooter" class="top-footer"> ... </div> <!-- The bottom footer always displays --> <div class="bottom-footer ..."> ... </div> </footer>
Available in 7.2 or above. In 7.1 or 7.0, the only way to change the favicon is to modify the src/assets/images/favicon.ico
file.
Each theme has the ability to add a set of (attribute-only) HTML tags in the <head>
section of the page. This is useful for example to change the favicon based on the active theme. Whenever the theme changes, the head tags are reset. A theme can inherit head tags from the parent theme only if it doesn't have any head tags itself. (E.g. theme B extends theme A; if theme B does not have head tags, the head tags of theme A will be used (if any). However, if theme B does have head tags, only the tags from theme B will be used.) If none of the themes in the inheritance hierarchy have head tags configured, the head tags of the default theme (if any) will be used.
Note that a simple hardcoded favicon is set in case no head tags are currently active. The hardcoded favicon is stored at src/assets/images/favicon.ico
. This implies that if head tags are added to a theme, the favicon should also be configured explicitly for that theme, else the behavior is undefined.
In the "themes" section of your config/config.*.yml
configuration file, add (one or more) "headTags", pointing at the favicon file you want to use. For example:
themes: # The default dspace theme - name: dspace # Whenever this theme is active, the following tags will be injected into the <head> of the page. # Example use case: set the favicon based on the active theme. headTags: # Insert <link rel="icon" href="assets/dspace/images/favicons/favicon.ico" sizes="any"/> into the <head> of the page. - tagName: link attributes: rel: icon href: assets/dspace/images/favicons/favicon.ico sizes: any # Insert <link rel="icon" href="assets/dspace/images/favicons/favicon.svg" type="image/svg+xml"/> into the <head> of the page. - tagName: link attributes: rel: icon href: assets/dspace/images/favicons/favicon.svg type: image/svg+xml # Insert <link rel="apple-touch-icon" href="assets/dspace/images/favicons/apple-touch-icon.png"/> into the <head> of the page. - tagName: link attributes: rel: apple-touch-icon href: assets/dspace/images/favicons/apple-touch-icon.png # Insert <link rel="manifest" href="assets/dspace/images/favicons/manifest.webmanifest"/> into the <head> of the page. - tagName: link attributes: rel: manifest href: assets/dspace/images/favicons/manifest.webmanifest
headTags
section.The primary Home page content is all included in the source code under "src/app/home-page". The News section is specifically under "src/app/home-page/home-news".
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.
@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' })
home-news.component.html
or home-news.component.scss
or both.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.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.assets/images
folder. Then reference them at the /assets/[theme-name]/images/
URL path.The "simple" Item page is the default display for an Item (when you visit any item via a URL like [dspace.ui.url]/items/[uuid]). If you want to modify the metadata fields displayed on that page by default, that can be done quite easily.
src/app/item-page/simple/item-types/untyped-item/
" src/app/item-page/simple/item-types/publication/
"Here's the basics of modifying this page. The below examples assume you are working with a normal Item. But the same logic would work for modifying the Publication pages (you'd just need to modify it's HTML/CSS instead)
src/app/item-page/simple/item-types/untyped-item/untyped-item.component.html
" in your theme. This is where you place your changes.src/app/item-page/simple/item-types/untyped-item/untyped-item.component.scss
" in your theme. This is where you place your changes.Edit your theme's app/item-page/simple/item-types/untyped-item/untyped-item.component.ts
file. Swap the "templateUrl" and "styleUrls" properties, based on which you want to modify in your theme. Also, MAKE SURE the "@listableObjectComponent" is using your theme... the last parameter should be the name of your theme!
// MAKE SURE that the final parameter here is the name of your theme. This one assumes your theme is named "custom". @listableObjectComponent(Item, ViewMode.StandalonePage, Context.Any, 'custom') @Component({ selector: 'ds-untyped-item', // If you want to modify styles, then... // Uncomment the styleUrls which references the "untyped-item.component.scss" file in your theme's directory // and comment out the one that references the default in "src/app/" styleUrls: ['./untyped-item.component.scss'], //styleUrls: ['../../../../../../../app/item-page/simple/item-types/untyped-item/untyped-item.component.scss'], // If you want to modify HTML, then... // Uncomment the templateUrl which references the "untyped-item.component.html" file in your theme's directory // and comment out the one that references the default "src/app/" templateUrl: './untyped-item.component.html', //templateUrl: '../../../../../../../app/item-page/simple/item-types/untyped-item/untyped-item.component.html', })
untyped-item.component.html
or untyped-item.component.scss
or both.untyped-item
.component.html
file may be empty by default. Copy over the default HTML code from src/item-page/simple/item-types/untyped-item/untyped-item.component.html
into your version of this file.untyped-item
.component.scss
file may be empty by default. Copy over the default Sass code from src/item-page/simple/item-types/untyped-item/untyped-item.component
.scss
into your version of this file<ds-generic-item-page-field>
- This tag can be used to display the value of any metadata field (as a string). src/assets/i18n/en.json5
" file (or corresponding file depending on your language)<ds-item-page-uri-field>
- This tag can be used to display the value of any metadata field as an HTML link. (The value must already be a URL)<ds-generic-item-page-field>
above.<ds-item-page-date-field>
and <ds-item-page-abstract-field>
). These are currently separate components under "src/app/item-page/simple/field-components/specific-field/
" directories. They are hardcoded to use a specific metadata field and label, but you could customize the components in that location.NOTE: If your changes to the simple item page don't appear to be working, make sure that you have updated the eager-theme.module.ts
to load your custom theme as described in the "Getting Started" section above! This small change is REQUIRED for the untyped-item component to work in a custom theme. You also may wish to restart your dev server to ensure nothing is being cached.
By now, if you've followed this entire guide, you'll notice a pattern! Customizing specific DSpace UI components requires just three steps:
*.component.ts
in your theme. *.component.scss
in your theme.*.component.html
in your theme.*.component.scss
code (from src/app/
) into your theme's component.scss
file.*.component.html
code (from src/app/
) into your theme's component.html
file.assets/images
folder. Then reference them at the /assets/[theme-name]/images/
URL path.Much of the text (like headers and labels) displayed by the DSpace UI is captured in translation (language pack) files to support the use of DSpace in multiple languages. This model of multi-language support is called internationalization (abbreviated i18n). The default set of these i18n files are stored in src/assets/i18n
and named using the language code, so en.json5
is the English translation, fr.json5
is the French translation, etc. In each of these files, a set of "keys" is mapped to text in the given language.
If you would like to change the text displayed in the UI, you will need to edit the i18n translation files. There are two approaches you can take:
src/assets/i18n/*.json5
file(s) directlysrc/assets/i18n/en.json5
and change the value for menu.section.browse_global
.src/assets/i18n/
files. However, a specific setup is necessary, see the "Theme override approach" instructions below.Theme override approach
The following "theme override" approach to capture i18n changes within a theme is only supported in DSpace 7.1 or above.
While editing the default i18n files directly is effective, the recommended approach is to capture i18n changes in your theme. This ensures that your changes to the default values are easy to find and review and also removes the risk of losing your changes when upgrading to newer versions of DSpace.
To capture i18n changes in your theme, you will need to:
src/themes/[theme-name]/assets
There is an example of this configuration in the custom theme, which you can find in src/themes/custom/assets/i18n
.
Once you have changes in place within your theme, they need to be applied by executing a script:
yarn merge-i18n -s src/themes/[theme-name]/assets/i18n
The merge-i18n
script will merge the changes captured in your theme with the default settings, resulting in updated versions of the default i18n files. Any setting you included in your theme will override the default setting. Any new properties will be added. Files will be merged based on file name, so en.json5 in your theme will be merged with the en.json5 file in the default i18n directory.
This is only supported in 7.1 and above
Themes can extend other themes using the "extends" configuration. See User Interface Configuration for more examples.
Extending another theme means that you inherit all the settings of the extended theme. So, if the current theme does NOT specify a component style, its ancestor theme(s) will be checked recursively for their styles before falling back to the default. In other words, this "extends" setting allows for a theme to inherit all styles/components from the extended theme, and only override those styles/components you wish to override.
Here's a basic example:
themes: # grandchild theme - name: custom-A extends: custom-B handle: '10673/34' # child theme - name: custom-B extends: custom handle: 10673/2 # default theme - name: custom
themes: [ // grandchild theme { name: 'custom-A', extends: 'custom-B', handle: '10673/34', }, // child theme { name: 'custom-B', extends: 'custom', handle: '10673/2', }, // default theme { name: 'custom', }, ],
In the above examples:
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:
Now, you need to "register" that component in one of your theme's module files: lazy-theme.module.ts or eager-theme.module.ts. For performance it's best to put as many components into lazy-theme.module.ts as that means they'll only be downloaded if they're needed. Components in eager-theme.module.ts are included in the initial JS download for the app, so you should only add components there that are necessary on every page, such as the header and footer, these DECLARATIONS
array. You should also include components using one of our custom decorators (such as @listableObjectComponent), because those decorators need to be registered when the app starts to be able to be picked up. These ENTRY_COMPONENTS
array, which will both declare them as well as ensure they're loaded when the app starts.
Add an import of the new component file, or copy the corresponding import from "src/themes/custom/lazy-theme.module.ts" or "src/themes/custom/eager-theme.module.ts". For example, the Footer Component import can be found in "src/themes/custom/eager-theme.module.ts" and looks like this:
import { FooterComponent } from './app/footer/footer.component';
In that same module file, also add this imported component to the "DECLARATIONS" section. (Again, you can optionally look in the custom theme's module files 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):
const DECLARATIONS = [ .... FooterComponent, .... ];
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 advantage 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 may require updates if one of the components it references underwent structural/major changes).
You can remove a Component directory as follows:
lazy-theme.module.ts
eager-theme.module.ts
. 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.
If you search that file, you'd fine this reference:
import { LoginPageComponent } from './app/login-page/login-page.component';
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:
const DECLARATIONS = [ .... LoginPageComponent, .... ];
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.While you are working on themes, sometimes you may discover that it's difficult to tell which theme is being used to generate specific HTML elements. Luckily, there's an easy way to determine which theme is used on every HTML element.
Simply view the HTML source of the page, and look for the "data-used-theme" attribute. This attribute will tell you which named theme matched that HTML element. By default, a name of "base" references the core or "base" code ( under ./src/app) was used.
For example:
<!-- This example shows the theme named "dspace" was used for the "themed-header-navbar-wrapper.component.ts" --> <ds-themed-header-navbar-wrapper ... data-used-theme="dspace"></ds-themed-header-navabar-wrapper> <main> <!-- But, on the same page, the theme named "base" (core code) was used for the "themed-breadcrumbs.component.ts" --> <ds-themed-breadcrumbs ... data-used-theme="base"></ds-themed-breadcrumbs> </main>
Every DSpace Angular component has a corresponding <ds-*>
HTML-like tag. The HTML tag is called the "selector" (or CSS selector), and it is defined in the "*.component.ts" tag using the "@Component" decorator (see Angular's Component Overview for the basics). The key point to remember is that if you can find the "<ds-* >" tag, then it is easy to determine which component generated that tag!
So, supposing you are trying to determine which component is generating part of a DSpace page.
Continuing the example, if you view the source of the "Communities in DSpace" heading, you'll see something like this (all HTML attributes have been removed to make the example simplier):
<ds-top-level-community-list> <div> <h2> Communities in DSpace </h2> <p>Select a community to browse its collections.</p> </div> </ds-top-level-community-list>
Continuing the example, if you search the ./src/app/
directories for "ds-top-level-community-list" you'll find a match in the "src/app/home-page/top-level-community-list/top-level-community-list.component.ts
" file:
@Component({ selector: 'ds-top-level-community-list', ... })
top-level-community-list.component.ts
" file or it's corresponding HTML file at "top-level-community-list.component.html
"
2 Comments
Paulo Graça
If you need to custom Entities components, there is currently a way to achieve it. Unlike basic and themed components, the "trick" here is to reference your component as an Entry Component. I think it is related with the way entity components list works. This part of the code might be refactored in a subsequent release, so this is kind of a temporary solution.
Imagine that you want to override the default Project item page component.
First you are required to edit file with the entry components:
/dspace/dspace-angular/src/themes/themed-entry-component.module.ts
and add your custom theme mydspacesite:
then, at your theme you need to specify which are the entry components:
/dspace/dspace-angular/src/themes/mydspacesite/entry-components.ts
and you need to create the required component in the the destination folder - /dspace/dspace-angular/src/themes/mydspacesite/app/+item-page/simple/item-types/project/ .
You will have a typical component structure with the .ts, the .scss and the .html file.
Your /dspace/dspace-angular/src/themes/mydspacesite/app/+item-page/simple/item-types/project/project.component.ts
If you just want to use the same features as the default component and just want to edit the html part, the content of this file will be something like this:
Bill Branan
The following was provided by Art Lowel (Atmire) in slack. - I've copied it here to ensure it persists.
Only the components you find in the custom theme folder are themeable out of the box. (This is ignoring the ones with
@listableObject
or@metadataRepresentationComponent
decorators, as they are themeable using a different mechanism)The reason for this is that every component we want to make themeable can’t just be referenced by name somewhere else as that would be a hard link to one specific theme.
Instead we need to replace it with a component with the logic to determine which, if any themed version of the original component should be loaded.
Because we didn’t have the time replace every single component with a themeable counterpart, we decided to focus on the basics: e.g. nearly every page component is themeable out of the box, that way, even if you can’t theme some specific component that’s part of the page, you can theme the page, and inside, use a hard reference to something else.
Is it even possible to customize the components that haven’t been included in the “custom” theme?
Yes, anything can be customized. If you don’t need different versions of the component you want to customize for different themes, you can simply modify the original component file. Granted, that will make it slightly more trouble if you upgrade to a newer version of DSpace later, but usually it’s not that big a problem.
If you do need different themed versions of the same component, or you want to ensure that all your customizations are kept in the theme folder, you can make that component themeable. You can find plenty of examples on how to do so in #1042. It boils down to:
Themed${Original Component Name}
that extendsThemedComponent
. Exampleds-themed${orignal selector}
. Examplethemed.component.html
file as thetemplateUrl
. ExamplegetComponentName()
by returning the name of the original component as a string: ExampleimportUnthemedComponent()
by returning animport()
call for the original component. Use a relative path. This tells us where to find the file in case no themed version was found. ExampleimportThemedComponent()
by returning animport()
call for themed versions of the component. This should be a relative path to where themed versions of that component would be located. Use thethemeName
variable in lieu of the actual name. ExampleinAndOutputNames
, and provide an array of the names of those in and outputs as strings. This is necessary to connect up the wires after the dynamic component has loaded. e.g. ['shouldShowRouteLoader', 'shouldShowFullscreenLoader'], which refers to these inputs on RootComponent<ds-root>
with<ds-themed-root>
in app.component.htmlBaseComponent
. ExampleIf you do go down the route of making additional components themeable, we’d appreciate it if you contribute them, even if it’s only one component at a time. That way, the next person that needs it doesn’t have to go through the trouble of doing it themselves.