Thursday, October 08, 2009

Liferay For Designers

This is a tutorial for Web Designers in charge of developing Layouts and Themes for Liferay Portal.

To develop layouts or themes a local liferay instance is necessary. In addition we will need to install the extension development environment and the plugin SDK.

There is a lot of command prompt usage but you just need to copy and paste if you install the bundle I am using.

I am showing how to configure the jboss and tomcat bundles. I recommend using Tomcat (better and faster option).

I am using MAC OSX this time.

Tomcat

1. Set variables while editing file ~/.profile:

JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home
PATH=$JAVA_HOME:$PATH

2. download bundle liferay-portal-tomcat-6.0-5.2.3.zip and uncompress as ~/liferay


3. download liferay-plugins-sdk-5.2.3.zip and uncompress as ~/liferay/plugin


4. download liferay-portal-ext-5.2.3.zip and uncompress as ~/liferay/ext


5. Customize the ext environment

echo 'app.server.parent.dir=${project.dir}/..' > ~/liferay/ext/app.server.`whoami`.properties

Deploy the extension environment into the application server:

cd ~/liferay/ext
ant deploy

6. Customize the plugin environment

echo 'app.server.dir=${project.dir}/../tomcat-6.0.18' > ~/liferay/plugin/build.`whoami`.properties
chmod +x ~/liferay/plugin/themes/create.sh

Run "ant deploy" from plugin folder.
7. Be sure the server is not running and delete the sample application data. If you run the server before you will need to drop the lportal db and recreate it as step 9 shows.

rm -fR ~/liferay/tomcat-6.0.18/webapps/sevencogs*
rm -fR ~/liferay/tomcat-6.0.18/webapps/sevencogswol*
rm -fR ~/liferay/tomcat-6.0.18/webapps/wol*

8. Install mysql/ from the .dmg image including "mysql start item", start the server:

sudo /Library/StartupItems/MySQLCOM/MySQLCOM start

9. Create the liferay DB:

/usr/local/mysql/bin/mysql -u root
drop database lportal;
create database lportal character set utf8;
UPDATE mysql.user SET Password=PASSWORD('root') WHERE User='root';
flush privileges;

10. Point the local server to the newly created mysql database. For that create/edit ~/liferay/ext/ext-impl/src/portal-ext.properties

jdbc.default.driverClassName=com.mysql.jdbc.Driver
jdbc.default.url=jdbc:mysql://localhost/lportal?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false
jdbc.default.username=root
jdbc.default.password=root

Run "ant deploy-properties" from ext/ folder. At this point ~/liferay/tomcat-6.0.18/webapps/ROOT/WEB-INF/classes/portal-ext.properties will be a copy of the original. Do not edit this file, you must change the one from ext/ext-impl and then run "ant deploy-properties".
11. Run the server. In my case:

~/liferay/tomcat-6.0.18/bin/startup.sh

To stop the server use:

~/liferay/tomcat-6.0.18/bin/shutdown.sh

12. At this time you should be able to see all tables in local DB, to confirm that, run from mysql prompt:

/usr/local/mysql/bin/mysql -u root -proot
use lportal;
show tables;

13. After a while liferay server will finish creating all tables and will open a browser window showing up the welcome page of the portal. Use test@liferay.com / test for credential. You can check the server log using:

tail -f ~/liferay/tomcat-6.0.18/logs/catalina.out



14. Layout development: Follow my tutorial to create a custom layout.


15. Let us say you want to start from an existent theme. I am starting let us say from the "transparentia" theme. You download the theme WAR and uncompress it as "transparentia-theme". Then:

cd ~/liferay/plugin/themes
./create.sh my-project "My Project"
cp -r ~/Downloads/transparentia-theme/css ~/liferay/plugin/themes/my-project-theme/docroot/_diffs/
cp -r ~/Downloads/transparentia-theme/images ~/liferay/plugin/themes/my-project-theme/docroot/_diffs/
cp -r ~/Downloads/transparentia-theme/javascript ~/liferay/plugin/themes/my-project-theme/docroot/_diffs/
cp -r ~/Downloads/transparentia-theme/templates ~/liferay/plugin/themes/my-project-theme/docroot/_diffs/

You go ahead and edit docroot/WEB-INF/liferay-plugin-package.properties with your name as author etc
Deploy your theme:

ant deploy

16. Login to the Liferay local server and select "Manage Pages", click on "Look An Feel" and select the new created theme. See how the creative has changed. Now the theme provides exactly the same look and feel as the transparentia theme.


17. Do some customizations in docroot/_diffs/ (Note customizations are provided always from _diffs folder and never in the files below docroot), for example in css/custom.css you can change the body background color. Deploy again and check changes have been applied.


18. At least for this environment as far as I can tell changes cannot include comments inside any selector or they will be ignored. For example:

.portlet-title img {
display: none;
}

Commenting the display style will not result in the expected outcome. Just remove the class instead. Remember, you just add in _diffs those bits you need and nothing more. At least for this bundle the plugin appears to be unregistered and registered a couple of times which kind of delay getting the final result.


