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.

Like the rest of us Stateside I’m sure, I’ve been watching the aftermath of Katrina with queasy horror. Beyond words.

I’ve also seen hints of a lot of generosity. Sure, the give-to-charity type is all over the place, but that isn’t actually what I mean. I’m talking about someone taking in an abandoned greyhound, someone else saying “Stay with me; I have room,” others picking up and heading south on no notice.

I don’t know anyone on the Gulf Coast. The only time I ever saw New Orleans was at the age of eight, when my parents insanely drove from North Carolina to Laredo to pick up a train into Mexico. (I’m serious. They did. It was insane.)

That doesn’t mean I have no responsibility to help. It just means I’m limited to help-by-proxy, faceless help; I can’t offer a flesh-and-blood hand if I’ve no one to offer it to. As it turns out, I do better with helping when I can offer a hand, make a human connection. I daresay I’m not alone in that. I also say that I don’t find it particularly praiseworthy; need is need, and limiting my response to need is not what I hope of myself.

I suppose that’s why I don’t talk here about the occasions on which I do extend my hand. Partly that shame, partly others’ privacy, partly a (salubrious, I’m sure) reluctance to claim virtue.

I’ve a story to tell, just now, aimed at someone on the other side of my outstretched hand. I hope the rest of you will forgive the indulgence.

It was years before my mother accepted David. Years. She had her reasons—at least, the ones she told me about. Honest or not (and to some extent they were), those reasons were not the entire story. David was my freedom, many years ago. David taught me how to build an independent spirit, and I don’t know that my mother ever quite got used to that, either.

I think she knew how it happened, though. I do think she knew.

As the days counted down before my departure for Madison to start graduate school, everyone in the house knew what the plans were, but none of us dared say anything. Peace was like that, in our family: artificial, bounded by thick slabs of silence. I was racking my brain trying to sort out how to move us and our stuff, given that we didn’t live in the same city and I didn’t drive. And how to do this without material assistance from my parents—well, that bordered on impossible.

So finally, one sweaty-hot July morning, I marched myself out to the garden where my parents were working, and I came clean. I tell you three times, it’s the hardest thing I’ve ever done. Leaving grad school was a cinch by comparison (of course, I was so beaten down by the time I left that really there wasn’t much else I could do).

In the pictures, these scenes always carry dignity. Well, I didn’t. I was crying and gulping for air and sweating bullets and doubtless looking a right sorry specimen. But for once in my sorry excuse for an adult life, I didn’t ask permission; I told them what I was going to do.

My mom had a way of smacking me down in my teenage years, whenever I came close to asserting myself. Only once did she ever actually hit me, and this was not that time (but I remember that time, yes, I do). She’d just say something deeply cutting and completely unanswerable, shocking me into stunned silence. This time, she said, “So what do you want from us? Our blessing?”

That made me stammer, more than a little. I certainly hadn’t envisioned asking for, much less receiving, any such thing. I knew better. Finally, I got hold of myself long enough to say that no, I didn’t want any blessing they weren’t willing to give; all I wanted was their help packing and moving.

And what do you know, I got it, essentially without further argument.

My parents and I have kept a careful arms-length distance ever since. One thing I have never done since that day is accept money from them, though we could have used it in those early years. Mom offered. Repeatedly. But it was easier to live the grad-mouse lifestyle than attach the marionette strings. (I paid for both my master’s degrees. My parents paid for both of my sister’s—and she still lives at home. Coincidence? Well, it’s always more complicated than joining point A and point B… but no, I’m sorry, it’s not mere coincidence.)

What it comes down to is that yanking myself free hurt like the devil and scared me silly. I did, however, survive it, and I have never had reason to regret doing it.

The same will be true of the person I’m writing this story for. I offer the story, then, along with my hand.

In response to my quick note of a “librarian shortage” in England, Colin Robertson said (quoted by permission):

