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

Advertisements

Eric Meyer’s CSS Sculptor

Eric Meyer’s CSS Sculptor

This is my latest favourite ‘toy’ that I’m playing with just now. Eric Meyer’s CSS Sculptor is a Dreamweaver Extension (for DW8 or DW CS3) from WebAssist developed in collaboration with the CSS guru himself. It’s not cheap, though: normal price is US $149.99, although I got it on special offer via .net magazine for US $104.99.

This extension allows you to quickly create a standards-compliant, CSS-based layout in minutes, rather than hours, in six simple steps:

  1. Choose one of the 30 built-in layouts (e.g. 1 Column, Fixed, Centered; 2 Column Elastic, Left Sidebar; 3 Column Fixed, Header and Footer, etc.)
  2. Customize widths and heights, margins and padding
  3. Set basic typography (text, h-tags and links)
  4. Style each div with background colours and/or images
  5. Define which layout components to show or hide in a print style sheet
  6. Once you’ve decided on a Doctype and whether to include the CSS in a separate file or within the document head click Finish to allow the extension build the code — it will build with or without explanatory comments, which are really useful for understanding what it’s done and why

Output code supports Internet Explorer 5.5 – 7.x, Firefox 2.x, Safari 2, Opera 9; earlier versions of Netscape and Firefox are notably absent from this list but all code that I’ve created with this extension so far have worked fine in Netscape 7.2 and Firefox 1.x.

Obviously, this isn’t a replacement for knowing CSS inside out — everyone does, right? 😉 — but it’s a great tool to add to the arsenal, and a great way to learn CSS, or simply to knock up a CSS-based design very quickly.