User Interface Configuration

Overview

As the DSpace User Interface is built on Angular.io, it aligns with many of the best practices of that platform & the surrounding community. One example is that our UI uses the TypeScript language. That said, you do NOT need to be deeply familiar with TypeScript to edit themes or other configuration.

Configuration File Format

The configuration format is YAML and is located at ./config/config.*.yaml.

Configuration Override

The UI configuration files reside in the ./config/ folder in the Angular UI source code. The default configuration is provided in config.yml.

To change the default configuration values, you simply create (one or more) local files that override the parameters you need to modify. You can use config.example.yml as a starting point.

For example, create a new config.dev.yml file in config/ for a development environment;
For example, create a new config.prod.yml file in config/ for a production environment;

Configurations can also be overridden via one of the following

Using Environment variables. All environment variables MUST (1) be prefixed with "DSPACE_", (2) use underscores as separators (no dots allowed), and (3) use all uppercase. Some examples are below:

# "ui" settings environment variables
ui.host => DSPACE_UI_HOST # The host name 
ui.port => DSPACE_UI_PORT # The port number 
ui.nameSpace => DSPACE_UI_NAMESPACE # The namespace
ui.ssl => DSPACE_UI_SSL # Whether the angular application uses SSL [true/false]

# "rest" settings environment variables
rest.host => DSPACE_REST_HOST # The host name of the REST application
rest.port => DSPACE_REST_PORT # The port number of the REST application
rest.nameSpace => DSPACE_REST_NAMESPACE # The namespace of the REST application
rest.ssl => DSPACE_REST_SSL # Whether the angular REST uses SSL [true/false]

# Other examples
defaultLanguage => DSPACE_DEFAULTLANGUAGE
mediaViewer.video => DSPACE_MEDIAVIEWER_VIDEO

# Multi-valued setting examples
# If a setting can have multiple values (e.g. theme names), then use an index number (starting with zero)
# to specify the multiple values.
# The below example is equivalent to:
# themes:
#   - name: 'dspace'
#   - name: 'mytheme'
#     handle: '10673/123'
DSPACE_THEMES_0_NAME = 'dspace'
DSPACE_THEMES_1_NAME = 'mytheme'
DSPACE_THEMES_1_HANDLE = '10673/123'

Or, by creating a .env (environment) file in the project root directory and setting the environment variables in that location.

The override priority ordering is as follows (with items listed at the top overriding all other settings)

Environment variables
The .env file
The ./config/config.prod.yml, ./config/config.dev.yml or ./config/config.test.yml files (depending on current mode)
The ./config/config.yml file
The hardcoded defaults in ./src/config/default-app-config.ts

Configuration Reference

The following configurations are available in ./config/config.example.yml These settings may be overridden as described above.

UI Core Settings

The "ui" (user interface) section defines where you want Node.js to run/respond. It may correspond to your primary/public URL, but it also may not (if you are running behind a proxy). In this example, we are setting up our UI to just use localhost, port 4000. This is a common setup for when you want to use Apache or Nginx to handle HTTPS and proxy requests to Node.js running on port 4000.

config.*.yml

ui:
  ssl: false
  host: localhost
  port: 4000
  # NOTE: Space is capitalized because 'namespace' is a reserved string in TypeScript
  nameSpace: /
  # The rateLimiter settings limit each IP to a 'max' of 500 requests per 'windowMs' (1 minute).
  rateLimiter:
    windowMs: 60000 # 1 minute
    max: 500 # limit each IP to 500 requests per windowMs

The "rateLimiter" sub-section can be used to protect against a DOS (denial of service) attack when the UI is processed on the server side (i.e. server-side rendering). Default settings are usually OK. In Angular, server-side rendering occurs to support better Search Engine Optimization (SEO), as well as to support clients which cannot use Javascript. See the next section for more details.

Sub-path in frontend URL: When using a subpath (nameSpace) in your UI server base URL (e.g. "http://localhost:4000/mysite/" instead of "http://localhost:4000/"), you must make sure that the URL without the subpath is added to the rest.cors.allowed-origins list in [dspace]/config/modules/rest.cfg or the local.cfg override. The default value used for this configuration assumes that Origin and DSpace URL are identical, but CORS origins do not contain a subpath. Without this change you will see CORS policy errors preventing communication between the frontend and backend servers.

Server Side Rendering (SSR) Settings

In DSpace 7, this section was called "universal", which referenced "Angular Universal", the original name of Angular's Server Side Rendering (SSR). As of DSpace 8, this section has been renamed "ssr", but the settings are the same.

