Developing skins in uPortal 3.1.x

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:

  1. Set up a development environment (Consider the uPortal Quickstart)
  2. Copy the entire skin directory
  3. Rename the skin directory
  4. Register the new skin in the portal
  5. Make modifications to skin files
  6. Test the new skin in a test environment
  7. Move the new skin to a public environment
  8. Restart the portal server
  9. 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:

  • [images]
  • ivy.css
  • ivy_base.css
  • ivy_jsr168.css
  • ivy_legacy.css
  • ivy_thumb.gif
  • jquery.css

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:

  • [images]
  • standrews.css
  • standrews_base.css
  • standrews_jsr168.css
  • standrews_legacy.css
  • standrews_thumb.gif
  • jquery.css

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.

<skin>
<skin-key>standrews</skin-key>
<skin-name>St Andrews</skin-name>
<skin-description>New design</skin-description>
</skin>

Redeploy uPortal

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

And I couldn’t find any documentation to explain that uPortal itself was caching the CSS and JavaScript files used by the skin.  Not the browser, the application.

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:

  • /path/to/uportal-war/src/main/webapp/WEB-INF/web.xml
  • /path/to/tomcat/webapps/uportal/WEB-INF/web.xml

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
<filter-mapping>
<filter-name>pageCachingFilter</filter-name>
<url-pattern>*.js</url-pattern>
<url-pattern>*.css</url-pattern>
</filter-mapping>-->

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

Intranets

At St Andrews we’re about to begin a new portal / intranet project. Any comments, recommendations, insights, pitfalls, welcomed.

I’ve discovered that the Nielsen Norman Group have a two volume report (from November 2007) based on case studies of 56 intranets called “Intranet Information Architecture”.

There’s a summary on Jakob Nielsen’s Alertbox site, and here’s a summary from the Nielsen Norman Group site:

Two-volume report on how to best structure your intranet, how to design its navigation system, and how to run the IA aspects of the design process.

Richly illustrated with 744 color screenshots of real intranets and their navigation design and other IA screen elements.

The report contains detailed profiles of 56 real-world intranets‘ information architecture as well as generalized analyses and best-practice recommendations derived from these many case studies. This report shows you how real intranets work – it’s not speculation or fantasy; it’s hard reality.

Our analysis encompassed intranets from a wide range of organizations in 12 countries:

  • 33 companies from a variety of industries, including financial services, utilities, and technology
  • 11 government agencies
  • 5 healthcare providers
  • 4 educational institutions
  • 3 non-profits

Of the organizations, 11 were small (500 employees or less), 30 were mid-sized (501-20,000 employees), and 15 were large (more than 20,000 employees).

Intranet Blog

Here’s also an interesting blog about intranets, imaginatively titled Intranet Blog, written by Toby Ward.