Page History
...
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:Code Block 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
- In 7.2 or above, any changes to this configuration just require restarting your site (no rebuild necessary). In 7.1 or 7.0, you must rebuild your site after modifying the favicon.ico.
- NOTE: If you specify multiple formats for your favicon (e.g. favicon.svg and favicon.ico), then your browser will select which one it prefers (e.g. Chrome seems to favor SVG over ICO). However, if you want to force all browser to use a single favicon, then you may wish to only specify one "icon" format in your
headTags
section.
Customize Home Page News
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".
- First, you'll want to decide if you want to modify just the Home Page News HTML, or styles (CSS/Sass), or both.
- If you want to modify the HTML, you'll need to create a copy of the HTML in "app/home-page/home-news/home-news.component.html" in your theme, . This is where you place your changes.
- If you want to modify the styles, you'll need to create a copy of the CSS in "app/home-page/home-news/home-news.component.scss" in your theme, . This is where you place your changes.
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 title home-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' })
- Now, based on what you want to modify, you will need to either update your theme's copy of
home-news.component.html
orhome-news.component.scss
or both.- 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 fromsrc/app/home-page/home-news/home-news.component.html
into your version of this file. - 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 fromsrc/app/home-page/home-news/home-news.component.scss
into your version of this file.
- To change HTML: Your theme's version of the
- Modify the HTML or Sass as you see fit.
- 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. - Keep in mind, all Bootstrap variables, utility classes & styles can be used in these files. Take advantage of Bootstrap when you can do so.
- If you want to add images, add them to your theme's
- 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
...
By now, if you've followed this entire guide, you'll notice a pattern! Customizing specific DSpace UI components requires just three steps:
- Configure your theme to use its copies of files: Modify the corresponding
*.component.ts
in your theme.- If you want to modify component style, replace the "styleUrls" in that file to point at the copy of
*.component.scss
in your theme. - If you want to modify component HTML, replace the "template" in that file to point at the copy of
*.component.html
in your theme.
- If you want to modify component style, replace the "styleUrls" in that file to point at the copy of
- Copy the default UI code into your theme file(s)
- If you want to modify component style, copy the default
*.component.scss
code (fromsrc/app/
) into your theme'scomponent.scss
file. - If you want to modify component HTML, copy the default
*.component.html
code (fromsrc/app/
) into your theme'scomponent.html
file.
- If you want to modify component style, copy the default
- Modify those theme-specific files
- 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. - Keep in mind, all Bootstrap variables, utility classes & styles can be used in these files. Take advantage of Bootstrap when you can do so.
- If you want to add images, add them to your theme's
- Remember to either rebuild the UI after each change, or run in dev mode (yarn start:dev) while you are doing theme work.
Customize UI labels using Internationalization (i18n) files
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:
- You can edit the
src/assets/i18n/*.json5
file(s) directly- For example, to change the label for the browse menu when viewing the UI in English (which defaults to "All of DSpace"), you would edit
src/assets/i18n/en.json5
and change the value formenu.section.browse_global
.
- For example, to change the label for the browse menu when viewing the UI in English (which defaults to "All of DSpace"), you would edit
- And/or, you can create a separate *.json5 file in your theme which only lists the keys you have changed. This can keep your language changes in your theme, and will override the default keys in the
src/assets/i18n/
files. However, a specific setup is necessary, see the "Theme override approach" instructions below.
Info | ||
---|---|---|
| ||
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:
- Create an i18n directory under
src/themes/[theme-name]/assets
- For each language you would like to update, add a file to the new i18n directory following the naming scheme in the default i18n directory (en.json5 for English, fr.json5 for French, etc)
- In each translation file add only the settings that you wish to add or override
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:
Code Block |
---|
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.
Extending other Themes
Info |
---|
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:
Code Block | ||||
---|---|---|---|---|
| ||||
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 |
Code Block | ||
---|---|---|
| ||
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:
- 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.
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:
...
- 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".
- 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".
...
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:
Code Block |
---|
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):
Code Block |
---|
const DECLARATIONS = [
....
FooterComponent,
....
]; |
...
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 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:
...
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:
Code Block |
---|
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:
Code Block |
---|
const DECLARATIONS = [
....
LoginPageComponent,
....
]; |
...
- 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 thelazy-theme.module.ts
similar to step 1 above.
Debugging which theme is being used
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:
...
language | xml |
---|---|
title | HTML source |
...
the simple Item page
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.
- Normal Item: The code for the simple Item page for a normal Item (i.e. not an Entity) can be found in the source code at "
src/app/item-page/simple/item-types/untyped-item/
" - Publication Entity: If you are wanting to modify the display of Publication Entities, it has separate source code under "
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)
- First, you'll want to decide if you want to modify just the Item Page HTML, or styles (CSS/Sass), or both.
- If you want to modify the HTML, you'll need to create a copy of the HTML in "
src/app/item-page/simple/item-types/untyped-item/untyped-item.component.html
" in your theme. This is where you place your changes. - If you want to modify the styles, you'll need to create a copy of the CSS in "
src/app/item-page/simple/item-types/untyped-item/untyped-item.component.scss
" in your theme. This is where you place your changes.
- If you want to modify the HTML, you'll need to create a copy of the HTML in "
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!Code Block title untyped-item.component.ts // 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', })
- Now, based on what you want to modify, you will need to either update your theme's copy of
untyped-item.component.html
oruntyped-item.component.scss
or both.- To change HTML: Your theme's version of the
untyped-item
.component.html
file may be empty by default. Copy over the default HTML code fromsrc/item-page/simple/item-types/untyped-item/untyped-item.component.html
into your version of this file. - To change Styles: Your theme's version of the
untyped-item
.component.scss
file may be empty by default. Copy over the default Sass code fromsrc/item-page/simple/item-types/untyped-item/untyped-item.component
.scss
into your version of this file
- To change HTML: Your theme's version of the
- In the HTML of the Simple Item page, you'll see a number of custom "ds-" HTML-like tags which make displaying individual metadata fields easier. These tags make it easier to add/remove metadata fields on this page.
<ds-generic-item-page-field>
- This tag can be used to display the value of any metadata field (as a string).- Put the name of the metadata field in the "[fields]" attribute... see existing fields as an example.
- Put the i18n label you want to use for this field in the "[label]" attribute. Again, see existing fields as an example. This i18n tag MUST then be added to your "
src/assets/i18n/en.json5
" file (or corresponding file depending on your language) - For example, here's a new ds-generic-item-page-field which displays the value of the "dc.title.alternative" field with a label defined in the "
<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)- This field has the same attributes at
<ds-generic-item-page-field>
above.
- This field has the same attributes at
- Some specific tags exist for other fields (e.g.
<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.
- To add new fields, just add new "<ds-generic-item-page-field>" tags (or similar). To remove fields, just comment them out or remove the HTML. You can also restructure the columns on that page using simple HTML and Bootstrap CSS.
- 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.
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.
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:
- Configure your theme to use its copies of files: Modify the corresponding
*.component.ts
in your theme.- If you want to modify component style, replace the "styleUrls" in that file to point at the copy of
*.component.scss
in your theme. - If you want to modify component HTML, replace the "template" in that file to point at the copy of
*.component.html
in your theme.
- If you want to modify component style, replace the "styleUrls" in that file to point at the copy of
- Copy the default UI code into your theme file(s)
- If you want to modify component style, copy the default
*.component.scss
code (fromsrc/app/
) into your theme'scomponent.scss
file. - If you want to modify component HTML, copy the default
*.component.html
code (fromsrc/app/
) into your theme'scomponent.html
file.
- If you want to modify component style, copy the default
- Modify those theme-specific files
- 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. - Keep in mind, all Bootstrap variables, utility classes & styles can be used in these files. Take advantage of Bootstrap when you can do so.
- If you want to add images, add them to your theme's
- Remember to either rebuild the UI after each change, or run in dev mode (yarn start:dev) while you are doing theme work.
Customize UI labels using Internationalization (i18n) files
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:
- You can edit the
src/assets/i18n/*.json5
file(s) directly- For example, to change the label for the browse menu when viewing the UI in English (which defaults to "All of DSpace"), you would edit
src/assets/i18n/en.json5
and change the value formenu.section.browse_global
.
- For example, to change the label for the browse menu when viewing the UI in English (which defaults to "All of DSpace"), you would edit
- And/or, you can create a separate *.json5 file in your theme which only lists the keys you have changed. This can keep your language changes in your theme, and will override the default keys in the
src/assets/i18n/
files. However, a specific setup is necessary, see the "Theme override approach" instructions below.
Info | ||
---|---|---|
| ||
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:
- Create an i18n directory under
src/themes/[theme-name]/assets
- For each language you would like to update, add a file to the new i18n directory following the naming scheme in the default i18n directory (en.json5 for English, fr.json5 for French, etc)
- In each translation file add only the settings that you wish to add or override
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:
Code Block |
---|
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.
Extending other Themes
Info |
---|
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:
Code Block | ||||
---|---|---|---|---|
| ||||
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 |
Code Block | ||
---|---|---|
| ||
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:
- 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.
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:
- 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.
- 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".
- 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".
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. TheseENTRY_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:
Code Block 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):
Code Block const DECLARATIONS = [ .... FooterComponent, .... ];
- 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.
- 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 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:
- First you MUST remove all references to that directory/component from your theme's
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:
Code Block 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:Code Block const DECLARATIONS = [ .... LoginPageComponent, .... ];
- Finally, delete the directory in question from your theme.
- At this point, you should rebuild/restart your UI to verify nothing has broken. If you did everything correctly, no build errors will occur.
- 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 thelazy-theme.module.ts
similar to step 1 above.
- If you failed to edit your
Debugging which theme is being used
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:
Code Block | ||||
---|---|---|---|---|
| ||||
<!-- 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> |
Finding which component is generating the content on a page
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.
- View the HTML source of the page in your browser. Search for that section of the page. (Or, right click on that part of the page and select "Inspect")
- For example, on the homepage view the source of the "Communities in DSpace" heading
- Look for a parent HTML tag that begins with "ds-". This is the component selector!
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):
Code Block <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>
- Based on the above HTML source, you can see that the "Communities in DSpace" header/content is coming from a component who's selector is "ds-top-level-community-list"
- Now, search the source code (./src/app/) directories for a ".component.ts" file which includes that "ds-" tag name. This can most easily be done in an IDE, but also could be done using command line tools (e.g. grep like this).
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:Code Block @Component({ selector: 'ds-top-level-community-list', ... })
- This lets you know that to modify the display of that section of the page, you may need to edit either the "
top-level-community-list.component.ts
" file or it's corresponding HTML file at "top-level-community-list.component.html
"
- Once you've located the component, you can edit that component's HTML file (ending in "component.html") to change that section of the page.
- Keep in mind, the component's HTML file may reference other "ds-" tags! Those are other components in DSpace which you can find again by searching the "./src/app" directories for that tag.
...
Additional Theming Resources
...