The article with the 59% figure was referring to public libraries only. Those are government funded, and I’m willing to bet that the salaries they offer are not very competitive with what someone with those same librarianship skills might receive elsewhere… If the salaries are lower in the public sector then that difficulty filling positions is exactly what you’d expect to see, but it wouldn’t mean that there was a shortage of librarians.

Quite correct. There’d just be a shortage of librarians willing to be underpaid, which in my book is only right and proper.

Not English, have no especially efficient way to check this out, but would be interested to see followup. I’ve said before that demand in excess of supply is the only way to drive our prices up; I hope that’s what happens for our English compatriots.

After all the frustration last week, I solved the JScript/JSP problem in ten minutes this morning. Turned out to be a bit more fallout from that HTML-attribute-quoting regex.

How’d I find the problem? Pulled up my version of the Javascript file along with a clean version and ran a diff on them. Badabing-badaboom, there was the problem.

I felt amazingly stupid, but at least the problem got fixed. You see what not quoting your HTML attributes does? You see, now? You mess with the markup wonks’ heads, that’s what you do when you don’t quote your HTML attributes. (Oh, and I discovered that the supposed HTML 4 that DSpace emits… isn’t, in a couple of places. You can imagine how thrilled I am to find that out.)

Anyway, I then ran into another problem associated with this bug. For the record, the listed fix may not work if your first form is in a piece of the page that does appear in the Administer EPeople page but doesn’t appear in the e-person popup. Reason: the form with the buttons is the second form on the Admin EPeeps page, but the first form in the popup, so the JavaScript gets confused either way. (Surely there’s a way to name/address forms in JavaScript so as to avoid this problem?)

In my own case, I had a search form in the location bar, which did (note tense!) appear in the Admin EPeeps page, but didn’t appear in the popup. The fix, of course, is to kill the location bar out of the Admin EPeeps page, which I did. And then everything worked.

I wrote up this fix for the DSpace wiki, but it can’t hurt to post it here too.

My next fix: the abominable buttons on the submit-an-item pages (submit/progressbar.jsp, for those of you who know DSpace). As I explained somewhat incoherently previously, DSpace 1.2 had a series of small colored text-as-graphics that let a submitter know where s/he was in the submission process and which steps could be jumped to at this point in the submission game.

These text-as-graphics disappeared in 1.3, presumably because it’s impossible to internationalize text-as-graphics. (Nota bene, web designers: if you’ll ever have to internationalize anything, hunt down all your text-as-graphics and kill it.) They were replaced with buttons, identical buttons all the way across. No clue which button represented the step the submitter was on. Worse, buttons representing stages that were off-limits at that point in the submission process were not clickable, with no indication what the difficulty was.

Basic, basic usability: if it’s clickable, users will try to click it, ergo it should do something. Unclickable buttons are a wretched, terrible thing to foist on users.

I fixed it. I de-buttonized everything that shouldn’t ever have been a button to begin with. Via CSS, I turned the current step green, and non-reachable steps white with a grey border. I separated all the buttons with pipes, too, because to my admittedly not-brilliant eye for design, the buttons looked horribly crowded. It’s not ideal, but it’s miles and miles better than the default.

Final fix: moving the bitstream (file) listing above the fold on the simple item-display page. Again, basic usability at work: a goodly portion of the time, someone arriving at an item-display page is looking for the bloody files. They’re new information. They should therefore be displayed prominently, below the title (for recognition purposes) but above all the other metadata (which there’s a goodly chance the user has already seen anyway).

While I was at it, I got rid of the filenames from the item listing, because who cares? Nobody’s going to choose a file based on its filename. Moreover, if they can’t see the filename, they’re less likely to try to cite it (instead of using the handle as they ought to). If they’ve just gotta know the filename, they can hover over the link like everybody else who uses a web browser.

So I fixed four things today, and I didn’t break anything that I’m aware. It was a good day.

I think it must be worse, to know this is coming. Many disasters are pure shock and adrenaline. This one is dread.

The katydids cheerfully making noise outside don’t know, and I envy them that. I wish I didn’t know. I wish I couldn’t imagine.

The last hope is the eyewall temporarily collapsing at the right time, as I understand matters. I will hope for that.

Katrina looks nasty. I hope the best for New Orleans and her people. I find myself checking the forecasts every couple of hours, hoping the storm will turn aside or weaken. No such luck yet.

I asked David to dig out the old red ledger that I quit using for expense-tracking back in 2001. Time to start that up again; I need to figure out what our baseline expenses are these days. It’s not so much that I’m worried (though I do wish our Madison house would sell); it’s just that my money-sense is all discombobulated and I want to get it back.

I’m hoping we can buy something around here. Eventually. Right now, even when the Madison house sells, anything we’d want is pretty much out of our league. It’s almost amusing, the way I seem to manage to land us places we make half the local median income.

Eh, well. Half the local median income around here actually isn’t too bad; and I’ve been making do on half for so long that I suspect I’ll manage.

With the help of the old red ledger.

That Javascript/JSP interaction that I broke and was trying to fix? Is still broken.

Getting kicked out of your office for half the day will do that.

No, no, not my fault. Power outages are frequent in my building—this is the third or fourth since I started—and today’s apparently shut off the ventilation fans in one of the kitchens. Nobody noticed the fans were out until a substantial part of the building was smoke-choked.

So, yeah, I got next to nothing technical done today (though I did accomplish two or three PR tasks that were hanging fire). Did have a nice lunch with colleagues, though, which is worth something.

And nobody was hurt and nothing major was damaged, which is worth more.

I was pointed to this article which claims an actual (actual, not pie-in-the-sky projected) shortage of librarians in England. The key statistic to my mind: “59% [of library authorities surveyed] saying they already have difficulty filling vacancies.”

If you look a little further down, you notice a claim that professional (degreed) librarians and manager-level people are the hardest to find. I half wonder if this isn’t fallout from a phenomenon that a number of us Stateside have already blogged or written about: when entry-level librarian jobs get deskilled, new librarians go jobless, reducing the pool of people to groom for leadership positions.

All in all, this article isn’t enough to change my mind about the job prospects for librarians Stateside. For the next few years, said prospects are lousy, and the “librarian shortage” hoopla is just that. Still, since I’ve been so relentless about beating the no-jobs-here drum, I feel I ought to at least point out the other side when I see it.

I fixed a bunch of DSpace things today that I hadn’t realized I broke, and a couple other things that were broken by others besides me. One bug (this one not mine—I think) I didn’t have the heart to test my latest fix for, partly because the Other Thing claimed a lot of my time and energy today. (It’s turning out to be one of those Things that gets further from resolution every time something purports to resolve it. Sigh. And if I don’t handle it right, that’ll haunt me for years, so I really have to handle it right.)

I keep telling myself that fixing bugs is part of learning the system. I keep telling myself that my work will transfer over to the production server with almost no hassle. I keep telling myself that if the boss can talk about “fixing things until they break” and have a sense of humor about it, I’m all right.

Eh, but sometimes I can’t hear what I keep telling myself.

Men, the lucky sods, don’t have to deal with wearing the Wrong Shoes. Strictly a gal thing.

I have two pairs of librarian shoes, because shoes actually fitting me is such a rare occurrence that I celebrate by buying more than one pair. I put on a black-and-red outfit yesterday for the introduction at the staff meeting, and dove into the closet for what I thought was the black pair of librarian shoes.

It was the blue pair. The blue pair. With black and red. Oh, dearie me, was I wearing the Wrong Shoes. And I didn’t notice until I got out to the bus stop and looked down. Far too late to go back and still get to work on time.

The sequel, of course, is that nobody noticed. (That I know of. As I understand the etiquette of these things, one doesn’t tell a lady that she is wearing the Wrong Shoes. One titters behind her back about it with other ladies.) Today I am wearing another black-and-red outfit, because I’ve a lunch with the other newbie librarians and the color combo should help them recognize me.

Got the right shoes this time, though.