The "ssr" section defines configurations related to Angular's Server Side Rendering (SSR). DSpace enables Angular SSR by default as required for Search Engine Optimization (SEO), as well as to support clients which cannot use Javascript. The default settings attempt to provide a balance between SEO and performance. However, you may choose to customize this behavior based on your local needs.

config.*.yml

ssr:
# Whether to tell Angular to inline "critical" styles into the server-side rendered HTML.
# Determining which styles are critical is a relatively expensive operation; this option is
# disabled (false) by default to boost server performance at the expense of loading smoothness.
inlineCriticalCss: false
# Path prefixes to enable SSR for. By default these are limited to paths of primary DSpace objects listed in the DSpace sitemap.
# Paths are matched based on whether they "start with" a string in this configuration. Wildcards are not supported.
# To disable this feature, specify [ '/' ], as that will result in all paths being enabled for SSR.
paths: [ '/home', '/items/', '/entities/', '/collections/', '/communities/', '/bitstream/', '/bitstreams/', '/handle/' ]
# Whether to enable rendering of Search component in SSR.
# If set to true the component will be included in the HTML returned from the server side rendering.
# If set to false the component will not be included in the HTML returned from the server side rendering.
enableSearchComponent: false
# Whether to enable rendering of Browse component on SSR.
# If set to true the component will be included in the HTML returned from the server side rendering.
# If set to false the component will not be included in the HTML returned from the server side rendering.
enableBrowseComponent: false
# Enable state transfer from the server-side application to the client-side application. (Defaults to true)
# Note: When using an external application cache layer, it's recommended not to transfer the state to avoid caching it.
# Disabling it ensures that dynamic state information is not inadvertently cached, which can improve security and
# ensure that users always use the most up-to-date state.
transferState: true
# When a different REST base URL is used for the server-side application, the generated state contains references to
# REST resources with the internal URL configured. By default, these internal URLs are replaced with public URLs.
# Disable this setting to avoid URL replacement during SSR. In this the state is not transferred to avoid security issues.
replaceRestUrl: true
# Enable request performance profiling data collection and printing the results in the server console.
# Defaults to false. Enabling in production is NOT recommended
enablePerformanceProfiler: false

The "paths" setting defines which DSpace pages will be processed in server-side rendering. For proper Search Engine Optimization, you should ensure this "paths" setting includes all URL paths that you want to be indexed by search engine bots. Any paths not listed in this setting will be inaccessible to most bots/crawlers (at least any that cannot process Javascript). The default "paths" settings are listed above, and they correspond to every page which is listed in the Sitemaps or may be of interest to search engines. DSpace purposefully does not add "/search" or "/browse" pages to these paths because bot requests to those pages may result in performance issues or require a larger amount of CPU to process the SSR. Keep in mind that values of "paths" are matched against the start of a path, so "/items/" will match every Item page in the system.

The "enableSearchComponent" and "enableBrowseComponent" settings control whether the Angular Components related to search/browse are enabled for SSR or not. These components are used in many different pages within the DSpace site, and these configurations are obeyed site wide. For example, while the "/communities/" and "/collections/" pages do undergo SSR by default, both of these pages also include embedded browse options as separate tabs. Setting "enableBrowseComponent: false" will ensure that the browse tabs for all Communities and Collections are not processed by SSR. Similarly, some "/entities/" pages (e.g. Person Entities) may include an embedded search section on the entity page. Setting "enableSearchComponent: false" will ensure that embedded search section for all Entities is not processed by SSR.

The "transferState" and "replaceRestUrl" settings are ONLY used if you've set the "ssrBaseUrl" setting the REST API Settings below (see next section). When the "ssrBaseUrl" is specified, then a different REST API URL is being used for all SSR requests. Setting "transferState" to true (default vaule) will ensure that the state of the server-side application will be transferred to the client-side after SSR completes. This is recommended behavior unless you are using an external cache layer. Setting "replaceRestUrl" to true (default value) will ensure that all URLs returned in the JSON response of an SSR request to the "ssrBaseUrl" will be updated to use the public REST API URL (set by the "ssl", "host", "port" and "nameSpace" in the REST API Settings). This is recommended behavior to ensure the client-side application has access to the public URLs you can use. Setting "replaceRestUrl" to false will disable this URL replacement, but will also disable "transferState" to ensure the state is not transferred while including potentially "private" URLs.

