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

About these ads

About Gareth J M Saunders

Hi, I'm Gareth J M Saunders, 6' 4", married to Jane, father of 3 boys (twins and singleton), I'm a priest in the Scottish Episcopal Church, employed as the Web Architect at the University of St Andrews. My main interests are HTML, CSS (inc. frameworks), jQuery, Information Architecture and Agile development.
This entry was posted in Code, Portal. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s