METS Navigator

METS Navigator User Guide

Contents

Introduction

METS Navigator is an open source METS-based system for displaying and navigating sets of page images or other multi-part digital objects. METS, the Metadata Encoding and Transmission Standard, is a freely available XML standard, maintained by the Library of Congress, for managing and describing digital library objects. Using the information in the METS <structMap> elements, METS Navigator builds a hierarchical menu that allows users to navigate to specific sections of a document, such as title page, specific chapters, illustrations, etc. METS Navigator also allows simple navigation to the next, previous, first, and last page image or component part of a digital object. METS Navigator also makes use of the descriptive metadata in the METS document to populate the interface with basic descriptive information about the digital object.
METS Navigator is built using Java and open source Web technologies, including the Apache Struts Web Application Framework, the Castor Java & XML Data Binding libraries, and Ant, and runs under a Web application server such as Apache Tomcat.
METS Navigator was developed by the Indiana University Digital Library Program.

System Requirements

Server Requirements

METS Navigator is a 100% pure Java web application and runs in server environments that provide:
  • Java Runtime Environment (JRE) 1.4 or greater. Note that METS Navigator requires the Java SDK.
  • A Java Servlet container, such as Apache Tomcat, that supports the Servlet API Specification, version 2.2 or later, and the JavaServer Pages (JSP) Specification, version 1.1 or later. METS Navigator has been tested Tomcat 4.1.30 and 5.5.15.

Client Requirements

METS Navigator has been designed to support and exploit current web standards. METS Navigator works with current version browsers and has been tested successfully against the following browsers and operating systems:

Mac OS

  • FireFox 1.x
  • Internet Explorer 5.2
  • Mozilla 1.7
  • Safari 1.x

Linux 2.6 kernel

  • FireFox 1.x
  • Mozilla 1.7

Windows XP/2000

  • FireFox 1.x
  • Internet Explorer 5.5+
  • Mozilla 1.7
  • Netscape Navigator 7.x

Installation

Installation from Binary Distribution

Prior to installing the MetsNavigator package, install and configure the Run-Time environment.
Java
You need to install the Sun Microsystems Java 2 platform Standard Edition (J2SE), JRE or SDK version 1.4.0 or higher. The J2SE run-time can be downloaded directly from Sun via this page. Please refer to Sun's own installation and configuration instructions for the J2SE.
Servlet Container (Apache Tomcat)
At this time, MetsNavigator has been tested on Apache Tomcat 4.1.x or higher. Please download tomcat from Apache Jakarta Tomcat project page, and follow the accompanying instructions on how to install and configure it.
MetsNavigator is expected to work with other servlet containers that support servlet 2.3/JSP 1.2 and installation and configuration process should be similar to what is for Apache Tomcat. However, detailed instructions on these servlet containers are beyond the scope of this document.
Once the run-time environment requirements have been met, do the following to install the MetsNavigator package:
  1. Shutdown your application server, to keep it from prematurely trying to unpack MetsNavigator.
  2. Download the MetsNavigator package, and place the web-archive file metsnav.war in the application server webapps directory.
  3. Start up the servlet container and browse to the default collection packaged with MetsNavigator:
    http://yourserver:port/metsnav/default/welcome.do
    Accessing this URL will cause the application server to unpack the web archive file, creating a metsnav sub-directory below the server's webapps directory.
  4. [optional] You can delete the metsnav.war file from the server's webapps directory now.
Upon completion of the above steps, the MetsNavigator will be installed and ready to use. Also installed is a sample set of Mets files and a sample configuration. To play with the sample collection, simply follow the URL described earlier in this section. To install new collections into MetsNavigator, please refer to the next section.

Installation from Source Distribution

Source Compilation Requirements

Java
You'll need to install J2SE SDK 1.4.0 or higher. Please refer to last section for instruction on installing J2SE.
Apache Ant
Ant 1.6 or newer is required to compile the source code. Please follow the installation and configuration instructions in the Ant package to install it.
Castor [optional]
Castor 0.9.6 or higher is required if you want to perform Java XML binding directly from the METS schema file to create Java classes.
Apache Tomcat [optional]
Apache Tomcat 4.1.x or higher is optionally required to compile the source code. It is required if you want to test the MetsNavigator on your own Tomcat testing server.

