Caveat Lector

Anybody who understands Java Server Pages will laugh herself sick at this post, but I’m writing it anyway because I don’t understand JSPs (much—I certainly understand more than I did a month ago!), and I doubt most DSpace admins do either.

And yet we’d like to add pages to our DSpace installs, and have them pick up the correct layout bits. The biggest and most obvious need is for tailored About pages; the About link in a standard DSpace install takes one to the DSpace home page. Not the worst possible choice, I suppose, but it’s far from ideal; DSpace is the software, not the service the institution is running, so why confuse users of the service by sending them to a site about the software? (If you run a webserver for others, you don’t send your About page to Apache.org, do you?)

So today I added About pages to my staging server. While it required a good bit of twiddling, it wasn’t nearly as bad as I thought; it worked my second try, and would have worked my first try except I forgot to upload dspace-web.xml.

I don’t know whether standalone JSPs work in a DSpace install; I didn’t try that route. There’s only one standalone JSP (index.jsp on the top level) in the install, so I didn’t think it wise to create another. Better to make my mods fit the existing system.

This means creating a Java servlet. Don’t panic; it’s not so bad. Servlets live in /src/org/dspace/app/webui/servlet. Copy a fairly simple one (I recommend LogoutServlet.java) to AboutServlet.java in the same folder. Then open AboutServlet.java and get rid of all the copyright cruft; this is your servlet, not Hewlett-Packard’s. Leave the import statements alone; you’ll probably leave a few you don’t need, but that’s harmless.

Now you want to create your AboutServlet class in that file. Here’s how mine ended up looking:

public class AboutServlet extends DSpaceServlet
{
    /** log4j category */
    private static Logger log = Logger.getLogger(AboutServlet.class);

    protected void doDSGet(Context context, HttpServletRequest request,
            HttpServletResponse response) throws ServletException, IOException,
            SQLException, AuthorizeException
    {
		JSPManager.showJSP(request, response, "/about/about.jsp");

    }

    protected void doDSPost(Context context, HttpServletRequest request,
            HttpServletResponse response) throws ServletException, IOException,
            SQLException, AuthorizeException
    {
        // Treat as a GET
        doDSGet(context, request, response);
    }
}

Basically three things happening here. One, DSpace is told how to log. Two, DSpace is told to run and fetch the file /about/about.jsp whenever this servlet is called with an HTTP GET request (which is what browsers do when you ask them to fetch a URL). Three, DSpace is told to treat an HTTP POST request just like an HTTP GET request. (For 99.9% of the pages somebody on my level of expertise will want to add to DSpace, this bit is optional, but it doesn’t hurt anything, so I left it in.)

Save file, close file, end of story with that file.

Now you need to tell Tomcat (or whatever you’re running) about the servlet you just made. You do this in the file /etc/dspace-web.xml. Scroll down past the stuff about filters (you won’t need it; at this level of expertise you’re not creating anything that needs authentication) to the listing of servlets. Add one:

  <servlet>
  	<servlet-name>about</servlet-name>
  	<servlet-class>org.dspace.app.webui.servlet.AboutServlet</servlet-class>
  </servlet>

If the long string of dots looks an awful lot like the long directory string I cited above—not coincidental. Note that the DSpace people kindly keep their servlet listings in alpha order; I recommend inserting your servlet in the appropriate location. Makes no difference to the computer, but it’s nice for human maintainers.

You need to add one more mapping: the servlet to the URL you want the servlet to answer to. Zip down to the servlet-mapping section and add a mapping:

  <servlet-mapping>
  	<servlet-name>about</servlet-name>
  	<url-pattern>/about</url-pattern>
  </servlet-mapping>

Again, alpha order is your friend.

Now you need to build the JSP that you told the servlet to run fetch. Do this in /jsp/local; I created a file /jsp/local/about/about.jsp. Again, it never hurts to copy another page, rip out the copyright notice and the guts, and go to town.

Notice the <dspace-layout> tag has a titlekey attribute. This sets the HTML title element for the page, so you’ll want to make it accurate. (The title element lives in /jsp/layout/header-default.jsp, so you can’t just add one to this page and have it work.) Make up a name for your new key (the dots are meaningless separators this time) and insert it as the attribute value, thusly: titlekey="jsp.about.title".

Now you need to go into /config/language-packs/Messages.properties and add a line that maps that name to what you want as the page title:

jsp.about.title = About [your brandname here]

Upload all this crud to your server in the right places (honestly, that’s the hardest part of this process!), run ant, copy the WAR, shut down and restart your Tomcat (or whatever) server, et voilà tout.

If your new page is missing pieces of the layout that you wanted there, there’s probably an attribute amiss in your dspace:layout tag. Easiest fix is to find the JSP for a page that has the correct layout pieces and copy whatever attributes its dspace:layout tag has. (I haven’t figured out all the attribute values yet, and they’re not documented. Life on the bleeding edge, what?)

I’m very proud of myself for figuring all this out. I’m also happy that now you don’t have to.