ShowTable of Contents
Introduction
WebDAV entry points for themes and skins were introduced in IBM® WebSphere® Portal version 7. This eased development of themes, especially when working together with Web agencies, and provided a convenient way to change the most common artifacts quickly.
However, when diving deeper into theme development and working on advanced scenarios, in most cases, you would create new dynamic content spots that would be deployed as EAR files. As a result, deployment would became more complicated and include different packages and technologies.
For environments in which the focus is on the simplicity of the deployment, WebSphere Portal 8 again offers deployment and development as a single EAR file. This article details the instructions to maintain your theme, using IBM Rational Application Developer (RAD), and deploy it as a single EAR file.
We start with a description of how to assemble the different artifacts from the original theme and then discuss the setup in RAD from which the theme can then be easily be hot-deployed during development.
This is followed by instructions on which configurations/files need to be changed for the custom EAR-theme, a description of the actual steps during deployment, and finally an explanation of debugging options. We do not go into the details of every theme feature, but links to additional information are included when related topics are touched on.
NOTE: Although this guide is written for the Portal 8 theme, you can also package the WebSphere Portal 7002 Theme as one EAR file.
Assembling theme artifacts
To set up the custom theme in an EAR file we need to retrieve the source from the shipped theme. Basically we need two kind of resources: Static (Cascaded Style Sheets, JavaScriptTM accessed via WebDAV) and Dynamic (JavaServer Pages) resources.
Dynamic resources
These need to be copied from the filesystem from the following location, per the product documentation topic,
“Make a unique copy of the dynamic resources for your theme:”
-
opt/WebSphere/PortalServer/theme/wp.theme.themes/default80/installedApps/DefaultTheme80.ear/DefaultTheme80.war
Copy the following folders/files to a temp folder:
-
skins /*
-
themes /*
-
WEB-INF/decorations.xml
-
WEB-INF/tld/*
Static resources
To retrieve the static resources you can connect using a WebDAV client as described in the topic, “Using WebDAV file store.” An easier option for this use case is to retrieve the content via the browser, per the topic, “Exporting content from the file store,” using the following URLs:
-
Themes
-
http://:/wps/mycontenthandler/dav/fs-type1/themes/?mime-type=application/zip
-
Skins
-
http://:/wps/mycontenthandler/dav/skinlist/?mime-type=application/zip
Setting up the development environment
To work with the theme, we must create two Dynamic Web Projects that will contain the WAR files and then be deployed as one EAR file to the Portal/Application Server.
Dynamic resources
1. Open RAD and switch to the Java EE Perspective.
2. Select File --- New --- Project --- Dynamic Web Project
3. Define names:
-
Project name: CustomTheme8Dynamic
-
Select WebSphere Portal v8.0 as the Target runtime
-
EAR project name: CustomTheme8EAR
4. Click Next, Next, and then Finish.
5. Now copy the resources retrieved from the shipped theme to the project (see figure 1):
-
skins → WebContent/skins
-
themes → WebContent/themes
-
WEB-INF/decorations.xml → WebContent/WEB-INF/decorations.xml
-
WEB-INF/tld → WebContent/WEB-INF/tld
Figure 1. File structure of the dynamic resources
Static resources
1. Select File --- New --- Project --- Dynamic Web Project.
2. Define names:
-
Project name: CustomTheme8Static
-
Select WebSphere Portal v8.0 as the Target runtime
-
EAR project name: Select CustomTheme8EAR
3. Click Next, Next, and then Finish.
4. Copy the resources previously retrieved from WebDAV to the following directories:
-
themes → WebContent/themes
-
skinlist/ibm.portal.80Hidden → WebContent/skins/Hidden (before copying, delete these files/folders):
-
skinlist/ibm.portal.80Hidden/metadata/*
-
skinlist/ibm.portal.80Hidden/metadata.properties
-
skinlist/ibm.portal.80NoSkin → WebContent/skins/NoSkin (before copying, delete these files/folders):
-
skinlist/ibm.portal.80NoSkin/metadata/*
-
skinlist/ibm.portal.80NoSkin/metadata.properties
-
skinlist/ibm.portal.80Standard → WebContent/skins/Standard (before copying, delete these files/folders):
-
skinlist/ibm.portal.80Standard/metadata/*
-
skinlist/ibm.portal.80Standard/metadata.properties
5. To allow access to the resources, add the code in listing 1 to the WEB-INF/web.xml file.
Listing 1. Code to add to WEB-INF/web.xml
<web-app ...>
[…......]
<context-param>
<description>A regular expression that defines which of the resources in the WAR file can be served by the portal war datasource.</description>
<param-name>com.ibm.portal.whitelist</param-name>
<param-value>.*</param-value>
</context-param>
<context-param>
<description>A regular expression that defines which of the resources in the WAR file cannot be served by the portal war datasource.</description>
<param-name>com.ibm.portal.blacklist</param-name>
<param-value>WEB-INF/.*</param-value>
</context-param>
[…......]
</web-app>
For more details, refer to the topic, “Add the static content to your custom theme article.”
Figure 2. File structure of the static resources
6. To create the deployment descriptor, right-click the EAR project and select Java EE --- Prepare for deployment.
Modify original resources (files and Portal config)
Before deploying the custom theme, we must ensure that the dynamic content spots in the static resources point to the custom dynamic EAR file:
1. Create a new content spot, per the instructions in the topic, “Creating a dynamic content spot.”
2. Add the “custom properties” listed below to the “Resource environment provider entry, “WP DynamicContentSpotMappings”, where “ CustomTheme8Dynamic” is the context root of the Dynamic Resources WAR file:
NOTE: You can also address the JSPs directly from the theme_*.html with the following pattern:
-
<a rel="dynamic-content" href="res:/CustomTheme8Dynamic/themes/html/dynamicSpots/footer.jsp "></a>)
Name: Custom80theme_footer
-
Value: res:/CustomTheme8Dynamic/themes/html/dynamicSpots/footer.jsp
Name: Custom80theme_crumbTrail
-
Value: res:/CustomTheme8Dynamic/themes/html/dynamicSpots/crumbTrail.jsp?rootClass=wpthemeCrumbTrail&startLevel=2
Name: Custom80theme_topNav
-
Value: res:/CustomTheme8Dynamic/themes/html/dynamicSpots/navigation.jsp?rootClass=wpthemeHeaderNav&startLevel=0&primeRoot=true
Name: Custom80theme_primaryNav
-
Value: res:/CustomTheme8Dynamic/themes/html/dynamicSpots/navigation.jsp?rootClass=wpthemePrimaryNav%20wpthemeLeft&startLevel=1
Name: Custom80theme_secondaryNav
-
Value: res:/CustomTheme8Dynamic/themes/html/dynamicSpots/navigation.jsp?rootClass=wpthemeSecondaryNav&startLevel=2&levelsDisplayed=2
Name: Custom80theme_commonActions
-
Value: res:/CustomTheme8Dynamic/themes/html/dynamicSpots/commonActions.jsp
Name: Custom80theme_pageModeToggle
-
Value: res:/CustomTheme8Dynamic/themes/html/dynamicSpots/pageModeToggle.jsp,wp_toolbar
Name: Custom80theme_head
-
Value: res:/CustomTheme8Dynamic/themes/html/dynamicSpots/head.jsp
Name: Custom80theme_status
-
Value: res:/CustomTheme8Dynamic/themes/html/dynamicSpots/status.jsp, wp_status_bar
3. Restart WebSphere Portal.
4. Now the content spots in the theme_*.html must be adapted:
a) In Eclipse, open “CustomTheme8Static/WebContent/themes/Portal8.0/nls/theme_en.html.“ (Note that this must be done for all localized theme_*.html files that should be supported by the solution.)
b) Replace the following content spots with the new names:
80theme_footer → Custom80theme_footer
80theme_crumbTrail → Custom80theme_crumbTrail
80theme_topNav → Custom80theme_topNav
80theme_primaryNav → Custom80theme_primaryNav
80theme_secondaryNav → Custom80theme_secondaryNav
80theme_commonActions → Custom80theme_commonActions
80theme_pageModeToggle → Custom80theme_pageModeToggle
80theme_head → Custom80theme_head
80theme_status → Custom80theme_status
Debugging
To work with the theme more efficiently and to make changes visible without restarting the WebSphere Portal Server, the following settings are recommended for the development system (
but must be removed for production!):
1. To enable reload of the static resources, make the change shown in listing 2 to the Default.jsp (CustomTheme8Dynamic/WebContent/themes/html/Default.jsp – Line 25 following):
Listing 2. Change to enable reload of static resources
--%><r:dataSource uri='<%="spa:" + pageContext.getAttribute("currentNavNodeID", PageContext.REQUEST_SCOPE)%>' escape="none"><%--
--%><r:param name="themeURI" value="${themeTemplateURI}"/><%--
--%><r:param name="mime-type" value="text/html"/><%--
--%><r:param name="max-age" value="2"/><%--
--%></r:dataSource><%--
2. Also, make sure that
CustomTheme8Dynamic/WebContent/WEB-INF/ibm-web-ext.xmi
CustomTheme8Static/WebContent/WEB-INF/ibm-web-ext.xmi
are set to the following:
reloadingEnabled="true"
Deployment scripts & deployment
Since the theme is not deployed via WebDAV, it is not registered automatically, and XML access is needed to register the theme and skins with Portal. The attached sample script will register
one new theme:
and three skins:
-
Custom Portal 8.0 – Standard
-
Custom Portal 8.0 – NoSkin
-
Custom Portal 8.0 – Hidden
where “Hidden” is the standard skin. Furthermore the “2ColumnEqual” layout-template is set as the standard.
1. Import the sample XML, “RegisterCustomTheme.xml.” either using the XML Admin Portlet or via xmlaccess:
./xmlaccess.sh/bat -user -password wpsadmin -url :/wps/config -in RegisterCustomTheme.xml -out result.xml
2. In the final step the EAR files must be deployed to the Application Server. You can either do this manually:
a) Right-click on the EAR project (CustomTheme8EAR), click Export, and click EAR file.
b) Define a name and destination, and click Finish.
or do a hot deployment---especially useful during the deployment process (these steps assume that you are running RAD and Portal on the same machine):
(NOTE: To enable hot deployment, you must allow publishing of projects that contain errors. To do this, select Window --- Preferences --- Server --- WebSphere Application Server, and enable “Allow applications containing errors to be published on a server.”)
-
Right-click the EAR project (CustomTheme8EAR) and select “Run as” --- “Run on server.”
-
Select “Manually define a new server”and “WebSphere Portal v8.0 Server” from the drop-down list.
-
Enter the server’s hostname and define a server name as you like.
-
The Server runtime environment shows “Create a new runtime environment” if you are doing this for the first time. To speed up future deployments, select “Always use this server when running this project”; click Next
-
Enter the location for “WebSphere Portal” and the “AppServer” and enter the password for the admin user; click Next
-
Enter the password for the Portal and WAS admin user to enable automatic login; click Next.
-
Check the settings and, if correct, click Next again.
-
The “CustomTheme8EAR” should now be preselected to be deployed; click Finish.
The theme should now be deployed to the server.
Finally, the theme needs to be assigned to a page:
-
Go to the page where the theme should be changed and click “Edit Mode”.
-
In the Overview tab select (while hovering) “Edit”.
-
In the Lightbox, select the Advanced tab and then “Custom Portal 8” as the theme.
-
Apply the setting by clicking Save.
That’s it! Changes can now be done to, for example, CustomTheme8Static/WebContent/themes/Portal8.0/nls/theme_en.html, and after redeploying it to the server, you will be able to see them.
Conclusion
In this article you learned how to set up your theme to deploy it as an EAR file using RAD. This gives you a good starting point to begin with the actual theme development. To make the best use of the new functions introduced with WebSphere Portal 7002 and 8, you can dive deeper via the product documentation topic, “Developing themes and skins” and the wiki articles in “Exceptional Web Experience for WebSphere Portal 8.0”.
Tell us what you think
Please visit this link to take a one-question survey about this article:
http://www.surveymonkey.com/s/9Q6ZKGNResources
developerWorks WebSphere Portal zone:
http://www.ibm.com/developerworks/websphere/zones/portal/
IBM WebSphere Portal V8.0 and IBM Web Experience Factory V8.0 deliver new capabilities for integrated social, contextual, and optimized multichannel online experiences:
http://www-01.ibm.com/common/ssi/cgi-bin/ssialias?subtype=ca&infotype=an&appname=iSource&supplier=897&letternum=ENUS212-132
WebSphere Portal forum:
http://www.ibm.com/developerworks/forums/forum.jspa?forumID=168
About the author
Peter Schnitzler is a member of the Lab Services Team for WebSphere Portal located in the IBM Development and Research Lab in Boeblingen, Germany. During the past years he has focused on providing in-depth expertise around the entire range of UI topics for WebSphere Portal, helping customers to create not only a state-of-the-art technical solution but also an exceptional user experience. He can be reached at peter@de.ibm.com.