Building and installing from Source with Ant

  1. Download the source distribution from MetsNavigator download page. Decompress the package into a local directory.
  2. [optional] If you want to test the MetsNavigator on your own testing tomcat server, or unit test the source codes, or generate Java files from Mets schema files, you need to rename the build.properties.sample file to build.properties and make changes to the file according to the instructions found in that file.
  3. Execute ant in the root directory of MetsNavigator source distribution, by entering ant in the command line.
  4. Several files will be created in the dist directory. Decompress the metsnavigator-[version].tar.gz or the metsnavigator-[version].zip file and follow the installation instruction for binary distribution to complete the process.
After installation of MetsNavigator, you may add your own collections to the system.

Adding collections to MetsNavigator

  1. Create a configuration file for your collection. See below.
  2. Copy your configuration file to the /metsnav/WEB-INF/metsnav/conf directory in the Tomcat webapps directory.
  3. Create a directory for your METS documents and copy your METS documents into that directory. This directory name must also be specified in the absolutePath or relativePath attribute in the dataSource <div> of the configuration file.
  4. Restart the Tomcat server.
  5. Visit your collection at http://yourserver:port/metsnav/[collectionName]/welcome.do, where [collectionName] is the name of your collection/directory specified in the relativePath configuration file.
  6. If this page is successfully loaded, there will be a list of Mets documents on the left part of the web page, and a welcome message in the middle-right part of the page.

Configuration

METS Navigator is designed to support multiple collections. Each unique collection requires an XML configuration file. Areas that require configuration for successful setup of a collection include:
Data Source
Sets the method to fetch and parse METS fils. The type of the DataSource must be specified in the "className" attribute. Two types of data sources are packaged in this release: edu.indiana.dlib.metsnav.config.FileSystemDataSource and edu.indiana.dlib.metsnav.config.URLDataSource.
  • The FileSystemDataSource is used when the METS file are loaded from the local file system of the server. This is also what the default sample collection included in MetsNavigator uses for data source. The Mets files can be put either inside the WEB-INF directory of the MetsNavigator web application, in which case a relativePath need to be specified in the configuration, or anywhere in the file system, in which case an absolutePath need to be specified in the configuration.
  • The URLDataSource can be used when the METS files are from a remote web server. When using the URLDataSource, the "oid" parameter in the URL to navigate images needs to be the URL to the remote METS file. For example, if using URLDataSource, the URL to navigate using a METS file at http://mets.file.server/my-mets-file.xml will be http://metsnav.server/metsnav/default/navigate.do?oid=http://mets.file.server/my-mets-file.xml. This feature allows MetsNavigator to be coupled with Fedora or any digital repository that can deliver METS file with a URL.
User Interface
Defines CSS style sheet, banner and footer contents, templates (currently only a default layout is available), labels for structural/hierarchical navigation, document- or item-level description, reciprocal link back to source or related website, and links for site navigation
Digital Image
Defines the various image sizes available for viewing

metsnav-config-default.xml

Following is a list of the parameters handled by the configuration file:
Data Source (FileSystemDataSource)
Parameter Value Notes
daoType edu.indiana.dlib.metsnav.dao.PersistentMetsFileDAO Default Value
relativePath /WEB-INF/metsnav/xml/[collectionName] This relative path points to where the METS documents will be stored for a particular collection. NOTE: Only relativePath or absolutePath may be used, not both.
absolutePath [absolute path to METS XML files, e.g. /data/mets/myCollection/] This absolute path points to where the METS documents will be stored for a particular collection. NOTE: Only relativePath or absolutePath may be used, not both.
metsVersion 1.5 or 1.4 Specifies the version of METS schema used by the METS documents. This parameter is optional. If not specified, the default value is 1.5
Data Source (URLDataSource)
Parameter Value Notes
daoType edu.indiana.dlib.metsnav.dao.PersistentMetsFileDAO Default Value
metsVersion 1.5 or 1.4 Specifies the version of METS schema used by the METS documents. This parameter is optional. If not specified, the default value is 1.5
Interface
Parameter Value Notes
cssLocation /css/[stylesheetName].css Each collection can have its own CSS or all collections can reference a generic CSS
bannerLogo /images/[logoName].[gif/jpg] Maximum logo height & width: 40 pixels by 80 pixels
bannerTitle [Website/Collection Title] Currently, only a text-based title is supported.
footerLastUpdated true/false Designate “true” to display last updated information in the footer
footerCurentURL true/false Designate “true” to display page URL in the footer
footerPublisher [institutionURL]; key=[institutionName] Multiple institutions or departments can be specified
footerFeedbackLabel [contactEmailAddress] For email address display
footerFeedbackAddress [mailto:emailAddress] Link to email address
templateLayoutName default Currently only one layout, default, is available
templateTileSetName default
linkBackURL [URL] Link to resource or application that launches the Navigator (e.g. OPAC, Finding Aid, etc.)
linkBackLabel e.g. [View Full Record] Label for link back to resource
siteNavigation [home] [homeURL] More than 1 link can be specified. They will appear in the order specified. No more than 7 site-level links are recommended.
Data Source
Parameter Value Notes
size [<mets:file>] A default size can be specified. Values are defined in the file/@USE attribute of the METS document. See explanation below.

