Work in progress - Early stages
| Revision History | |
|---|---|
| Revision Updated: | Thursday, November 23rd, 2006 |
Table of Contents
Intended audience. This document is intended for system administrators that want to upgrade an existing Liferay Portal installation to a new version and developers that have done developments for a given version and want them to work in a later version.
Liferay version. This guide has been written for Liferay 4.2. It includes information for upgrading from 4.1 and some previous versions.
Related documents. If this is not what you are looking for consider the following related documents:
Liferay Portal 4 -Development in the Extension Environment
More information and support. If you have are looking for help in an specific issue we invite you to use our community forums: http://www.liferay.com/web/guest/devzone/forums to explain your problems and ask your questions. We also offer professional support services (support@liferay.com)where your company can be assigned a Liferay developer that will ensure that your questions are answered promptly so that your project is never compromised. Purchased support always gets first priority. This business model allows us to build a company that can contribute a great portal to the open source community. If your company uses Liferay, please consider purchasing support. Liferay has an extremely liberal license model (MIT, very similar to Apache and BSD), which means you can rebundle Liferay, rename it, and sell it under your name. We believe free means you can do whatever you want with it. Our only source of revenue is from professional support and consulting.
![[Note]](images/note.png) | Note |
|---|---|
This guide is a work in progress in its early stages |
Table of Contents
One of the biggest changes for themes in Liferay Portal 4.0.0 is that hot-deployable themes must now use Velocity templates. The following outlines why this change was necessary:
Up until Liferay Portal 4.0.0RC2, Liferay used to place its JARs in the shared class loader. The benefit of this was that all web applications could access Liferay's classes since they were in the shared class loader. The drawback was that JARs in the shared class loader would automatically override JARs in other web applications. So if a web application required Hibernate 2.0 and Liferay required Hibernate 3.0, this would cause conflicts because the JARs in the shared class loader would override the JARs in the web application.
Starting from Liferay Portal 4.0.0 final, Liferay no longer places its JARs in the shared class loader. This allows Liferay to work with web applications that require different versions of Struts, Hibernate, etc. without any changes to the code. This also means that hot-deployable themes cannot access Liferay's classes because they are not in the shared class loader.
Tomcat's shared class loader is here: tomcat/common/lib/ext. Instead of placing its JARs in the shared class loader, Liferay now puts them here: tomcat/liferay/WEB-INF/lib. Web applications in tomcat/webapps cannot access Liferay's classes because they are no longer in tomcat/common/lib/ext.
If your theme is named *.war, it is a web application. For example, ant-themes-4.0.0.war is a web application. These themes are also called hot-deployable themes since you can deploy them at runtime. Themes that have a .war extension must use Velocity templates because they cannot access Liferay's classes.
Use Velocity for cleaner code and better maintainability. We converted all of our community themes to use Velocity. These themes are a great way to learn how to build your own themes using Velocity. Also see VelocityTaglib.java for a list of tags that are available to you.
Use JSP for flexibility or if you do not have time to learn Velocity. If you want to create themes using JSP, you will need to create them in ext/ext-web/docroot/html/themes. See portal/portal-web/docroot/html/themes for examples on how to create JSP themes.
Note: All themes developed in ext/themes or themes that have a .war extension cannot access Liferay's classes because of the new class loader. These themes must be developed using Velocty templates. On the other hand, JSP themes must be developed in ext/ext-web/docroot/html/themes. These themes must be developed here because they need to access Liferay's classes.
Convert your theme to Velocity. See our community themes for examples on how to create themes using Velocity templates.
Port your theme to the ext/ext-web/docroot/html/themes directory. If you do not know how to create an extension environment, read this section first: http://content.liferay.com/4.0.0/docs/quickstart/ch04s01.html
The following guidelines will help you to port your theme to Liferay Portal 4.0.0.
If you developed your theme as a *.war file or if you developed your theme in ext/themes, deploy your theme to your server. Then copy the resulting theme directory to ext/ext-web/docroot/html/themes. Skip this step if your theme is already located in ext/ext-web/docroot/html/themes.
Example: If your theme is ant-themes-4.0.0.war, deploy this theme to your server. If you are using Tomcat, the theme will be deployed to tomcat/webapps. Copy the resulting "ant-themes-4.0.0" directory and all of its contents to ext/ext-web/docroot/html/themes
When you are finished the directory structure should look like this: ext/ext-web/docroot/html/themes/ant-themes-4.0.0. If your "ant-themes-4.0.0" directory is empty you have not deployed the theme correctly.
Convert the JSPs:
| Before | After |
|---|---|
| <liferay:runtime-portlet | <liferay-portlet:runtime |
| <liferay:include flush=”true” | <liferay-util:include Remove "flush" attribute |
| layoutId | plid |
| getLayoutId | getPlid |
| getUserId | getOwnerId |
| getResTotal | getResolution Only use this method in css.jsp |
| LayoutServiceUtil.getLayout | LayoutLocalServiceUtil.getLayout |
| tilesSubNav | This variable was removed |
Convert icons in portlet_top.jsp to <liferay-portlet> taglib icons:
<liferay-portlet:icon-configuration /> <liferay-portlet:icon-edit /> <liferay-portlet:icon-edit-guest /> <liferay-portlet:icon-help /> <liferay-portlet:icon-print /> <liferay-portlet:icon-minimize /> <liferay-portlet:icon-maximize /> <liferay-portlet:icon-close />
Convert hrefs in top.jsp to use themeDisplay getter methods
getURLMyAccount getURLSignOut getURLAddContent getURLPageSettings getURLSignIn
Convert “Communities” to “My Places”
<div id="layout-my-places"> <liferay-portlet:runtime portletName="<%= PortletKeys.MY_PLACES %>" /> </div>
Images
Liferay convention is to put all custom images into images/custom
Copy default images from Classic theme.
CSS Styles
Remove any styles with “n1” or “w1” in the name
Add the following styles:
portal-add-content layout-column_column-? layout-column-highlight portlet-dragging-placeholder layout-my-places
Change the following styles:
| Before | After |
|---|---|
| #gamma-tab | .gamma-tab |
| #current | .current |
Table of Contents
Since Liferay Portal v4.1.2 the ids of portlets and themes are manipulated before writting them to the database. In particular all characters that are not safe to be used in JavaScript scripts (spaces and minus signs) are removed. Liferay 4.1.3 and Liferay 4.2.0 include an upgrade script that modifies the database to mantain change any old portlet or theme reference to conform to the new naming convention.
While the upgrade script should cover 99% of the situations there
is a 1% that is not covered and you should be aware of. If you are using
custom layout templates that define columns whose names are not of the
form column-N where N is a number from 1 to 10 then
you should upgrade the portlets referenced from those columns
yourself.
In order to do so review the typePreferences of
entries of the Layout_ table that use the
non-conforming layout template and edit it's contents. You should keep
the properties-like format and only change the portlet ids to remove the
spaces and minus signs in the cases where they are used.