Old Release

This documentation relates to an old version of DSpace, version 6.x. Looking for another version? See all documentation.

Support for DSpace 6 ended on July 1, 2023.  See Support for DSpace 5 and 6 is ending in 2023

The DSpace digital repository supports two user interfaces: one based on JavaServer Pages (JSP) technologies and one based upon the Apache Cocoon framework (XMLUI). This chapter describes those parameters which are specific to the JPSUI interface.


The user will need to refer to the extensive WebUI/JSPUI configurations that are contained in JSP Web Interface Settings.

Customizing the JSP pages

The JSPUI interface is implemented using Java Servlets which handle the business logic, and JavaServer Pages (JSPs) which produce the HTML pages sent to an end-user. Since the JSPs are much closer to HTML than Java code, altering the look and feel of DSpace is relatively easy.

To make it even easier, DSpace allows you to 'override' the JSPs included in the source distribution with modified versions, that are stored in a separate place, so when it comes to updating your site with a new DSpace release, your modified versions will not be overwritten. It should be possible to dramatically change the look of DSpace to suit your organization by just changing the CSS style file and the site 'skin' or 'layout' JSPs in jsp/layout; if possible, it is recommended you limit local customizations to these files to make future upgrades easier.

You can also easily edit the text that appears on each JSP page by editing the Messages.properties file. However, note that unless you change the entry in all of the different language message files, users of other languages will still see the default text for their language. See Internationalization in Application Layer.

Note that the data (attributes) passed from an underlying Servlet to the JSP may change between versions, so you may have to modify your customized JSP to deal with the new data.

Thus, if possible, it is recommended you limit your changes to the 'layout' JSPs and the stylesheet.

The JSPs are available in one of two places:

  • [dspace-source]/dspace-jspui/dspace-jspui-webapp/src/main/webapp/ - Only exists if you downloaded the full Source Release of DSpace
  • [dspace-source]/dspace/target/dspace-[version].dir/webapps/dspace-jspui-webapp/ - The location where they are copied after first building DSpace.

If you wish to modify a particular JSP, place your edited version in the [dspace-source]/dspace/modules/jspui/src/main/webapp/ directory (this is the replacement for the pre-1.5 /jsp/local directory), with the same path as the original. If they exist, these will be used in preference to the default JSPs. For example:

DSpace default

Locally-modified version





Fonts and colors can be easily changed using your own style sheet. Place a style sheet in [jsp.custom-dir]/dspace/modules/jspui/src/main/webapp/static/css/] Include a link to the style sheet in all JSP file where you want to use it. The style sheet styles.css is there mainly for legacy reasons. It is used only for the help popup, controlled vocabulary popup and header popup.

The 'layout' of each page, that is, the top and bottom banners and the navigation bar, are determined by the JSPs /layout/header-*.jsp and /layout/footer-*.jsp. You can provide modified versions of these (in [jsp.custom-dir]/dspace/modules/jspui/src/main/webapp/layout), or define more styles and apply them to pages by using the "style" attribute of the dspace:layout tag.

The basic branding of the public pages of the repository is possible editing the header-default.jsp file and specifically the "container banner" div https://github.com/DSpace/DSpace/blob/dspace-6_x/dspace-jspui/src/main/webapp/layout/header-default.jsp#L133 this banner is shown in all the public page but hide in "backend functionalities" to allow more space for the functionality itself.

For the backend pages, both administrative than "registred user", you should edit the header-submission.jsp.

To change colors, fonts and CSS settings in general It is preferable to generate a new bootstrap.css using the tool provided by the bootstrap creator here: https://getbootstrap.com/docs/3.3/customize/ or choose one of the several themes available for bootstrap online, like the freely available provided by bootwatch

  1. Rebuild the DSpace installation package by running the following command from your [dspace-source]/dspace/ directory:

    mvn package
  2. Update all DSpace webapps to [dspace]/webapps by running the following command from your [dspace-source]/dspace/target/dspace-installer directory:

    ant -Dconfig=[dspace]/config/dspace.cfg update 
  3. Deploy the the new webapps:

    cp -R /[dspace]/webapps/* /[tomcat]/webapps
  4. Restart Tomcat
    When you restart the web server you should see your customized JSPs.

Styling the Simple Item View

DSpace offers following CSS classes in the HTML output to style metadata labels and values in the simple item view, :

  • metadataFieldLabel
  • metadataFieldValue

Each label and value gets enhanced by a CSS class identifying the metadata field by its schema, element and qualifier. The pattern for this classes is: schema_element_qualifier. Examples:

  • Select the CSS classes metadataFieldValue and dc_title to style the title element.
  • Select the CSS classes metadataFieldValue and dc_description_abstract  to style the abstract element
/* Make title bold */
.metadataFieldValue.dc_title { 
    font-weight: bold;

/* Make abstract italic and enforce the display of its line breaks */
.metadataFieldValue.dc_description_abstract {
    white-space: pre-line;
    font-style: italic;
  • No labels