Templates

METS Navigator templates define the layout and look of the web pages generated by METS Navigator. They are comprised of layouts, tiles and css style sheets. Currently, METS Navigator has only one layout, default.

Layouts

Layouts are XHTML skeletons that contain pre-defined content areas such as banner, footer, etc. This release contains one layout, default, that can be customized for a particular collection by defining interface parameters in the configuration file and creating CSS style sheet.

Tiles

Tiles contain the pre-defined content areas specified in the default layout. They are grouped into two categories: common and pages. “Common” contains the XHTML for the various bits that comprise a web page (e.g. banner, footer, etc.). The “common” files have been designed so that all customization happens at the configuration level. “Pages” contains the default, generic help page and the welcome page used for collection-setup troubleshooting. To add new pages to the site, such as an “about” page or custom “help” page, the following needs to occur:
  1. Make sure these links to new, internal pages are added in the configuration file under <siteNavigation>
  2. Create a collection-specific directory under /webapps/metsnav/. Make sure the naming convention is consistent with the collection name defined in the configuration file.
  3. Copy pagesTemplate.jsp ; rename to match site-level link defined in the configuration file under <siteNavigation>
  4. Modify new page with appropriate content
Currently, the welcome page for METS Navigator is designed to help implementers test and troubleshoot collection setup. If the collection is meant to be a stand-alone collection (e.g. not launched from another application), the home page will have to be customized following the above-outlined steps.

CSS Style Sheet

As much as possible, METS Navigator separates presentation and layout from content. Most presentation details (fonts, font sizes, font styles, heading styles, etc.) are specified in the METS Navigator default Cascading Style Sheet metsnavigator.css (/metsnav/css/), which is heavily commented to allow for easy modification by implementers. The default style sheet is provided as a template for collection-specific modification (e.g. collectionA.css).

Images

Images used for the collection website are saved in the images directory (/metsnav/images/). These images include:
Image Type File Name/Specification Notes
Logo Naming is flexible; logo is specified in the XML configuration file Maximum height and width of a logo is 40 pixels by 80 pixels.
Bullet Naming is flexible; bullet is defined in the CSS Maximum height and width of a bullet is 5 pixels by 5 pixels.
Background Image Naming is flexible; background images are defined in CSS Maximum height of a background image is 40 pixels for the banner area and 15 pixels for the site navigation area.
Spacer Transparent Image spacer.gif This is a transparent spacer image that is required; do not delete.
METS Navigator Logo metsNavLogo.gif This image is referenced in the footer; do not delete.
Collection-specific subdirectories are recommended for images such as logos, bullets, etc. under /metsnav/images/. Otherwise, all collection images would reside in one directory and would need to be identified by file naming conventions (e.g. collectionAbullet.gif, collectionBlogo.gif, etc.).

METS Documents for METS Navigator