19. Go ahead and create a theme from scratch

cd ~/liferay/plugin/themes
./create.sh my-project2 "My Project 2"

and pick up css, javascript, images and templates folders from ~/liferay/tomcat-6.0.18/webapps/ROOT/html/themes/classic. That is the application server path for the classic Liferay theme.

cp -r ~/liferay/tomcat-6.0.18/webapps/ROOT/html/themes/classic/* ~/liferay/plugin/themes/my-project2-theme/docroot/_diffs/

Deploy the theme and test it is working.

20. Let us try to be a little more agile now. Open file ~/liferay/tomcat-6.0.18/bin/setenv.sh and add the below line at the end

JAVA_OPTS="-Dexternal-properties=portal-developer.properties $JAVA_OPTS"

Take a look at all settings that will take care after you restart the server from file ~/liferay/tomcat-6.0.18/webapps/ROOT/WEB-INF/classes/portal-developer.properties
For the changes to take effect restart the server.

21. Restart the server and make a modification in one of the files from _diffs folder, then copy the file straight to the application server, for example:

cp ~/liferay/plugin/themes/my-project2-theme/docroot/_diffs/css/custom.css ~/liferay/tomcat-6.0.18/webapps/my-project2-theme/css/


JBoss

1. Set variables while editing file ~/.profile:

JAVA_HOME=/System/Library/Frameworks/JavaVM.framework/Versions/CurrentJDK/Home
PATH=$JAVA_HOME:$PATH

2. download bundle liferay-portal-jboss-tomcat-5.0-5.2.3.zip and uncompress as ~/liferay


3. download liferay-plugins-sdk-5.2.3.zip and uncompress as ~/liferay/plugin


4. download liferay-portal-ext-5.2.3.zip and uncompress as ~/liferay/ext


5. Customize the ext environment

cd ~/liferay/ext
vi app.server.`whoami`.properties

Then use proper values for your local environment:

app.server.type=jboss-tomcat
app.server.parent.dir=${project.dir}/..

app.server.version=5.0
app.server.dir=${app.server.parent.dir}/jboss-tomcat-5.0.0
app.server.classes.global.dir=${app.server.instance.dir}/lib
app.server.instance.dir=${app.server.dir}/server/default
app.server.lib.global.dir=${app.server.instance.dir}/lib/ext

app.server.jboss-tomcat.version=5.0
app.server.jboss-tomcat.dir=${app.server.parent.dir}/jboss-tomcat-5.0.0
app.server.jboss-tomcat.classes.global.dir=${app.server.jboss-tomcat.instance.dir}/lib
app.server.jboss-tomcat.instance.dir=${app.server.jboss-tomcat.dir}/server/default
app.server.jboss-tomcat.lib.global.dir=${app.server.jboss-tomcat.instance.dir}/lib

Deploy the extension environment into the application server:

cd ~/liferay/ext
ant deploy

6. Customize the plugin environment

vi plugin/build.`whoami`.properties

Then use proper values for your local environment

app.server.dir=${project.dir}/../jboss-tomcat-5.0.0
app.server.lib.global.dir=${app.server.dir}/server/default/lib/ext
app.server.portal.dir=${app.server.dir}/server/default/deploy/ROOT.war
app.server.classes.portal.dir=${app.server.portal.dir}/WEB-INF/classes
app.server.lib.portal.dir=${app.server.portal.dir}/WEB-INF/lib

Run "ant deploy" from plugin folder.
7. Be sure the server is not running and delete the sample application data. If you run the server before you will need to drop the lportal db and recreate it as step 9 shows.

rm -fR ~/liferay/jboss-tomcat-5.0.0/server/default/deploy/sevencogs*
rm -fR ~/liferay/jboss-tomcat-5.0.0/server/default/deploy/sevencogswol*
rm -fR ~/liferay/jboss-tomcat-5.0.0/server/default/data/hypersonic/*
rm -fR ~/liferay/jboss-tomcat-5.0.0/server/default/deploy/wol*
rm -fR ~/liferay/jboss-tomcat-5.0.0//server/default/work/jboss.web/localhost/*

8. Install mysql/ from the .dmg image including "mysql start item", start the server:

sudo /Library/StartupItems/MySQLCOM/MySQLCOM start

9. Create the liferay DB:

/usr/local/mysql/bin/mysql -u root
drop database lportal;
create database lportal character set utf8;
UPDATE mysql.user SET Password=PASSWORD('root') WHERE User='root';

10. Point the local server to the newly created mysql database. For that create/edit ~/liferay/jboss-tomcat-5.0.0/server/default/deploy/ROOT.war/WEB-INF/classes/portal-ext.properties

jdbc.default.driverClassName=com.mysql.jdbc.Driver
jdbc.default.url=jdbc:mysql://localhost/lportal?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false
jdbc.default.username=root
jdbc.default.password=root

11. Run the server. In my case:

~/liferay/jboss-tomcat-5.0.0/bin/run.sh

12. At this time you should be able to see all tables in local DB, to confirm that, run from mysql prompt:

use lportal;
show tables;

13. After a while liferay server will finish creating all tables and will open a browser window showing up the welcome page of the portal. Use test@liferay.com / test for credential.


14. Layout development: Follow my tutorial to create a custom layout.


15. Let us say you want to start from an existent theme. I am starting let us say from the "transparentia" theme. You download the theme WAR and uncompress it as "transparentia-theme". Then:

cd ~/liferay/plugin/themes
./create.sh my-project "My Project"
cp -r ~/Downloads/transparentia-theme/css ~/liferay/plugin/themes/my-project-theme/docroot/_diffs/
cp -r ~/Downloads/transparentia-theme/images ~/liferay/plugin/themes/my-project-theme/docroot/_diffs/
cp -r ~/Downloads/transparentia-theme/javascript ~/liferay/plugin/themes/my-project-theme/docroot/_diffs/
cp -r ~/Downloads/transparentia-theme/templates ~/liferay/plugin/themes/my-project-theme/docroot/_diffs/

You go ahead and edit docroot/WEB-INF/liferay-plugin-package.properties with your name as author etc
Deploy your theme:

ant deploy

16. Login to the Liferay local server and select "Manage Pages", click on "Look An Feel" and select the new created theme. See how the creative has changed. Now the theme provides exactly the same look and feel as the transparentia theme.


17. Do some customizations in docroot/_diffs/ (Note customizations are provided always from _diffs folder and never in the files below docroot), for example in css/custom.css you can change the body background color. Deploy again and check changes have been applied.


18. At least for this environment as far as I can tell changes cannot include comments inside any selector or they will be ignored. For example:

.portlet-title img {
display: none;
}

Commenting the display style will not result in the expected outcome. Just remove the class instead. Remember, you just add in _diffs those bits you need and nothing more. At least for this bundle the plugin appears to be unregistered and registered a couple of times which kind of delay getting the final result.


19. Go ahead and create a theme from scratch as explained before and pick up css, javascript, images and templates folders from ~/liferay/jboss-tomcat-5.0.0/server/default/deploy/ROOT.war/html/themes/classic. That is the application server path for the classic Liferay theme.


20. Let us try to be a little more agile now. Open file ~/liferay/jboss-tomcat-5.0.0/bin/run.sh and include the below line after one of the existing lines starting with "JAVA_OPTS=..."

JAVA_OPTS="-Dexternal-properties=portal-developer.properties $JAVA_OPTS"

Take a look at all settings that will take care after you restart the server from file ~/liferay/jboss-tomcat-5.0.0/server/default/deploy/ROOT.war/WEB-INF/classes/portal-developer.properties


21. Restart the server and make a modification in one of the files from _diffs folder, then copy the file straight to the application server, for example:

cp ~/Downloads/transparentia-theme/css/custom.css ~/liferay/jboss-tomcat-5.0.0/server/default/deploy/my-project-theme.war/css/


References:
http://www.liferay.com/web/guest/community/wiki/-/wiki/Main/Themes#section-Themes-DevelopingATheme

9 comments:

sseifodd said...

On step five, what is the value of project_dir environment variable supposed to be?

Thanks

Nestor Urquiza said...

@sseifodd ${project_dir} is an "ant" variable. You can always use "echo" from "ant" to print your local value. Liferay and the app server can be deployed in any directory, that is why variables are intensively use.

georgegeorge said...

I tried on ubuntu linux and did the
exactly same changes but got ERROR
for installing
liferay-portal-jboss-tomcat-5.0-5.2.3.zip. Any help ?
---------
directory structure:
~/proj/liferay/jboss-tomcat-5.0.0
~/proj/liferay/plugin/
~/proj/liferay/ext/
edit files:
ext/app.server..properties
plugin/build..properties
ant deploy OK under ext/ and plugin/.

edit changes for Mysql database based on your post.
The run.sh gor ERROR:
------------------

pituin3rut said...

hi, nice tutorial...but i don't find any layout tutorial...please help me...i'm new in liferay

thanks in advance

Nestor Urquiza said...

@pituin3rut I have added the link for the layout tutorial: http://thinkinginsoftware.blogspot.com/2009/10/liferay-and-semantic-web.html
Cheers
-Nestor

Nestor Urquiza said...

@georgegeorge What is the error you are referring to?
Thx
-N

Eleanor said...

Dear Nestor,

I am an acquisition editor for Packt, a UK based publishing company that specializes in IT books.

I am currently hoping to develop a Beginners Guide on Liferay Theming.

Whilst looking for potential authors, I came across your blog and wondered if you would be interested in writing the book?

If you would like more information about writing for Packt, as well as information about our Open Source Royalty Scheme, then please take a look at http://authors.packtpub.com/

If you would be interested in this unique opportunity and would like to discuss it further, then please let me know.

I look forward to hearing from you,

Eleanor Duffy

Acquisitions Editor

Packt Publishing

pituin3rut said...

Thank You, I have seen you post about layout.
I'm also write a blog about liferay
http://sakhrul.co.cc

please visit and give some idea.

Thanks in advance

Rose said...

one of the finest blog ever and thanks for sharing.
- liferay customization

Followers