Abstract

Skinning uPortal: For Developers.

There's more than one way to skin a cat. This expression refers to removing the very tough skin from the delicate flesh of a catfish. There are many ways to skin a catfish and all were initially developed through trial and error in an attempt to find the best way to remove the skin without tearing the edible flesh into smaller bits and chunks. Like most fish, an intact one-piece half-fish fillet of catfish is most desirable for cooking (battered, breaded or pan fried). To obtain such catfish fillets, takes knack and technique. Likewise, the goal of this seminar is to refine your portal skinning technique. We want to get right to the content so this seminar won't cover the installation of uPortal, but we'll touch upon development environments before digging into skinning and theming best practices and debugging common skin issues.

Seminar highlights:

What's the difference between a theme and a skin?
How do you change the theme?
How do you change or create new skins?
What are some common skin issues?

Outline

Agenda
1. Technology stack
2. Define theme & skin
3. Create skin
4. Customize skin
5. Create child skin
6. Examine theme
7. Common issues
8. Environment checklist

Slides

Demo steps & images

demo-script-images.zip

Presentation Notes

Section Notes: Technology stack

Technology stack

Ensure compatible versions

uPortal Manual

Java SE 6 Update 24
Apache Ant 1.7.1
1. Ant is used to build Java applications
2. Ant supplies developers with built-in tasks to compile, assemble & test
Apache Maven 2.2+
1. Maven is a project management tool that provides a standard way to build projects
2. Manages project dependencies
Apache Tomcat 6.x
1. Implementation of Java Servlet and JavaServer Pages technologies
uPortal source

Section Notes: Define theme & skin

Define theme & skin

What is a theme?

A theme provides structure or layout for the portal
Similar to a skeleton, a blueprint or the framework of buildings
It is the underlying HTML code of the portal, which is developed using XSLT technology

What is a skin?

A skin consists of the portal's color scheme, text styles and images (visual appearance)
Developed with Cascading Style Sheets (CSS) and image files
Remember to disable the portal's aggregation of CSS and Javascript resources (Portlet Administration)

Section Notes: Create skin

Create a skin

Demo

Location of skins:
1. uportal-war/src/main/webapp/media/skins/universality
Copy stable skin as a starting point
Rename new skin
Register new skin (skinList.xml)
Adjust skin configuraiton (skin.xml)
Deploy new skin to Servlet container
```
// From command-line
ant deploy-war
```
View & select new skin in the gallery
1. Inspect portal link tags, which should point to your new skin
Create alias, short-cuts & copy commands for faster development

Section Notes: Customize skin

Customize skin

CSS stack

CSS stack is defined in skin.xml
Styles common to all skins are imported from common_skin.xml to skin.xml
Third-party libraries (Fluid, jQuery) live in the ResourceServingWebapp within Tomcat
Most development occurs in portal.css

CSS stack illustrated

Demo

Header
Page Bar
Web Search
Tabs
Portlet Containers
Footer

Section Notes: Create child skin

Create child skin

What is a child skin?

A child skin is a variation of an existing skin
A child skin inherits style definitions from the parent skin
A child skin overrides styles defined by the parent

Demo

Copy stable skin as a starting point
Rename new skin
Register new skin (skinList.xml)
Adjust skin configuration (skin.xml)
Add CSS overrides
Deploy new skin to Tomcat (ant deploy-war)
View & select new skin in the gallery
Create alias, short-cuts & copy commands for faster development

Section Notes: Examine theme

Examine theme

What is a theme?

A theme provides structure or layout for the portal
Similar to a skeleton, a blueprint or the framework of a building
It is the underlying HTML code of the portal, which is developed using XSLT technology

What is a theme?

What is XSLT?

XSLT stands for XSL Transformations
XML-based language used for the transformation of XML documents into other documents such as HTML
XSLT uses XPath to navigate XML

How does XSLT work?

Suggested work flow

Work in the uPortal source code
Copy changed files from your source code to your deployed code
Copy changed files from your source code to your deployed code
Setup up alias / copy commands for faster development

Demo

Location:
1. /uportal-war/src/main/resources/layout/theme/universality
Theme consists of 7 major files:
1. universality.xsl
2. page.xsl
3. navigation.xsl
4. components.xsl
5. columns.xsl
6. content.xsl
7. preferences.xsl
Change the portal through configuration:
1. Show or hide tab flyout menus
2. Add a sidebar to the portal
3. Add a page title to the portal
4. Add additional links
5. Remove the web search from the header

Section Notes: Common issues

Common issues

Typos & syntax errors in xsl files
Incorrect copy commands
uPortal aggregation enabled
Tomcat fails to shutdown
Leverage logs
1. location: tomcat/logs
2. catalina.out
3. uPortal.log

