I’ve been tasked with the (un)envious job of skinning our installation of uPortal which we’re using to develop a students’ portal and have been frustrated at the lack of online documentation available for guiding Tomcat n00bs like me at how to do it.
The online documentation takes you so far, and outlines the various steps:
- Set up a development environment (Consider the uPortal Quickstart)
- Copy the entire skin directory
- Rename the skin directory
- Register the new skin in the portal
- Make modifications to skin files
- Test the new skin in a test environment
- Move the new skin to a public environment
- Restart the portal server
- Verify the new skin within the portal
But it’s the finer details that I’ve struggled with. Thankfully we’ve got a contract with uPortal consultants Unicon who came up trumps last night with a top tip that has sped up development incredibly.
Creating a new skin directory
Steps 2 and 3 above instruct you to “Copy the entire skin directory” and “Rename the skin directory”. Here’s what I did.
uPortal comes with a default theme (called universality) and two skins (uportal3 and ivy). In uPortal themes control the page structure and layout, while skins control the design of themes.
For our purposes the ivy skin was close to what we wanted to achieve so I just copied the ivy folder within the uPortal war source directory (\uPortal-3.1.1\uportal-war\src\main\webapp\media\skins\universality\) and renamed it standrews.
This new standrews directory contains the following files and folders:
The next step was to rename any instance of the old skin name (ivy) with the new (in this case: standrews). So we now get:
But it doesn’t stop there. There are also references to the theme within the standrews_base.css file. I used my web editor of choice (Blumentals WeBuilder 2010) to replace within these files an instance of ‘ivy’ with ‘standrews’.
The standrews_thumb.gif file shows a thumbnail screenshot image of your new theme, but since I’ve not created it yet I simply edited the existing file to make it look different from the original.
Register the new skin
The next step is to register your skin within uPortal by editing the skinList.xml file within the uPortal-3.1.1\uportal-war\src\main\webapp\media\skins\universality\ directory.
It’s simply a case of copying the XML entry for ivy and making the necessary adjustments, e.g.
Redeploying uPortal (ant deploy-war) and restarting Tomcat will now give you the option of your new skin.
So far so good.
Modify skin files
But it’s step 5 that I was struggling with: make modifications to skin files.
The problem is that once I’d discovered where Tomcat stores the files: apache-tomcat-6.0.18\webapps\uPortal\media\skins\universality\ (and accounting for uPortal minifying the files too) whenever I made a change to a CSS element within, for example, standrews_base.min.css and then refreshed my browser nothing would happen.
Turn off uPortal caching
I fired off another email to Unicon and within a couple of hours (they’re in the US) I got the reply I was looking for:
The caching can be turned off by commenting out a couple lines in the web.xml file. The web.xml file can be found in the following locations:
Commenting out filter-mapping for *.css and *.js disables the caching. The code that needs to be commented is around line 186. This is what it looks like in my environment.
<!-- Comment out filter for development purposes
I then redeployed uPortal and that was it. That was the missing link. Now I can edit the CSS files, refresh my browser and there are the changes.
That’s one piece of information that would be a welcome addition to the JA-SIG Wiki.
Gareth @ St Andrews