SUNScholar/XMLUI Theme/Tutorial
Back to XMLUI Theme
Contents
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
- The Tomcat server is configured to use port 80 and 443.
- The Tomcat server is configured to use the XMLUI interface as default.
- The aspects (functionality) to be used are defined in the xmlui.xconf file.
- The XMLUI theme to be used is defined in the xmlui.xconf file.
- The XMLUI theme is rendered using a pipeline, expressed simply as: Java => SAXON => DRI => XML = ((XSL => XHTML) + CSS = HTML).
Theme Transformation Pipeline Sequence
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.
- https://wiki.duraspace.org/display/DSPACE/Manakin+theme+tutorial
- https://wiki.duraspace.org/label/DSPACE/manakinhowto
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:
- The meta element that contains all the document metadata.
- The body element that contains all the <div> elements for document content.
- For example: Community/Collection list (referenceSet), view (raw html) and update
- For example: Item list (referenceSet), view (simple or detailed table) and update.
- The options element that contains all the <list> document content navigational elements.
- For example: /login, /browse, /search, /advanced-search, /logout, /submission etc...
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.
- The following setting in dspace.cfg must be set to true: xmlui.theme.allowoverrides
- 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.
