SUNScholar/XMLUI Theme/Tutorial

From Libopedia
Jump to navigation Jump to search
Back to XMLUI Theme

Introduction

The XMLUI is one of the web user interfaces available to DSpace, the other is the JSPUI.

The XMLUI is based on Manakin using COCOON pipelines and the DRI schema to render the HTML web pages.

This wiki page provides a brief overview of the technical properties of the XMLUI.

Theme Definition

  1. The Tomcat server is configured to use port 80 and 443.
  2. The Tomcat server is configured to use the XMLUI interface as default.
  3. The aspects (functionality) to be used are defined in the xmlui.xconf file.
  4. The XMLUI theme to be used is defined in the xmlui.xconf file.
  5. The XMLUI theme is rendered using a pipeline, expressed simply as: Java => SAXON => DRI => XML = ((XSL => XHTML) + CSS = HTML).

Theme Transformation Pipeline Sequence

Xmlui-overview.jpg

A Java file per aspect is created to form the DRI in an XML format.

ls -lR $HOME/source/dspace-xmlui/src/main/java/org/dspace/app/xmlui/aspect

The DRI XML is transformed via XSL to XHTML, using global transformers.

nano $HOME/source/dspace-xmlui/src/main/webapp/sitemap.xmap

The XML is further transformed via XSL to XHTML, using localised transformers, assuming you selected to use the clean "template" theme.

nano $HOME/source/dspace-xmlui/src/main/webapp/themes/template/sitemap.xmap

The XHTML files are styled per theme using CSS files.

ls -lR $HOME/source/dspace-xmlui/src/main/webapp/themes/template/lib/

Official Help

View the following for official DSpace Manakin help.

View the following for a better understanding of XMLUI Mirage theme design using the "modules" overlay method:

Development Tools

DRI (Digital Repository Interface) Schema

The DRI XML Document consists of the root element document and three top-level elements that contain two major types of elements.

The root element is: document.

The three top-level elements are:

  1. The meta element that contains all the document metadata.
  2. The body element that contains all the <div> elements for document content.
    1. For example: Community/Collection list (referenceSet), view (raw html) and update
    2. For example: Item list (referenceSet), view (simple or detailed table) and update.
  3. The options element that contains all the <list> document content navigational elements.
    1. For example: /login, /browse, /search, /advanced-search, /logout, /submission etc...

DRISchema.png

Detailed Information

https://wiki.duraspace.org/display/DSDOC5x/DRI+Schema+Reference
https://wiki.duraspace.org/display/DSDOC4x/DRI+Schema+Reference
https://wiki.duraspace.org/display/DSDOC3x/DRI+Schema+Reference

DRI2XHTML Transformers

The DRI is transformed into XHTML using XSL templates.

There are two main base templates you can use when creating an XMLUI Theme:

  • dri2xhtml - used in the generation of default Reference, Classic and Kubrick themes
  • dri2xhtml-alt - used in the generation of default Mirage theme

You only should use one of these two templates, based on which seems easier to you, or none and create your own, you choose.

DRI Expression

You can view the DRI (Digital Repository Interface) elements as follows per page by prepending DRI/.

http://scholar.sun.ac.za/DRI/
http://scholar.sun.ac.za/DRI/discover
http://scholar.sun.ac.za/DRI/statistics-home

XML Expression

You can view the XML elements as follows per page by appending ?XML.

http://scholar.sun.ac.za/?XML
http://scholar.sun.ac.za/discover?XML
http://scholar.sun.ac.za/statistics-home?XML

Theme path

A new feature in DSpace versions => 1.5 is the ability to try out different themes on a particular page without having to mess with the xmlui.xconf file or needing to restart Tomcat.

Two things need to be done in order to apply a theme to any page you are currently looking at.

  1. The following setting in dspace.cfg must be set to true: xmlui.theme.allowoverrides
  2. The "?themepath=" value should be appended to the end of the url. See examples below.
http://scholar.sun.ac.za/?themepath=Classic/
http://scholar.sun.ac.za/?themepath=Reference/
http://scholar.sun.ac.za/?themepath=Mirage/
http://scholar.sun.ac.za/?themepath=Mirage2/
http://scholar.sun.ac.za/?themepath=Kubrick/
http://scholar.sun.ac.za/?themepath=mobile/

Now check all themes by rendering the discovery search page/aspect only.

http://scholar.sun.ac.za/discover?themepath=Classic/
http://scholar.sun.ac.za/discover?themepath=Reference/
http://scholar.sun.ac.za/discover?themepath=Mirage/
http://scholar.sun.ac.za/discover?themepath=Mirage2/
http://scholar.sun.ac.za/discover?themepath=Kubrick/
http://scholar.sun.ac.za/discover?themepath=mobile/

Combined Expression

Now lets combine expressions as follows.

http://scholar.sun.ac.za/DRI/?themepath=Classic/
http://scholar.sun.ac.za/DRI/discover?themepath=Classic/
http://scholar.sun.ac.za/DRI/statistics-home?themepath=Classic/

Item View

Each item is also rendered with METS metadata. See examples below.

http://scholar.sun.ac.za/metadata/handle/10019.1/79321/mets.xml
http://scholar.sun.ac.za/metadata/handle/10019.1/4815/mets.xml
http://scholar.sun.ac.za/metadata/handle/10019.1/4815/mets.xml
http://scholar.sun.ac.za/metadata/handle/10019.1/17774/mets.xml

Getting at the raw XHTML

Moving further down the pipeline, once the XSL templates have been applied and DRI has been converted into XHTML, CSS rules can be applied to the result in order to impart a specific look and feel to the theme. This is the point where Tier 1 development usually begins. When editing the CSS, Manakin theme development is much like any Web development project. You start out with XHTML, a blank CSS and possibly a design in mind, and work with the CSS until the results are satisfactory.

Getting at the raw XHTML output of the XSL processor is easy: all browsers allow the user to look at the page source and save a copy. While the underlying HTML varies for any given DSpace page, the top-level structures like body and header remain consistent. One technique is to go through DSpace page by page, look at the HTML, and create CSS rules as necessary. Alternatively, you can extend the Reference theme that contains CSS selectors for nearly all elements encountered in the HTML structures of Manakin DSpace.