METS Navigator currently assumes that each page within an item is represented by one or more image files of different sizes. Images may be in any still image format (e.g., GIF, JPEG, PNG) transmittable by the Web server in use and appropriate for the target audience.
All METS XML files loaded into METS Navigator must be valid to the METS Schema, version 1.4 http://www.loc.gov/standards/mets/version14/mets.xsd or 1.5 http://www.loc.gov/standards/mets/version15/mets.xsd. Elements from the METS Schema may either be indicated with a namespace prefix or by declaring a default namespace. Elements from other namespaces must be indicated with valid namespace prefixes.

<dmdSec>

METS XML files for METS Navigator may optionally contain one or more <dmdSec> elements. A <dmdSec> may be used to override the <linkBackURL> specified in the application configuration file. To do this, provide a <dmdSec> with the attribute <ID="dmdSec_fullRecordLink">, and a child <mdRef> with an xlink:href attribute containing a URL. This URL will appear as the target of the <linkBackURL> in the METS Navigator interface.
Other <dmdSec> elements may appear; however, they will be ignored by METS Navigator.

<fileSec>

METS XML files loaded into METS Navigator must contain at least one <fileGrp> element within the <fileSec> element. Each <file> element within a <fileGrp> must have the following attributes, in addition to any other attributes desired or required for a valid METS instance:
  • ID: This ID will be referenced from the <structMap> to provide the network location of a digital file for delivery in METS Navigator.
  • GROUPID: This ID will be used to connect a file in one <fileGrp> with the corresponding file of a different size in other <fileGrp>s.
  • USE: Each <file> element intended to be displayed by METS Navigator must have a USE attribute. In order to be displayed, this USE attribute must match a value specified in the <div name="digitalImage"><parameter type="list" name="size"><value> list in the METS Navigator configuration file. Other <fileGrp> elements with USE attribute values not indicated in the configuration file may be present; however, these files will be ignored by METS Navigator. All <file> elements within a <fileGrp> must have the same USE attribute.
Each <file> element must have a child <FLocat> element with the following attributes, in addition to any other attributes desired or required for a valid METS instance:
  • LOCTYPE: A value valid to the METS schema describing the link type in the xlink:href attribute.
  • xlink:href: A link to the image file of the specified size to be displayed by METS Navigator.
Each page image represented in the METS instance to be displayed by METS Navigator must be present as a <file><FLocat> element within each <fileGrp> with a USE attribute indicated in the application configuration file. The recursive features in the <fileSec> added in METS version 1.5 are not supported; <file> elements that are children of other <file> elements, <stream>, and <transformFile> are all ignored. All images that should be displayed by METS Navigator must be represented in <file> elements as immediate children of <fileGrp>.

Physical <structMap>

A <structMap> section with the attribute TYPE="physical" is required by the METS Navigator. The data within the <structMap TYPE="physical"> section is used to navigate from one page within the METS Navigator display to the next or previous page in the item.
Inside the containing <div> required by the METS schema, the physical <structMap> should contain one <div> for each page of the item(s) to be displayed, with no further nesting. Each of these <div> elements should have the following attributes, in addition to any other attributes desired or required for a valid METS instance:
  • ORDER: Order attributes should be numbered consecutively from 1 to the last <div> present.
  • TYPE: All <div> elements within the outer containing <div> in the physical <structMap> should have the attribute TYPE="page".
Each <div> element representing a page of the item(s) to be displayed should have one or more child <fptr> elements. One <fptr> element should appear for each of the different-sized images in the <fileSec>, referencing the ID of for the page described in the parent <div> in the FILEID attribute. Other <fptr> children may be present; however, METS Navigator will not use these in its display or functionality.

Logical <structMap>

