Adding Viewer Links

The TDS adds Viewer Links to datasets at the bottom of a dataset's HTML web page, for example:

Viewers

Currently, the TDS automatically adds a NetCDF-Java Tools link to any direct dataset that has an ID. It adds an IDV link to any dataset that has an OPENDAP service, and has a DataType of GRID.

You can add your own viewer links in these ways:

  1. Adding a property element to each dataset, explicitly listing the URL of the viewer
  2. Creating a Java class that tells the TDS what datasets are viewable, and what HTML fragment to include.

Adding a property element

This method is available in TDS version 3.17+.

Adding a static viewer link

To add a viewer link to a specific dataset, add a property element to the dataset in the configuration file, for example:

  <dataset name="Test Viewer" ID="testViewer" serviceName="dapService" urlPath="test/testData.nc" dataType="Grid">
    <property name="viewer" value="http://www.unidata.ucar.edu/staff/caron/,MyViewer"/>
  </dataset>

The name of the property must be "viewer"and the value must be the viewer link, a comma, and then the viewer name. The actual HTML fragment that is placed into the web page is

    <a href='"+viewerLink+"'>"+viewerName+"</a>

Using inheritence to add viewer links to many datasets

By placing the property in an inherited metadata element, one can make it appear on all children of the dataset. This is espcially useful in conjuction with the datasetScan element. For example:

<datasetScan name="Test all files in a directory" ID="testDatasetScan" path="testAll" location="content/testdata">
  <metadata inherited="true">
    <serviceName>allServices</serviceName>
    <dataType>Grid</dataType>    
    <property name="viewer" value="http://www.unidata.ucar.edu/staff/caron/,MyViewer"/>
  </metadata>
</datasetScan>

Adding the Dataset URL to the Viewer Link

You may need to include the dataset URL into the viewer link. If there is a single service for the dataset, you can place "{url}" into your viewer link, and the Dataset's access URL will be substituted for it:

  <dataset name="Test Viewer2" ID="testViewer2" serviceName="dapService" urlPath="test/testData.nc" dataType="Grid"
    <property name="viewer" value="http://localhost:8080/thredds/cdmValidate?URL={url},Validation Service"/>
  </dataset>

will create a URL like:

  http://localhost:8080/thredds/cdmValidate?URL=http://localhost:8080/thredds/dodsC/test/testData.nc

Selecting one of the Dataset access URLs

When a Dataset has more than one kind of access, each access will have a seperate URL. Use the service name inside of curly brackets to select which access URL to use: 

<datasetScan name="Test all files in a directory" ID="testDatasetScan" path="testAll" location="content/testdata">
  <metadata inherited="true">
    <serviceName>allServices</serviceName>
    <dataType>Grid</dataType>    
    <property name="viewer" value="http://localhost:8080/thredds/cdmValidate?URL={HTTPService},Validation Service"/>
  </metadata>
</datasetScan>

Create a Viewer implementation Java class

This method is available in TDS version 3.14+.

This technique gives you full control over whether your viewer link appears, and what the URL looks like. You must create a Java class which implements the thredds.servlet.Viewer interface: 

public interface Viewer {
 (1) public boolean isViewable( thredds.catalog.InvDatasetImpl dataset);
 (2) public String getViewerLinkHtml( InvDatasetImpl ds, HttpServletRequest req);
}
  1. Your class is passed a thredds.catalog.InvDatasetImpl object, and it returns true if it is viewable by your viewer.
  2. Your class is passed a viewable thredds.catalog.InvDatasetImpl, and it must return a well-formed HTML string that has an href link in it.

Example:

package my.package;
include thredds.catalog.*;


public class IDV implements Viewer {
 public boolean isViewable( InvDatasetImpl ds) {
   InvAccess access = ds.getAccess(ServiceType.DODS);
   if (access == null) access = ds.getAccess(ServiceType.OPENDAP);
1) if (access == null) return false;

2) return (ds.getDataType() == DataType.GRID);
 }
 public String getViewerLinkHtml( InvDatasetImpl ds, HttpServletRequest req) {
   InvAccess access = ds.getAccess(ServiceType.DODS);
3) if (access == null) access = ds.getAccess(ServiceType.OPENDAP);
4) URI dataURI = access.getStandardUri();
   try {
     URI base = new URI( req.getRequestURL().toString());
5)   dataURI = base.resolve( dataURI);
   } catch (URISyntaxException e) {
     log.error("Resolve URL with "+req.getRequestURL(),e);
   }

