Skinning uPortal: For Developers Matthew Polizzotti Senior UX Developer Unicon, Inc. Westin Westminster Standley I 25-May-2011 © Copyright Unicon, Inc., Some rights reserved. This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 United States License. To view a copy of this license, visit

2 Agenda 1.Technology stack 2.Define theme & skin 3.Create skin 4.Customize skin

3 Agenda 5.Create child skin 6.Examine theme 7.Common issues 8.Environment checklist

4 Technology stack

5 Java SE 6 Update 24 Apache Ant Apache Maven 2.2+ Apache Tomcat 6.x (Servlet spec. 2.5+) uPortal trunk Ensure compatible versions: uPortal Manual

6 Define theme & skin

7 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

8 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)

9 Create skin

10 Demo Location of skins:  uportal-war/src/main/webapp/ media/skins/universality Copy stable skin as a starting point Rename new skin Register new skin  skinList.xml

11 Demo Adjust skin configuration  skin.xml Deploy new skin to Tomcat  ant deploy-war View & select new skin in the gallery Create alias, short-cuts & copy commands for faster development

12 Questions

13 Customize skin

14 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 ResourceServing Webapp within Tomcat Most development occurs in portal.css

15 CSS stack

16 Demo Header Page Bar Web Search Tabs Portlet Containers Footer

17 Questions

18 Create child skin

19 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

20 Demo Copy stable skin as a starting point Rename new skin Register new skin  skinList.xml Adjust skin configuration  skin.xml

21 Demo 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

22 Questions

23 Examine theme

24 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

25 What is a theme? Example:

26 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

27 How does XSLT work?

28 Suggested work flow Work in the uPortal source code Copy changed files from your source code to your deployed code Changes made to deployed environment can be easily lost or overridden Setup up alias / copy commands for faster development

29 Demo Location:  /up-trunk/uportal/war/src/main/resources/ layout/theme/universality Theme consists of 7 major files:  universality.xsl  page.xsl  navigation.xsl  components.xsl  columns.xsl  content.xsl  preferences.xsl

30 Demo Change the portal through configuration  Flyout menus  Web search  Additional links  Sidebar

31 Questions

32 Common Issues

33 Common Issues Typos & syntax errors in xsl files Incorrect copy commands uPortal aggregation enabled Tomcat fails to shutdown Leverage logs  uPortal.log  catalina.out

34 Environment checklist

35 Download & Install Java SE 6 Update 24 Apache Ant Apache Maven 2.2+ Apache Tomcat 6.x (Servlet spec. 2.5+) uPortal trunk Ensure compatible versions: uPortal Manual

36 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

37 Recommended Aptana 3.0 (eclipse) M2Eclipse Plugin Subversion Plugin or other SVN client Setup alias or short-cuts for long or repetitive commands  uPortal source directory  Theme directory  Skin directory

38 Environment Variables # Java export JAVA_HOME=/path/jdk1.6.0_24 export PATH=$PATH:$JAVA_HOME/bin # Maven export M2_HOME=/path/apache-maven export PATH=$PATH:$M2_HOME/bin # Ant export ANT_HOME=/path/apache-ant export PATH=$PATH:$ANT_HOME/bin Make Java, Maven & Ant libs available across your OS. Example:.bashrc

39 Memory Settings # Java export JAVA_HOME=/path/jdk1.6.0_24 export JAVA_OPTS="-XX:MaxPermSize=256m -Xms728m -Xmx1024m" export PATH=$PATH:$JAVA_HOME/bin 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 Prevent out of memory errors

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

41 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 shared.loader=${catalina.base}/shared/classes,${catalina.bas e}/shared/lib/*.jar Example: CATALINA_BASE/conf/catalina.properties

42 Tomcat Settings Shared Sessions  Enable the sharing of user session data between portlets & the portal  Add emptySessionPath parameter <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" emptySessionPath="true"/> Example: CATALINA_BASE/conf/server.xml

43 Tomcat Settings GZipping portal's HTML content  Add compression parameter  Add compressableMimeType parameter <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" emptySessionPath="true" compression="on" compressableMimeType="text/html,text/xml,text/plain"/> Example: CATALINA_BASE/conf/server.xml

44 Portal Settings Configure build.properties  Set server.home property to Tomcat directory  Used by Ant to deploy compiled uPortal.war to Tomcat ##### Replace server.home with the location of Tomcat 6 on your machine ##### # path to tomcat binaries server.home=/path/apache-tomcat Example: /up-trunk/build.properties

45 Portal Settings Configure log4j.properties to output XML to uPortal.log Portal XML string is a useful visual tool when working with the portal's theme layer ## 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.LoggingStAXCompo nent=false Example: /up-trunk/uportal-war/src/main/webapp/WEB-INF/log4j.properties

46 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)

47 Build the Portal ant -p  List of all ant commands ant hsql  Starts the database ant initportal  Runs all the targets necessary to deploy the portal and prepare the portal database  Should be executed only once  -Dmaven.test.skip=true

48 Start the Portal Server start up.  Tomcat/bin/startup.sh (linux) Tomcat/bin/startup.sh (linux)  Tomcat/bin/startup.bat (windows) Tomcat/bin/startup.bat (windows) Local login.  Portlet Administration  Toggle JS/CSS Aggregation Toggle JS/CSS Aggregation

49 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)

50 Questions & Answers Matthew Polizzotti Senior UX Developer Unicon, Inc.