A <structMap> section with the attribute TYPE="logical" is required by the METS Navigator. The data within the <structMap TYPE="logical"> section is used to build the “table of contents”-style navigation in the METS Navigator interface. The value of the LABEL attribute in the <structMap TYPE="logical"> element will appear in the upper left corner of the METS Navigator interface as a page title.
Inside the containing <div> required by the METS schema, the logical <structMap> should contain <div> elements, nested to represent any desired structure for navigation with the item(s) described by the METS document. <div> elements may be nested to any depth of hierarchy; however, the lowest level of hierarchy for each <div> must be one or more <div>s representing the pages of the item(s) to be displayed, matching each lowest-level <div> in the physical <structMap>. Any <div> must have as immediate children either only <div>s of type="page" or no <div>s of type="page".
Each of these <div> elements should have the following attributes, in addition to any other attributes desired or required for a valid METS instance:
  • ORDER: Order attributes should be numbered within the containing <div> consecutively from 1 to the last div present.
  • TYPE: Any value may be entered here; however, some values elicit specific behaviors in the METS Navigator interface.
    • Nodes with the value TYPE="ill" will have the string “[Illustration]” appended to the value in the LABEL attribute within the “table of contents”-style navigation box in the METS Navigator display.
    • Nodes with the value TYPE="plate" will have the string “[Plate]” appended to the value in the LABEL attribute within the “table of contents”-style navigation box in the METS Navigator display.
    • All page images described in the physical <structMap> must also be present in the logical <structMap>, as the lowest level of hierarchy within a <div>, and each of these must contain the attribute TYPE="page". Nodes with this TYPE will not be displayed in the “table of contents”-style navigation box.
  • LABEL: The value in this attribute will appear in the “table of contents”-style navigation box in the METS Navigator display as a hyperlink. When this hyperlink is clicked, the interface will navigate to the first page image within this <div> (the child element <div ORDER="1" type="page">).

Other considerations

In the current implementation of METS Navigator, no sections of the METS schema other than those discussed here are required. In addition to the elements and attributes required by METS Navigator, any other elements and attributes valid in the METS 1.4 or 1.5 Schema may be added to the METS document. METS Navigator will not, however, make use of this data in its display or functionality.

Sample Documents

METS Navigator is distributed with 3 sample documents to illustrate METS Navigator configuration options.

Release Notes

The following feature enhancements and bug fixes are included in the 1.0b_2 release of METS Navigator:

Additions and Changes

  • Added URL parameter "debug" for diagnosing
  • Collection level Linkback can be overwritten if there is a value in METS/dmdSec[@ID='dmdSec_fullRecordLink']/mdRef/@xlink:href in the METS file
  • Added logging functionalities using Log4J
  • Added timestamp for files (Class FileSystemDataSource). Now changes made to METS files will be automatically picked up if file is updated
  • Added "forceUpdate" parameter in URL. When this parameter appears, MetsNavigator will be forced to clear cache.
  • Added support for both METS 1.4 and METS 1.5.
  • Renamed default sample collection from "brittlebooks" to "sample".

Fixes

  • Fixed bug causing "alt" attribute of images to always say "null"

METS Navigator API Javadocs

The METS Navigator API Javadocs are available in a separate document: METS Navigator API Javadoc.

License

Software License, Version 1.0
©2005 Trustees of Indiana University. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
  1. All redistributions of source code must retain the above copyright notice, the list of authors in the original source code, this list of conditions and the disclaimer listed in this license;
  2. All redistributions in binary form must reproduce the above copyright notice, this list of conditions and the disclaimer listed in this license in the documentation and/or other materials provided with the distribution;
  3. Any documentation included with all redistributions must include the following acknowledgement:
    "This product includes software developed by the Digital Library Program at Indiana University. For further information contact the Digital Library Program at diglib@indiana.edu."
    Alternatively, this acknowledgement may appear in the software itself, and wherever such third-party acknowledgments normally appear.
  4. The name Indiana University or "METS Navigator" shall not be used to endorse or promote products derived from this software without prior written permission from Indiana University. For written permission, please contact Indiana University Research and Technology Corporation ("IURTC") at 351 West 10th Street, Indianapolis, Indiana 46202.
  5. Products derived from this software may not be called "METS Navigator", nor may "Indiana University," "Indiana University Libraries," or "Indiana University Digital Library Program" appear in their name, without prior written permission of IURTC.
Indiana University provides no reassurances that the source code provided does not infringe the patent or any other intellectual property rights of any other entity. Indiana University disclaims any liability to any recipient for claims brought by any other entity based on infringement of intellectual property rights or otherwise.
LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", "VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE. LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION GENERATED USING SOFTWARE.
Date: (unknown) . Author: Michelle Dalmau, David Jiao, Jenn Riley, and John A. Walsh.
Maintained by the Indiana University Digital Library Program :: Last Updated 18 September 2006
Comments: diglib@indiana.edu :: Copyright 2004-2005, The Trustees of Indiana University