Tuesday, December 23, 2008

Customizing DSpace v1.5.1

Prior to version 1.5.1 of DSpace, customization was done using a separate project called Manakin. The name persists within DSpace, including DSpace documentation, but actually it is all integrated now and customization is done in the dspace tree, not some separate project.

Details on how to customize dspace are very thin on the ground and most talk about how to do it when it was the separate Manakin project. I have managed to find something that works for me. Here's how I did it:

  • Stop tomcat.
  • Delete the tomcat dir webapps/xmlui.
  • go to the dir in which you unpacked dspace. My dir is called dspace-1.5.1-src-release.
  • Go to the sub-dir where the themes are stored. The documentation I found leads you to the wrong place. I found I had to go to dspace-xmlui/dspace-xmlui-webapp/src/main/webapp/themes.
  • Copy the dir that is closest to the theme you want. Copy the whole dir to a new target theme name. The one I copy is Reference.
  • This next step is CRUCIAL - edit sitemap.xmap to make it refer to the new theme name. If you don't then it will still refer to Reference! You need to go to the map:components section near the start. There you will see a section that looks like this:
            <theme-name>put your theme description 
    Change Reference and update the comment.
  • Edit dspace/config/xmlui.xconf. Go to the end where you will see the path defined for the default theme. It is Reference/. Note the trailing slash, it is important. Change Reference for your theme name.
  • Change something in your theme dir so that the change will be visually obvious. For example you can change the style sheet to refer to a different background image.
  • Rebuild dspace with these theme changes. Use the command 'mvn package'. This builds to [dspace-src]/dspace/target.
  • Update the dspace installation (which is in c:\dspace for me). Use the command 'ant update'.
  • copy the dir dspace/webapps/xmlui to the tomcat webapps dir.
  • Restart tomcat.

No comments: