RSS Feed

Manakin Install Documentation

DSpace 1.4.2, Manakin 1.1 release

Introduction

This is the DSpace XML UI / Manakin project installation guide. Manakin is the second release of the XML UI project's customizable DSpace interface and is currently under development by Texas A&M University in order to provide major improvements to the user interface of DSpace; the fundamental feature this project adds is the ability for each community and collection within DSpace to establish a unique look-and-feel, one that might extend outside of DSpace into an existing web presence.

Prerequisites

DSpace XML UI / Manakin is an add-on to the standard DSpace software. This means that before Manakin can be installed you must first install DSpace. For both DSpace and Manakin you will need the following prerequisites:

The DSpace installation manual covers installing & configuring these tools for use with both DSpace and Manakin.

Obtaining Manakin

Manakin may be obtained by either downloading a snapshot or checking out a version directly from Manakin's SVN repository. We recommend obtaining Manakin directly from SVN rather than an out-of-date snapshot. The list of available snapshots may be found on A&M's Digital Initiatives website.

The most current version can be checked out from SVN's main trunk:

  svn co https://svn.di.tamu.edu/svn/xmlui/trunk

Older, less unstable, versions can be checked out as a tag:

  svn co https://svn.di.tamu.edu/svn/xmlui/tags/<tag name>
  (list of available tags)

Installing Manakin

Step 1: Configure DSpace

Your dspace.cfg file needs to be updated to include specific Manakin configuration parameters. First you must supply information about your repository. There are also several optional configuration parameters you may wish to use.

Required: Provide some basic information to be included in every Manakin page about your repository. Add the following parameters to your dspace.cfg:

  #
  # Repository metadata
  #
  xmlui.repository.identifier = DSpace Manakin
  xmlui.repository.description = This is the default repository description
  xmlui.repository.publisher = Default DSpace publisher
  xmlui.repository.subject = Default repository subject
  xmlui.repository.title = DSpace XMLUI :: Manakin

Optional: You may configure Manakin to be optimized for a large community / collection hierarchy. In this case Manakin will forgo a full rendering for each community and collection object and instead will used a shortened version that just includes the container's name and a link to it's location. While this reduces the flexability & power provided to a theme it is recommended for repositories that have a large community list to improve performance.

  # Should full community/colection objects be rendered 
  # on the community-list page? The default is true.
  xmlui.community-list.render.full = false

Optional: (Almost no one needs to use this option) You may configure Manakin to use DSpace crosswalks when generating metadata. Using this feature would allow Manakin Themes to take advantage of additional metadata that may be present in your repository beyond the standard “Dublin Core”-based flat metadata. To configure these crosswalks add the following parameters to your dspace.cfg file:

  # List the dissemination crosswalks that Manakin 
  # should use for describing DSpace objects. 
  #
  # Format: xmlui.item.dmd =  <crosswalk name>:<METS name>, ...
  xmlui.mets.item.dmd = MODS:MODS
  xmlui.mets.collection.dmd = MODS:MODS
  xmlui.mets.community.dmd = MODS:MODS

In example above Manakin is configured to use the MODS crosswalk (which will generate MODS metadata of course). This value can be changed to any installed crosswalk. You can find a list of all installed crosswalks at plugin.named.org.dspace.content.crosswalk.DisseminationCrosswalk parametr in your dspace.cfg file.

Optional: (Almost no one needs to use this option) You may configure Manakin to take advantage of metadata stored as a bitstream on an item. These metadata files should be inside the "METADATA" bundle and named either "MODS.xml" or "METS.xml", at the present time only these two types of bitstream metadata formats are supported.

  # Use METS documents that are located
  # in an Item's "METADATA" bundle.
  xmlui.bitstream.mets = true
  
  # Use MODS documents that are located
  # in an Item's "METADATA" bundle.
  xmlui.bitstream.mods = true

Step 2: Configure Manakin

First, copy the theme and aspect configuration file config/xmlui.xconf from Manakin's source to your DSpace configuration directory. This file is used to configure which aspects and themes are installed on your Manakin / DSpace. By default the following Aspects are turned ON, to turn off any of them off just comment out the corresponding <aspect> element in xmlui.xconf.

  1. Artifact Browser:

    Responsible for browsing communities, collections, items, and bitstreams, viewing an individual item, and searching the repository.

  2. E-Person & Authentication:

    Responsible for logging in, logging out, new user registration, forgotten passwords, editing profiles, and changing passwords.

  3. Submission & Workflow:

    Responsible for submitting new items to DSpace, the workflow process, and finally ingesting the new items into the DSpace repository.

  4. Administration:

    Responsible for administrating DSpace, such as creating, modifying, and removing all communities, collections, e-persons, groups, registries, and authorizations.

  5. XML Test:

    Provides a set of test pages that exercise various features of Manakin.

Next, copy the front page news file, config/news.xml from Manakin's source, to your DSpace configuration directory. This file is used to place news items on Manakin's homepage. Edit this file to include any announcements that you would like displayed on the front page of your new Manakin installation.

Step 3: Configure Tomcat

Update Tomcat's conf/context.xml to include a parameter that tells Manakin where your dspace.cfg configuration is located. Modify the context.xml file to add the following element inside the <Context> element:

  <Parameter name="dspace-config"
     value="/absolute/path/to/dspace.cfg"
     description="Path to the DSpace configuration file." />

Modify the parameter's value to your particular environment; the value should be the absolute path to your dspace.cfg file.

Remember, Manakin requires Tomcat version 5.5.

Step 4: Compile & Deploy

Compile Manakin using an existing DSpace source tree to link against. Use the "dspace" ant parameter to tell Manakin where your DSpace source directory is, as follows:

  ant -Ddspace=/path/to/dspace/source  build_wars

This will create a manakin.war file in the build/ directory, to deploy Manakin simply copy this war file into Tomcat's webapps/ directory. Alternatively you may deploy using the deploy or tomcat-delopy tasks, see the ant build file for more information on these deployment methods.

Common Problems

Idealy everything would just work however sometimes even following the above steps exactly you will encounter problems installing Manakin. This section lists common problems that people encounter when installing DSpace, if you encounter a problem please report it to the DSpace Manakin email list. (Manakin email list archives)

After deploying it doesn't work, I get a blank page or Tomcat crashes.

This is the symptom of several initialization failures. Check the Tomcat log file for the precise error it encountered.

The page's header & footer appear but there is no content.

This usually means that no aspects were installed. First, check to make sure that the xmlui.xconf file exists inside your installed dspace configuration directory. Next, check to make sure that at least the ArtifactBrowser aspect is enabled in the xmlui.xconf file. Lastly, check the Tomcat log file for any error messages.

Appendix: Eclipse Development

Most Manakin developers, if not all, use Eclipse as a development IDE. This section covers some configuration hints specific to useing the Eclipse development platform with Manakin.

Subeclipse SVN

Subeclipse is an Eclipse plugin that provides a Subversion (SVN) client. This allows you to check out Manakin, make modifications, and recieve future updates easily. Installing the plugin is easy, just follow these step-by-step installation instructions with screen shots.

Java Build Paths

Manakin requires a complicated build path configuration. If it is not set up corrrectly then either you will not be able to take advantage of the java-centric features of Eclipse or most classes will appear to have compilation errors. To solve these problems do the following:

Assuming you have both a DSpace project and a Manakin project in your Eclipse Workspace.

  1. Select the Manakin project in the "Package Explorer".
  2. Right click on the Manakin project and select Properties.
  3. Select Java Build Path from the left hand list.

  4. Select the Source tab.
  5. Click the Add Folder... button.
  6. Check the following directories in the list:
    • aspects/ArtifactBrowser/src/
    • aspects/EPerson/src/
    • aspects/Submission/src/
    • aspects/Administrative/src/
    • aspects/XMLTest/src/
    • src/
  7. Click the Browse... button to select the Default output folder.
  8. Make the output folder be build/classes/, note you may need to create this new folder location. Then click ok.


  9. Select the Projects tab.
  10. Click the Add... button.
  11. Check box nekt to the DSpace project and click ok.

  12. Select the Libraries tab.
  13. Click the Add JARs... button.
  14. Select all jar files in the Manakin project.
  15. Click the Add JARs... button again.
  16. Select all jar files in the DSpace project.

  17. Finaly, when finished click ok to close the properties dialog box.

Using Ant Tasks

Use the external tools function to make deploying Manakin (and DSpace) a one-click operation. To do this you will need to set up a set of ant build tasks in Eclipse.

First, setup Tomcat's manager by following the manager's installation instructions on Tomcat's website.

Next, create a build.properties file along side the build.xml file inside the Manakin project. This file will contain all the properties needed by ant to build Manakin. Here is an example:

  # The name of the web application (aka, war file)
  war = manakin 

  # Where the DSpace source is located
  dspace = /path/to/dspace/source/

  # Tomcat connection parameters: url, username, and password. 
  manager.url = http://localhost:8080/manager/
  userid = your-tomcat-manager-name
  password = your-tomcat-manager-password

Then, setup Eclipses's external tools: select Run -> External Tools -> External Tools... from the main menu bar. You will want to create a new entry for all the commonly used ant tasks (i.e. ant clean, ant build_wars, ant tomcat-deploy, etc ...). For each of these tasks set the build file to: "${project_loc}/build.xml"; by using this buildfile these same tasks will work across multiple Eclipse projects. The other alternative is to create entries per each project. Before you finish make sure you click over to the targets tab and select the appropriate target for each task.

Finally, to run each of these build tasks just click the external tools icon in the menu bar (it looks like a green arrow with a tool box below it) and select the task. If you select your tomcat-deploy task then ant will compile your project, build the war file, and deploy it to your Tomcat all with just one click.

Web Tooling Platform (WTP)

The Eclipse Web Tooling Platform (WPT) is a set of tools for developing web applications in Eclipse. It promises lots of features, one of the major features is tight integration with Tomcat (or other application servers). This would allow a developer access to debug (i.e. step-by-step) web applications. The project is not complete and is still under development. I have been unable to get it to work with Cocoon and/or OS X, however if you have been able to make any progress in getting it to work please let the community know about your experience on the Manakin mailing list.

Oxygen XML Editor

Manakin has a lot of XML files, really a lot, from just plain .xml files, to .xsl files, to .xmap files, to .xconf files. All of them are in XML format and they are at the hart of what makes Manakin work. If you are going to be developing with Manakin it is beneficial to have a good XML editor. Unfortunately the default XML editor that comes with Eclipse doesn't provide much. There are several plugins to provide better XML support to Eclipse, some are free such as XMLBuddy, however the best plugin is the Oxygen XML editor. While Oxygen is not free it is cheap compared to other professional XML IDEs out there and offers reduced pricing for academic & home use. Beyond the ability to have syntax highlighting, tag completion, and auto indentation the major feature that Oxygen provides over other plugins is the ability to debug an XSL file step-by-step. This is very useful in theme development.

By default the Oxygen XML editor only recognizes a limmited set of file extensions for use with the XML editior. This set of extensions does not include .xconf or .xmap which are common file types in Manakin. You'll need to adjust the plugin's configuration to get it to recognize these types as XML. Instructions for how to modify this are on Oxygen's forums.