Some Big changes are Afoot

OK, I've been quiet about this for a bit. But I had other things to do, like attending the Balisage Conference. In the meantime I've had a rethink. I have realised how poorly written Jetspeed is. To create your own Jetspeed website you have to modify an existing website. Yuck. It should just be a product that you ADD things to, like webapps or portlets. Drop them in and away you go. Instead there is all this tinkering with the internals of a complex progam.

So I am returning to Pluto. It's very simple a cleaner. OK, there's no so many features but I can add those. Also, I have decied to use JSPs to define the portlets. I can rewrite the servlet code I have for Alpha and fit it very nicely into Pluto. And the best thing is Pluto is tiny - just 20MB. That sure beats over 200MB for Jetspeed, and that was small.

Changing the database location

This would seem to be a simple task. After all, a web application which is dependent on a database being located somewhere on the disk can't store that information in the database itself. It needs some independent storage location. The obvious place to put this information is in the customised application somewhere. But after searching for it for hours I couldn't find it. No, it is in Tomcat in the /conf/Catalina/localhost directory. The file is called dv.xml (or jetspeed.xml for an uncustomised application).

The reason I wanted to know was that I wished to distribute the website and have it run on Windows. Obviously /tmp/jetspeed wouldn't be available. It would make more sense to store the database in the same folder as the website, and then have a single .bat file to start it all up. But I needed to alter the database location. Now I can.

Actually, I use a relative url. Instead of /tmp/jetspeed/derby/productiondb I used: ../../jetspeed/derby/productiondb, and it worked. My jetspeed directory was in the same directory as apache-tomcat-6.0.20, and contains derby/productiondb.

Changing the Navigation Menu

The navigation menu, which in the 'thesolution' layout is seen on the left, is a reflection of the links defined in /dv/WEB-INF/pages. I just deleted all the boring apache ones and replaced them with more reasonable DV ones.

Localising Included HTML files

Of course, in a website you want lots of HTML files, and in a multi-language website you want to provide translations for them. But how do you arrange it so that if you choose French as your locale, then the correct French HTML files are loaded?

The trick is to create a portlet definition for each HTML file you want to include. A bit tedious, I know, but how else can you do it? The portlet definitions reside in portlet.xml in the j2-portal web application, inside the WEB-INF folder. In there you will find a suitable portlet to revise and take over, such as 'Welcome to Jetspeed 2'. Just copy and duplicate this as many times as you want. It uses the Apache Portal Applications FilePortlet. Now this contains a trick suggested here, although the real mechanism is a little bit different.

You first define an init-param for the portlet thus:

<init-param>
  <name>useLanguage</name>
  <value>true</value>
</init-param>

This turns on the 'fallback' mechanism for files you specify but Jetspeed doesn't find at first. It works like this: if you specify a file /WEB-INF/view/info/about.html in your portlet-preference (see the portlet.xml file) but it's not there, and you enabled the fr locale by saying <supported-locale>fr</supported-locale>, and the current locale is French, then it will generate a fallback consisting of /WEB-INF/view/info/fr/about.html, and if that is present it will load that. The same trick works for any locale, including en.

The title and description strings have to be defined in resource bundles, but I will tackle that tomorrow.

Localising the Website Title

Although my colleagues will probably want 'Digital Variants' in all languages, I wanted localised versions in French, Spanish and Italian as the website title. Here's how you do it. In default-page.psml add some meta-data for each desired version:

<metadata name="short-title" xml:lang="fr">Variantes Numériques</metadata>
etc.

Then, define a Velocity macro in decorator-macros.vm:

#macro (ShortPageTitle)$jetspeed.page.getShortTitle( $preferedLocale)#end

This calls the getShortTitle method of org.apache.jetspeed.page.document.Node.java, which retrieves the declared 'shortTitle' of the page. I now have 'Varianti Digitali' as the website title in Italian.

Restricting the number of languages

How do you correctly restrict the number of languages supported by the DV site? I tried configuring the locales belonging to the Locale Selector portlet, but this doesn't limit the number of displayed flags.

The answer was quite simple, but ferreted away in the bowels of Jetspeed. In the j2-admin application (of which Locale Selector is but a part) you look in the WEB-INF directory for the classes folder. In there under org/apache/jetspeed/portlets/localeselector/resources there's a file LocaleSelectorResources.properties. Edit out the values in localeselector.locales that you don't want. I think that's all, but for good measure I also edited out the unwanted locale names. Ditto for the other files for the other locales in the same directory. Again this is probably redundant. Then you have to quit Tomcat. I deleted /work/Catalina for good measure (the Tomcat cache) and restarted Tomcat and the unwanted locale flags were gone. Hooray!

Why can't they just tell you this?

Progress!

So now I at last understand how to customise Jetspeed. There are four basic areas you can tweak:

1. The administration portlets. Here under 'Portal Site Manager' you can select a page and configure it to some extent. Crucially you can't alter the layout of the stuff in the middle. For that you need:
2. The .pgsml files. These specify in simple XML how to lay out the portlets on a page. Or you can edit a page directly in the portal by clicking on the pencil icon if you have admin privileges.
3. The decorations/layout and decorations/portal folders in the jetspeed or (in my case 'dv' application) folder contain stylesheets for tweaking the appearance of the header, footer and portlet decorations. Overall layout is determined by choosing and manipulating:
4. The header.vm, footer.vm Velocity templates. These are basically HTML files with embedded stuff that boggles the mind where it comes from. I wasted considerable time trying to trace it back through the Java and Velocity macros and eventually gave up. Familiarity will come in time, but it ain't easy.

But, hey, it's starting to look like the portal I wanted, and that's progress! Here's a peek at my first embarrassing effort:

Obviously I haven't finished colouring it correctly or even giving it a main menu or any content yet. But hold on, this my first effort at building a portal and I am as proud of it as a toddler with his first painting. We're actually only going to support four languages (unless we can find someone to do a German or Hindi version) namely French, Italian, Spanish and English, so don't get carried away.