6) return "<a href='/thredds/view/idv.jnlp?url="+dataURI.toString()+"'>Integrated Data Viewer (IDV) (webstart)</a>";
 }
  1. Requires there to be OPeNDAP access for the dataset.
  2. Requires the dataset to be of DataType.GRID.
  3. Get the OPeNDAP access object for the dataset.
  4. Get the access URI.
  5. Resolves the access URI against the request, which turns it into an absolute URI
  6. Forms the HTML string to be placed on the dataset's TDS web page. Note that is has an href embedded in it, which will be displayed in this example as:

    Integrated Data Viewer (IDV) (webstart)

Referencing an external URL

If the viewer you want to reference is not part of the TDS, just make the href absolute, eg:

 <a href='http://my.server/viewer?url=http://motherlode.ucar.edu:8080/thredds/dodsC/model/data.grib2'>My Server</a>

In this example, the server would see the OPeNDAP data access URL and remotely read it.

Returning a JNLP file

The IDV example returns a JNLP file, which allows the IDV client program to be automatically started through Java Webstart. If you have a webstart-enabled viewer, you can also get the TDS to return your own JNLP file. To do so:

  1. The returned URL should start with /thredds/view/
  2. The remaining part of the URL (before the ?) is the name of a JNLP template file in the ${tomcat_home}/content/thredds/views/ directory.
  3. The JNLP template file is processed in the following way:
    1. Each parameter in the URL is read as a name=value pair (in the example, there is one parameter, whose name is url and value is http://motherlode.ucar.edu:8080/thredds/dodsC/model/data.grib2).
    2. The JNLP template file is searched for strings of the form {name}, and the corresponding value is substituted into it (in the example, all strings of the form {url} would be replaced by http://motherlode.ucar.edu:8080/thredds/dodsC/model/data.grib2).
  4. Once the JNLP template file is processed, it is sent as the response to the user clicking on your link. If they have webstart installed, the application named in the JNLP file is downloaded (if necessary) and started up.

Example:

This is an approximately what is used in the IDV JNLP file. Note that the {url} string on the boldface line is replaced by the actual data access URL. This will create a command line argument -data type:opendap.grid:http://motherlode.ucar.edu:8080/thredds/dodsC/model/data.grib2 and pass it to the IDV application. 

<?xml version="1.0" encoding="utf-8"?>
<!-- JNLP File for Integrated Data Viewer -->
<jnlp spec="1.0+" codebase="http://www.unidata.ucar.edu/software/idv/webstart/">
  <information>
    <title>Integrated Data Viewer</title>
    <vendor>Unidata</vendor>
    <homepage href="http://www.unidata.ucar.edu/software/idv/index.html"/>
    <description>Integrated Data Viewer(IDV)</description>
    <description kind="short">A tool for geoscientific analysis and visualization.
    </description>
    <icon href="IDV/idv.gif"/>
    <offline-allowed/>
  </information>
  <security>
   <all-permissions/>
  </security>
  <resources>
   <j2se version="1.4+" max-heap-size="512m"/>
   <jar href="IDV/idv.jar"/>
   <extension name="IDV Base" href="IDV/idvbase.jnlp"/>
  </resources>
  <application-desc main-class="ucar.unidata.idv.DefaultIdv">
   <argument>-data</argument>
   <argument>type:opendap.grid:{url}</argument>
  </application-desc>
</jnlp>

Loading your class at runtime

You must place your Viewer class into the ${tomcat_home}/webapps/thredds/WEB-INF/lib or classes directory. (Previous instructions to place it into the ${tomcat_home}/shared directory doesn't work, because of classloader problems).

Then tell the TDS to load it by adding a line to the ${tomcat_home}/content/thredds/threddsConfig.xml file, for example:

  <viewer>my.package.MyViewer</viewer>
This document is maintained by John Caron and was last updated on Oct 23, 2008