The "enablePerformanceProfiler" setting should always remain false in production environments. Setting it to "true" will enable request performance profiling data collection and print those results to the server console. This corresponds to the Angular SSR setting for performance profiling.

REST API Settings

The "rest" (REST API) section defines which REST API the UI will use. The REST settings MUST correspond to the primary URL of the backend. Usually, this means they must be kept in sync
with the value of dspace.server.url in the backend's local.cfg. See Configuration Reference.

This example is valid if your Backend is publicly available at https://mydspace.edu/server/ . Keep in mind that the "port" must always be specified even if it's a standard port (i.e. port 80 for HTTP and port 443 for HTTPS).

config.*.yml

rest:
  ssl: true
  host: mydspace.edu
  port: 443
  # NOTE: Space is capitalized because 'namespace' is a reserved string in TypeScript
  nameSpace: /server
  # OPTIONAL: Provide a different REST API URL to be used during SSR execution. 
  # It must contain the whole URL including protocol, server port and server namespace
  ssrBaseUrl: http://localhost:8080/server

The "ssl", "host", "port" and "nameSpace" settings are all required , and are used to construct the URL used to contact the REST API. As noted above, these four settings should be kept in sync with the value of dspace.server.url in the backend's local.cfg

The "ssrBaseUrl" provides the option to use a different URL for the REST API when performing Server Side Rendering (SSR) (see prior section). This is not enabled by default, but it can provide potential SSR performance benefits, as it allows all SSR requests to bypass DNS lookup. For example, the primary REST API settings (ssl, host, port, nameSpace) should always reference a public URL like "https://mydspace.edu/server". But, you could set the "ssrBaseUrl" to a localhost URL (e.g. "http://localhost:8080/server") if your REST API is running on the same machine as the User Interface. This would result in all client-side code (running in the user's browser) accessing the REST API via the public URL, while the server-side code (triggered by SSR) would access the REST API via the localhost URL. A few important tips:

The "ssrBaseUrl" need not always be a localhost URL, but it must be accessible to the machine where the User Interface's server-side code is running.
When the "ssrBaseUrl" is specified, you must also set the corresponding dspace.server.ssr.url in the backend's local.cfg. See Configuration Reference.
When the "ssrBaseUrl" is specified, there are additional "ssr" settings available including "transferState" and "replaceRestUrl". See Server Side Rendering (SSR) above.

Cache Settings - General

The "cache" section controls how long objects/responses will remain in the UI cache. The defaults should be OK for most sites.

config.*.yml

cache:
  # NOTE: how long should objects be cached for by default
  msToLive:
    default: 900000 # 15 minutes
  # Default 'Cache-Control' HTTP Header to set for all static content (including compiled *.js files)
  # Defaults to one week. This lets a user's browser know that it can cache these files for one week, 
  # after which they will be "stale" and need to be redownloaded.
  control: max-age=604800 # one week
  autoSync:
    defaultTime: 0
    maxBufferSize: 100
    timePerMethod:
      PATCH: 3 # time in seconds

Cache Settings - Server Side Rendering (SSR)

Caching options are also available for the User Interface's "server-side rendering" (which uses Angular Universal). Server-side rendering is used to pre-generate full HTML pages and pass those back to users. This is necessary for Search Engine Optimization (SEO) as some web crawlers cannot use Javascript. It also can be used to immediately show the first HTML page to users while the Javascript app loads in the user's browser.

While server-side-rendering is highly recommended on all sites, it can result in Node.js having to pre-generate many HTML pages at once when a site has a large number of simultaneous users/bots. This may cause Node.js to spend a lot of time processing server-side-rendered content, slowing down the entire site.

Therefore, DSpace provides some basic caching of server-side rendered pages, which allows the same pre-generated HTML to be sent to many users/bots at once & decreases the frequency of server-side rendering.

Two cache options are provide: botCache and anonymousCache . As the names suggest, the botCache is used for known web crawlers / bots, while the anonymousCache may be used for all anonymous (non-authenticated) users. By default, only the botCache is enabled. But highly active sites may wish to enable the anonymousCache as well, since it can provide users with a more immediate response when they encounter cached pages.

Keep in mind, when the "anonymousCache" is enabled, this means that all non-authenticated users will utilize this cache. This cache can result in massive speed improvements (for initial page load), as the majority of users may be interacting with cached content. However, these users may occasionally encounter cached pages which are outdated or "stale" (based on values of "timeToLive" and "allowStale"). This means that these users will not immediately see new updates or newly added content (Communities, Collections, Items) until the cache has refreshed itself. That said, when "timeToLive" is set to a low value (like 10 seconds), this risk is minimal for highly active pages/content.

config.*.yml

cache:
...
serverSide:
# Set to true to see all cache hits/misses/refreshes in your console logs. Useful for debugging SSR caching issues.
debug: false
# When enabled (i.e. max > 0), known bots will be sent pages from a server side cache specific for bots.
# (Keep in mind, bot detection cannot be guarranteed. It is possible some bots will bypass this cache.)
botCache:
# Maximum number of pages to cache for known bots. Set to zero (0) to disable server side caching for bots.
# Default is 1000, which means the 1000 most recently accessed public pages will be cached.
# As all pages are cached in server memory, increasing this value will increase memory needs.
# Individual cached pages are usually small (<100KB), so max=1000 should only require ~100MB of memory.
max: 1000
# Amount of time after which cached pages are considered stale (in ms). After becoming stale, the cached
# copy is automatically refreshed on the next request.
# NOTE: For the bot cache, this setting may impact how quickly search engine bots will index new content on your site.
# For example, setting this to one week may mean that search engine bots may not find all new content for one week.
timeToLive: 86400000 # 1 day
# When set to true, after timeToLive expires, the next request will receive the *cached* page & then re-render the page
# behind the scenes to update the cache. This ensures users primarily interact with the cache, but may receive stale pages (older than timeToLive).
# When set to false, after timeToLive expires, the next request will wait on SSR to complete & receive a fresh page (which is then saved to cache).
# This ensures stale pages (older than timeToLive) are never returned from the cache, but some users will wait on SSR.
allowStale: true
# When enabled (i.e. max > 0), all anonymous users will be sent pages from a server side cache.
# This allows anonymous users to interact more quickly with the site, but also means they may see slightly
# outdated content (based on timeToLive)
anonymousCache:
# Maximum number of pages to cache. Default is zero (0) which means anonymous user cache is disabled.
# As all pages are cached in server memory, increasing this value will increase memory needs.
# Individual cached pages are usually small (<100KB), so a value of max=1000 would only require ~100MB of memory.
max: 0
# Amount of time after which cached pages are considered stale (in ms). After becoming stale, the cached
# copy is automatically refreshed on the next request.
# NOTE: For the anonymous cache, it is recommended to keep this value low to avoid anonymous users seeing outdated content.
timeToLive: 10000 # 10 seconds
# When set to true, after timeToLive expires, the next request will receive the *cached* page & then re-render the page
# behind the scenes to update the cache. This ensures users primarily interact with the cache, but may receive stale pages (older than timeToLive).
# When set to false, after timeToLive expires, the next request will wait on SSR to complete & receive a fresh page (which is then saved to cache).
# This ensures stale pages (older than timeToLive) are never returned from the cache, but some users will wait on SSR.
allowStale: true

Authentication Settings

The "auth" section provides some basic authentication-related settings. Currently, it's primarily settings related to when a session timeout warning will be showed to your users, etc.

config.*.yml

auth:
  # Authentication UI settings
  ui:
    # the amount of time before the idle warning is shown
    timeUntilIdle: 900000 # 15 minutes
    # the amount of time the user has to react after the idle warning is shown before they are logged out.
    idleGracePeriod: 300000 # 5 minutes
  # Authentication REST settings
  rest:
    # If the rest token expires in less than this amount of time, it will be refreshed automatically.
    # This is independent from the idle warning. Defaults to automatic refresh when the token will
    # expire within 2 minutes. Because token expires after 30 minutes by default, this means automatic
    # refresh would occur every ~28 minutes.
    timeLeftBeforeTokenRefresh: 120000 # 2 minutes

Form Settings

The "form" section provides basic settings for any forms displayed in the UI. At this time, these settings only include a validatorMap, which is not necessary to modify for most sites

config.*.yml

form:
  # Whether to enable "spellcheck" attribute of textareas in forms.
  spellCheck: true
  # NOTE: Map server-side validators to comparative Angular form validators
  validatorMap:
    required: required
    regex: pattern

Notification Settings

The "notifications" section provides options related to where user notifications will appear in your UI. By default, they appear in the top right corner, and timeout after 5 seconds.

config.*.yml

notifications:
  rtl: false
  position:
    - top
    - right
  maxStack: 8
  # NOTE: after how many seconds notification is closed automatically. If set to zero notifications are not closed automatically
  timeOut: 5000 # 5 second
  clickToClose: true
  # NOTE: 'fade' | 'fromTop' | 'fromRight' | 'fromBottom' | 'fromLeft' | 'rotate' | 'scale'
  animate: scale

The set of valid animations can be found in the NotificationAnimationsType, and are implemented in ./src/shared/animations/

Submission Settings

The "submission" section provides some basic Submission/Deposit UI options. These allow you to optionally enable an autosave (disabled by default), and custom styles/icons for metadata fields or authority confidence values.

config.*.yml

submission:
  autosave:
    # NOTE: which metadata trigger an autosave
    metadata: []
    # NOTE: after how many time (milliseconds) submission is saved automatically
    # eg. timer: 300000 # 5 minutes
    timer: 0
  icons:
    metadata:
      # NOTE: example of configuration
      #   # NOTE: metadata name
      # - name: dc.author
      #   # NOTE: fontawesome (v6.x) icon classes and bootstrap utility classes can be used
      #   style: fas fa-user
      - name: dc.author
        style: fas fa-user
      # default configuration
      - name: default
        style: ''
    authority:
      confidence:
        # NOTE: example of configuration
        #   # NOTE: confidence value
        # - value: 600
        #   # NOTE: fontawesome (v6.x) icon classes and bootstrap utility classes can be used
        #   style: text-success
        #   icon: fa-circle-check
        #   # NOTE: the class configured in property style is used by default, the icon property could be used in component
        #           configured to use a 'icon mode' display (mainly in edit-item page)
        - value: 600
          style: text-success
          icon: fa-circle-check
        - value: 500
          style: text-info
          icon: fa-gear
        - value: 400
          style: text-warning
          icon: fa-circle-question
        - value: 300
          style: text-muted
          icon: fa-thumbs-down
        - value: 200
          style: text-muted
          icon: fa-circle-exclamation
        - value: 100
          style: text-muted
          icon: fa-circle-stop
        - value: 0
          style: text-muted
          icon: fa-ban
        - value: -1
          style: text-muted
          icon: fa-circle-xmark
        # default configuration
        - value: default
          style: text-muted
          icon: fa-circle-xmark

Language Settings

The "defaultLanguage" and "languages" sections allow you to customize which languages to support in your User Interface. See also Multilingual Support.

config.*.yml

#  Default Language in which the UI will be rendered if the user's browser language is not an active language
defaultLanguage: en

# Languages. DSpace Angular holds a message catalog for each of the following languages.
# When set to active, users will be able to switch to the use of this language in the user interface.
# All out of the box language packs may be found in the ./src/assets/i18n/ directory
languages:
  - code: en
    label: English
    active: true
  - code: cs
    label: Čeština
    active: true
  - code: de
    label: Deutsch
    active: true
  - ...

The DSpace UI requires that a corresponding language pack file (named with the language code and ending in ".json5") be placed in ./src/assets/i18n/. See also DSpace 7 Translation - Internationalization (i18n) - Localization (l10n) for information about how to create and contribute these files.

Browse By Settings

The "browseBy" section provides basic UI configurations for "Browse by" pages (/browse path). The "Browse by" options that appear in the "All of DSpace" header menu are determined dynamically from the REST API. This allows the UI to change dynamically based on the configured browse indexes in Discovery.

config.*.yml

browseBy:
  # Amount of years to display using jumps of one year (current year - oneYearLimit)
  oneYearLimit: 10
  # Limit for years to display using jumps of five years (current year - fiveYearLimit)
  fiveYearLimit: 30
  # The absolute lowest year to display in the dropdown (only used when no lowest date can be found for all items)
  defaultLowerLimit: 1900
  # If true, thumbnail images for items will be added to BOTH search and browse result lists. (default: true)
  showThumbnails: true
  # The number of entries in a paginated browse results list.
  # Rounded to the nearest size in the list of selectable sizes on the settings menu.
  pageSize: 20

# NOTE: The "types" section no longer exists, as it is determined dynamically via the REST API

NOTE: The "pageSize" configuration will always round to the closest "pageSizeOptions" value listed in "page-component-options.model.ts"

Community-List Settings

The "communityList" section allows you to configure the behavior of the "Communities & Collections" page (/community-list path), which is linked in the header.

config.*.yml

communityList:   
  # Number of communities to list per expansion (i.e. each time you click "show more")
  pageSize: 20

NOTE: The "pageSize" configuration will always round to the closest "pageSizeOptions" value listed in "page-component-options.model.ts"

Homepage Settings

The "homePage" section allows you to configure the behavior of the DSpace homepage (/ path).

config.*.yml

homePage:   
  recentSubmissions:
    # The number of item showing in recent submissions list. Set to "0" to hide all recent submissions
    pageSize: 5
    # Date field to use to sort recent submissions
    sortField: 'dc.date.accessioned'
  topLevelCommunityList:
    # Number of communities to list (per page) on the home page
    # This will always round to the nearest number from the list of page sizes. e.g. if you set it to 7 it'll use 10
    pageSize: 5
  # Enable or disable the Discover filters on the homepage
  showDiscoverFilters: false

NOTE: The "pageSize" configuration will always round to the closest "pageSizeOptions" value listed in "page-component-options.model.ts"

Undo Settings

Both the "item" edit and "collection" edit screens allow you to undo changes within a specific time. This is controlled by these settings:

config.*.yml

item:
  edit:
    undoTimeout: 10000 # 10 seconds

collection:
  edit:
    undoTimeout: 10000 # 10 seconds

Item Access Labels

Item access labels allow to display for each item in search results if it is Open Access, under embargo, restricted or metadata only (does not contain any file/bitstream). This feature is disabled by default, but can be enabled in your config.*.yml.

config.*.yml

# Item Config
item:
  # Show the item access status label in items lists (default=false)
  showAccessStatuses: true

Item Page Settings

The "item" section allows you to configure the behavior of the Item pages.

config.*.yml

item:
  ...
  bitstream:
    # Number of entries in the bitstream list in the item view page.
    pageSize: 5
    # Show the bitstream access status label on the item page (default=false)
    # When enabled, embargoed bitstreams will show their embargo date in a label.
    showAccessStatuses: false

NOTE: The "pageSize" configuration will always round to the closest "pageSizeOptions" value listed in "page-component-options.model.ts"

Community Page Settings

The "community" section allows you to configure the behavior of the Community pages (Path: /community/[uuid]).

config.*.yml

community:
  # Search tab config
  searchSection:
    # When set to "true", the search filter sidebar will be displayed on the "Search" tab
    showSidebar: true
  # Default tab to be shown when browsing a Community. Valid values are: comcols, search, or browse_<field>
  # <field> must be any of the configured "browse by" fields, e.g., dateissued, author, title, or subject
  # When the default tab is not the 'search' tab, the search tab is moved to the last position
  defaultBrowseTab: search

Collection Page Settings

The "collection" section allows you to configure the behavior of the Collection pages (Path: /collection/[uuid]).

config.*.yml

collection:
  # Search tab config
  searchSection:
    # When set to "true", the search filter sidebar will be displayed on the "Search" tab
    showSidebar: true
  # Default tab to be shown when browsing a Collection. Valid values are: search, or browse_<field>
  # <field> must be any of the configured "browse by" fields, e.g., dateissued, author, title, or subject
  # When the default tab is not the 'search' tab, the search tab is moved to the last position
  defaultBrowseTab: search

Theme Settings

The "themes" section allows you to configure which theme(s) are enabled for your DSpace site (with the default theme being the "dspace" one). You can enable a single theme across all pages, and/or enable specific alternative themes based on a specific Community, Collection or Item (by UUID or Handle), or based on a Regex match of a URL pattern. This allows you fine grained control over how your site looks, including the ability to customize it per Community or Collection or even per specific pages in the site. See User Interface Customization for details of how to create a new, custom theme.

config.*.yml

themes:
  # Add additional themes here. In the case where multiple themes match a route, the first one
  # in this list will get priority. It is advisable to always have a theme that matches
  # every route as the last one
  #
  # # A theme with a handle property will match the community, collection or item with the given
  # # handle, and all collections and/or items within it
  # - name: 'custom',
  #   handle: '10673/1233'
  #
  # # A theme with a regex property will match the route using a regular expression. If it
  # # matches the route for a community or collection it will also apply to all collections
  # # and/or items within it
  # - name: 'custom',
  #   regex: 'collections\/e8043bc2.*'
  #
  # # A theme with a uuid property will match the community, collection or item with the given
  # # ID, and all collections and/or items within it
  # - name: 'custom',
  #   uuid: '0958c910-2037-42a9-81c7-dca80e3892b4'
  #
  # # The extends property specifies an ancestor theme (by name). Whenever a themed component is not found
  # # in the current theme, its ancestor theme(s) will be checked recursively before falling back to default.
  # - name: 'custom-A',
  #   extends: 'custom-B',
  #   # Any of the matching properties above can be used
  #   handle: '10673/34'
  #
  # - name: 'custom-B',
  #   extends: 'custom',
  #   handle: '10673/12'
  #
  # # A theme with only a name will match every route
  # name: 'custom'
  #
  # # This theme will use the default bootstrap styling for DSpace components
  # - name: BASE_THEME_NAME
  #
  - 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:
    - tagName: link
      attributes:
        rel: icon
        href: assets/dspace/images/favicons/favicon.ico
        sizes: any
    - tagName: link
      attributes:
        rel: icon
        href: assets/dspace/images/favicons/favicon.svg
        type: image/svg+xml
    - tagName: link
      attributes:
        rel: apple-touch-icon
        href: assets/dspace/images/favicons/apple-touch-icon.png
    - tagName: link
      attributes:
        rel: manifest
        href: assets/dspace/images/favicons/manifest.webmanifest

Bundle Settings

The "bundle" section allows you to customize which bundles will be displayed as suggestions whenever you upload a new Bitstream:

bundle:
  standardBundles: [ ORIGINAL, THUMBNAIL, LICENSE ]

Media Viewer Settings

The DSpace UI comes with a basic, out-of-the-box Media Viewer (disabled by default). This media viewer can support any files which have a MIME Type that begins with either "image/*", "video/*", or "audio/*".

config.*.yml

# Whether to enable media viewer for image and/or video Bitstreams (i.e. Bitstreams whose MIME type starts with 'image' or 'video').
# When "image: true", this enables a gallery viewer where you can zoom or page through images.
# When "video: true", this enables embedded video streaming.  This embedded video streamer also supports audio files.
mediaViewer:
  image: false
  video: false

Uploading video captioning files

The Video viewer also supports WebVTT (or VTT) Captioning. Video captioning requires that a WebVTT Caption file (.vtt) be uploaded into the DSpace Item (DSpace is not able to create or generate these .vtt files). Here's an example of how to setup captioning:

The Item must already have a Bitstream which is a video file (in a "video/*" format) in the ORIGINAL bundle. In this example, we'll assume it is named "myVideo.mp4"
Upload a corresponding WebVTT Caption file named "[video-filename]-[languageCode].vtt" to the ORIGINAL bundle.
- For a video named "myVideo.mp4", an English caption file would be named "myVideo.mp4-en.vtt".
- If an additional Spanish language caption file was uploaded, it should be named "myVideo.mp4-es.vtt".
- All WebVTT Caption files MUST use two-letter ISO 639-1 Language Codes. A list of all supported Language Codes can be found in "src/app/item-page/media-viewer/media-viewer-video/language-helper.ts"
Once the Caption file is uploaded, reload the video viewer (on the Item page). You should now see the "Captions" (or CC) option is now available. (Depending on the browser you use, this option may appear in the lower menu of the video, or require you to open an options menu.) Selecting it will enable captioning in your language of choice.

Toggle end-user agreement and privacy policy

The DSpace UI comes with basic end-user agreement and privacy policy functionality. These features can be disabled in a configuration file. More information on what disabling on of these features results in is documented in the default app configuration (see code snippet below).

config.*.yml

info:
  # Whether the end user agreement is required before users may use the repository.
  # If enabled, the user will be required to accept the agreement before they can use the repository.
  # If disabled, the page will not exist and no agreement is required to use the repository
  enableEndUserAgreement: false
  # Whether the privacy statement should exist or not.
  enablePrivacyStatement: false

By default the features are enabled.

Settings for rendering Markdown, HTML and MathJax in metadata

The DSpace UI can support Markdown (using https://commonmark.org/) and MathJax (https://www.mathjax.org) in metadata field values. Both Markdown and MathJax are disabled by default.

HTML is a part of markdown, so enabling the markdown option will ensure HTML tags in metadata field values get rendered as well

config.*.yml

# Whether to enable Markdown (https://commonmark.org/) and MathJax (https://www.mathjax.org/)
# display in supported metadata fields. By default, only dc.description.abstract is supported.
markdown:
  enabled: false
  mathjax: false

Mathjax will only be rendered if markdown is enabled, so configuring 'markdown.mathjax = true' with 'markdown.enabled = false' will have no effect.

By default, only the "dc.description.abstract" metadata supports these formats when enabled. To enable markdown for other metadata fields, a custom sub-component of the ItemPageFieldComponent has to be created for that metadata field, with the enableMarkdown field set to true. Refer to the ItemPageAbstractFieldComponent component for an example.

Controlled Vocabularies in Search Filters

When using hierarchical controlled vocabularies (e.g. SRSC as described in Authority Control of Metadata Values), it's possible to search using the controlled vocabulary hierarchy via the search filters. To enable this feature, you must specify the filter and vocabulary to enable as follows:

config.*.yml

# Which vocabularies should be used for which search filters
# and whether to show the filter in the search sidebar
# Take a look at the filter-vocabulary-config.ts file for documentation on how the options are obtained
vocabularies:
  - filter: 'subject'
    vocabulary: 'srsc'
    enabled: true

Keep in mind, the "filter" MUST be a valid search filter (e.g. subject, author) as seen on the "/api/discover/facets" REST API endpoint. The "vocabulary" MUST be a valid controlled vocabulary installed in your DSpace backend (under "[dspace]/config/controlled-vocab/" folder based on the documentation at Authority Control of Metadata Values.

When this feature is enabled, you should see a "Browse [filter] tree" link in the search filter on the search results page (and anywhere search filters are shown). This "Browse [filter] tree" link will allow you to select a search filter from within the configured hierarchical vocabulary.

Search settings

The "search" section allows you to customize how the Search page works (Path: /search)

config.*.yml

search:
  # Settings to enable/disable or configure Advanced Search filters.
  advancedFilters:
    enabled: false
    # List of filters to enable in "Advanced Search" dropdown
    filter: [ 'title', 'author', 'subject', 'entityType' ]

Geospatial map viewer settings

The "geospatialMapViewer" section allows you to enable the display of geospatial maps on item pages, search result views, and as a "browse by" page.

Take note of the default field used for geospatial metadata - this may need to be changed to fit your specific repository metadata usage.

config.*.yml

# Geospatial Map display options
geospatialMapViewer:
  # Which fields to use for parsing as geospatial points in search maps
  # (note, the item page field component allows any field(s) to be used
  # and is set as an input when declaring the component)
  spatialMetadataFields:
    - 'dcterms.spatial'
  # Which discovery configuration to use for 'geospatial search', used
  # in the browse map
  spatialFacetDiscoveryConfiguration: 'geospatial'
  # Which filter / facet name to use for faceted geospatial search
  # used in the browse map
  spatialPointFilterName: 'point'
  # Whether item page geospatial metadata should be displayed
  # (assumes they are wrapped in a test for this config in the template as
  # per the default templates supplied with DSpace for untyped-item and publication)
  enableItemPageFields: false
  # Whether the browse map should be enabled and included in the browse menu
  enableBrowseMap: false
  # Whether a 'map view' mode should be included alongside list and grid views
  # in search result pages
  enableSearchViewMode: false
  # The tile provider(s) to use for the map tiles drawn in the leaflet maps.
  # (see https://leaflet-extras.github.io/leaflet-providers/preview/) for a full list
  tileProviders:
    - 'OpenStreetMap.Mapnik'
  # Starting centre point for the map, as lat and lng coordinates. This is useful
  # to set the centre of the map when the map is first loaded and if there are no
  # points, shapes or markers to display.
  # Defaults to the centre of Istanbul
  defaultCentrePoint:
    lat: 41.015137
    lng: 28.979530

Debug Settings

The "debug" property allows you to turn on debugging in the Angular UI. When enabled, your environment and all Redux actions/transfers are logged to the console. This is only ever needed if you are debugging a tricky issue.

config.*.yml

# NOTE: will log all redux actions and transfers in console
debug: false

All Versions

DSpace Documentation

Page tree

Overview

Configuration File Format

Configuration Override

Configuration Reference

UI Core Settings

Server Side Rendering (SSR) Settings

REST API Settings

Cache Settings - General

Cache Settings - Server Side Rendering (SSR)

Authentication Settings

Form Settings

Notification Settings

Submission Settings

Language Settings

Browse By Settings

Community-List Settings

Homepage Settings

Undo Settings

Item Access Labels

Item Page Settings

Community Page Settings

Collection Page Settings

Theme Settings

Bundle Settings

Media Viewer Settings

Uploading video captioning files

Toggle end-user agreement and privacy policy

Settings for rendering Markdown, HTML and MathJax in metadata

Controlled Vocabularies in Search Filters

Search settings

Geospatial map viewer settings

Debug Settings