Section Notes: Environment checklist

Environment checklist

Download & install

Ensure compatible versions

uPortal Manual

Java SE 6 Update 24
Apache Ant 1.7.1
- Ant is used to build Java applications
- Ant supplies developers with built-in tasks to compile, assemble & test
Apache Maven 2.2+
- Maven is a project management tool that provides a standard way to build projects
- Manages project dependencies
Apache Tomcat 6.x
Implementation of Java Servlet and JavaServer Pages technologies
uPortal source

Recommended

Download Java, Ant & Maven to common area specific to your OS
- Linux (/home/username/opt)
- Windows (C:\Program Files)
Download uPortal & Tomcat to the same project folder
Aptana (eclipse)
M2Eclipse plugin
Subversion plugin
Setup alias or short-cuts for long or repetitive commands

Environment Variables

Environment variables are global system variables accessible by all the processes running under an operating system. Makes Java, Maven & Ant libs available across your Operating System.

Example: .bashrc

# Java
export JAVA_HOME=/path/jdk1.6.0_24
export PATH=$PATH:$JAVA_HOME/bin

# Maven
export M2_HOME=/path/apache-maven-2.2.1
export PATH=$PATH:$M2_HOME/bin

# Ant
export ANT_HOME=/path/apache-ant-1.7.1
export PATH=$PATH:$ANT_HOME/bin

Memory settings

Prevent out of memory errors

Tune JVM with JAVA_OPTS variable
-Xmx – maximum amount of memory allocated to JVM
-Xms – initial amount of memory allocated allocated to JVM
-XX:MaxPermSize – maximum amount of memory for PermGen. Is used by the JVM to hold loaded classes.

Example: .bashrc

# Java
export JAVA_HOME=/path/jdk1.6.0_24
export JAVA_OPTS="-XX:MaxPermSize=256m -Xms728m -Xmx1024m"
export PATH=$PATH:$JAVA_HOME/bin

Tomcat Settings

Shared Libraries

uPortal places libraries in CATALINA_BASE/shared/lib
Tomcat 6.0 does not allow libraries to be loaded from CATALINA_BASE/shared/lib

Example: CATALINA_BASE/conf/catalina.properties

shared.loader=${catalina.base}/shared/classes,${catalina.base}/shared/lib/*.jar

Shared Sessions

Enable the sharing of user session data between portlets & the portal
Add emptySessionPath parameter

Example: CATALINA_BASE/conf/server.xml

<Connector port="8080" protocol="HTTP/1.1"
	connectionTimeout="20000" redirectPort="8443"
	emptySessionPath="true"/>

GZipping portal's HTML content

Add compression parameter
Add compressableMimeType parameter

Example: CATALINA_BASE/conf/server.xml

<Connector port="8080" protocol="HTTP/1.1"
     connectionTimeout="20000" redirectPort="8443"
     emptySessionPath="true" compression="on"
     compressableMimeType="text/html,text/xml,text/plain"/>

Portal Settings

Configure build.properties
- Set server.home property to Tomcat directory
- Used by Ant to deploy compiled uPortal.war to Tomcat

Example: /trunk/build.properties

##### Replace server.home with the location of Tomcat 6 on your machine #####
# path to tomcat binaries
server.home=/path/apache-tomcat-6.0.32

Configure log4j.properties to output portal's XML string to uPortal.log
Portal XML string is a useful visual tool when working with the portal's theme layer

Example: /trunk/uportal-war/src/main/webapp/WEB-INF/log4j.properties

## Uncomment to see the XML at various stages in the rendering pipeline
log4j.logger.org.jasig.portal.rendering.LoggingStAXComponent=DEBUG, R
log4j.additivity.org.jasig.portal.rendering.LoggingStAXComponent=false

Build the portal

Execute all ant commands from the command-line
All ant commands are executed against the uPortal source directory
Build uPortal source code and deploy to our servlet container (Tomcat)
ant -p
- List of ant commands available
ant hsql
- Starts the database
ant initportal
- Runs all the targets necessary to deploy the portal and prepare the portal database
- Should only be executed once
- -Dmaven.test.skip=true
  - Can be added to skip tests when building

Start the portal

Server start up
- Tomcat/bin/startup.sh (linux)
- Tomcat/bin/startup.bat (windows)
Local login:
- http://localhost:8080/uPortal/Login?userName=admin&password=admin
Portlet Administration
- Toggle JS/CSS Aggregation

Recommended

Setup alias or short-cuts for long or repetitive copy commands
- Copy files from the Theme (source) to the Theme (deployed)
- Copy files from the Skin (source) to the Skin (deployed)