Adapting the Mirage Theme
The ELOGeo Project theme was based on a theme called ‘Mirage’ which features a left navigation and top breadcrumb trail. To this were added logos for the involved parties e.g. University of Nottingham and Mimas. The design used an orange and red colour scheme (Fig 1). The developers had utilised the Mirage theme which had not been renamed – just amended. To bring the ELOGeo repository into Jorum , we ran the risk that either the Mirage theme was already in use by another community or that because Mirage is a popular layout, another community may need to use the Mirage theme in the future. Our designers had moved away from the warm colours to a white, blue and grey scheme with green buttons (Fig 2). However, the actual layout is very similar to the older ELOGeo scheme with some alterations to spacing and other minor structural changes.
It would be necessary to adjust the main page layout adjust some style information and alter the structure of the HTML divs and in some cases assign ids or classes to the divs. Whilst doing this it made sense to rename our Mirage theme as ‘elogeo’ to reflect the repository name.
Renaming the theme
Renaming the theme, unfortunately was not as simple as just renaming the theme folder. Inside the theme directory is an XSL file named after the theme. This file name must match the directory name (and on some platforms this is case sensitive). It is also worth checking that the theme folder isn’t referenced anywhere in the theme files.
Some elements of the theme can be amended without rebuilding DSpace. Since the rebuild process can take a number of minutes, it is much faster to work on the live web application and copy back the changes to the source directory to be built later.
The XMLUI web application is based on the Apache Cocoon framework that incorporates caching. This cache must be cleared to view the development changes.
Edit the theme in [Tomcat Folder]/webapps/xmlui/themes/[themename]/lib/[xsl or CSS].
Clear the cache and restart Tomcat:
apache-tomcat-7.0.11/bin/shutdown.sh rm -rf [Tomcat directory]/work/Catalina/[domain]/xmlui/cache-dir apache-tomcat-7.0.11/bin/startup.sh
When DSpace is rebuilt again after any configuration changes, the webapps folder of the DSpace Build Directory will be overwritten. This means that the XSL and CSS style changes in the Tomcat webapps directory ([tomcat directory]/webapps will not have been incorporated in the new build. Changes to the live web application MUST be copied back from the Tomct webapps directory to the DSpace source directory.
cp -r [Tomcat Directory]/webapps/xmlui/themes/[theme name] [DSpace source directory]/dspace-xmlui/dspace-xmlui-webapp/src/main/webapp/themes
General theme structure
A Manakin (XMLUI) theme is composed of XSL and CSS files which can be readily amended. More in-depth customisations require changes to the theme’s aspects – which in this case we haven’t had to do.
Editing the Main Layout
The main layout of the interface is defined in the file page-layout.xsl. This determines how the content is translated into HTML. Any additions or alterations such as the order of divs, changing or adding classes and ids and inserting any static text or images is done my editing this file. The working file is at [Tomcat Directory]/webapps/xmlui/themes/elogeo/lib/xsl/core and this must be copied back to the DSpace source at [DSpace Source directory]/dspace-xmlui/dspace-xmlui-webapp/src/main/webapp/themes/elogeo/lib/xsl/core.
The main CSS style information is in [Tomcat directory]/webapps/xmlui/themes/elogeo/lib/css/style.css and again this must be copied back to the DSpace source if the changes are to survive a rebuild: [DSpace Source directory]/dspace-xmlui/dspace-xmlui-webapp/src/main/webapp/themes/elogeo/lib/css.
The Mirage theme main page structure accommodates a reasonable number of divs to contain the content. It can be difficult to work out which html structures are controlling elements such as the content width. In our case this was being set by the trail UL element width.
Opening the DSpace URL in Firefox gives the option under the menu Tools/Web Developer/Inspect to view the page structure and style. The style information can be edited in real-time. It is useful to see the structure of divs in the output and to identify which have an ID or class referenced by the CSS of the site.
Amongst other things, our design required moving the login link from the page header to the right hand side of the breadcrumb trail under the page header. Because the UL of the breadcrumb trail set the page width, these changes caused a number of issues with page flow. To assist in getting the page structure and flow correct, I built a simple test HTML page outside of DSpace with div ids mirroring the DSpace structure. I added inline style information under the style attributes of each element.
To accomplish the new design we had to insert some new divs into page-structure.xsl and to edit the style properties of a number of elements.When this page flow worked correctly, I updated the CSS attributes in the main style sheet.