Sunday, October 18, 2009

Liferay for backend developers

This is a tutorial for Back End developers (Java code) in charge of developing Portlets for Liferay Portal.

As a backend developer needs to understand how the look and feel will be applied, this tutorial is a continuation of my recent "Liferay for Designers" tutorial. So, if you haven't done it please follow steps on the Designers tutorial before continuing.

Note that I am providing instructions here for two bundles, tomcat and jboss+tomcat. You better use tomcat for development purposes as it is lighter and just use JBoss if you really need J2EE capabilities not available from Tomcat.

Extension Environment

You will need to use this development path either when:
* You are extending an existing portlet portal built-in portlet or a portlet which has been built using the extension environment
* You have found the plugin environment will be not enough for the necessary logic.

Be sure you understand that no changes are done inside the ~/liferay/portal folder which we will create right away.

1. Uncompress liferay-portal-src-5.2.3.zip into ~/liferay/portal

2. Many parameters from ~/liferay/portal/portal-impl/src/portal.properties can be modified but you do so inserting the new values into ~/liferay/ext/ext-impl/src/portal-ext.properties. Many of the properties are actually modified using ~/liferay/ext/ext-impl/src/portal-developer.properties instead (if you do not have it there already just copy it from liferay/portal/portal-impl/src/portal-developer.properties) and deploy it using "ant deploy-properties" from ~/liferay/ext/ext-impl

3. Let us install p6spy so we can sniff JDBC.

Tomcat

Add the below at the end of file ~/liferay/tomcat-6.0.18/bin/setenv.sh:


JAVA_OPTS="-Dp6.home=$HOME/liferay/tomcat-6.0.18/lib/ext $JAVA_OPTS"
Jboss

Insert the below line at the very beginning of ~/liferay/jboss-tomcat-5.0.0/bin/run.sh


JBOSS_CLASSPATH="$HOME/liferay/jboss-tomcat-5.0.0/server/default/db"
Then create file spy.properties

Tomcat


~/liferay/tomcat-6.0.18/lib/ext/spy.properties
 Jboss


~/liferay/jboss-tomcat-5.0.0/server/default/db/spy.properties
Below is the content of spy.properties file. It can be further configured but with the settings below you will be just fine.


#################################################################
# P6Spy Options File #
# See documentation for detailed instructions #
#################################################################

#################################################################
# MODULES #
# #
# Modules provide the P6Spy functionality. If a module, such #
# as module_log is commented out, that functionality will not #
# be available. If it is not commented out (if it is active), #
# the functionality will be active. #
# #
# Values set in Modules cannot be reloaded using the #
# reloadproperties variable. Once they are loaded, they remain #
# in memory until the application is restarted. #
# #
#################################################################

module.log=com.p6spy.engine.logging.P6LogFactory
#module.outage=com.p6spy.engine.outage.P6OutageFactory

#################################################################
# REALDRIVER(s) #
# #
# In your application server configuration file you replace the #
# "real driver" name with com.p6spy.engine.P6SpyDriver. This is #
# where you put the name of your real driver P6Spy can find and #
# register your real driver to do the database work. #
# #
# If your application uses several drivers specify them in #
# realdriver2, realdriver3. See the documentation for more #
# details. #
# #
# Values set in REALDRIVER(s) cannot be reloaded using the #
# reloadproperties variable. Once they are loaded, they remain #
# in memory until the application is restarted. #
# #
#################################################################

# oracle driver
# realdriver=oracle.jdbc.driver.OracleDriver

# mysql Connector/J driver
# realdriver=com.mysql.jdbc.Driver

# informix driver
# realdriver=com.informix.jdbc.IfxDriver

# ibm db2 driver
# realdriver=COM.ibm.db2.jdbc.net.DB2Driver

# the mysql open source driver
#realdriver=org.gjt.mm.mysql.Driver

# mssql open source driver
realdriver=com.mysql.jdbc.Driver

#specifies another driver to use
realdriver2=
#specifies a third driver to use
realdriver3=


#the DriverManager class sequentially tries every driver that is
#registered to find the right driver. In some instances, it's possible to
#load up the realdriver before the p6spy driver, in which case your connections
#will not get wrapped as the realdriver will "steal" the connection before
#p6spy sees it. Set the following property to "true" to cause p6spy to
#explicitily deregister the realdrivers
deregisterdrivers=false

################################################################
# P6LOG SPECIFIC PROPERTIES #
################################################################
# no properties currently available

################################################################
# EXECUTION THRESHOLD PROPERTIES #
################################################################
# This feature applies to the standard logging of P6Spy. #
# While the standard logging logs out every statement #
# regardless of its execution time, this feature puts a time #
# condition on that logging. Only statements that have taken #
# longer than the time specified (in milliseconds) will be #
# logged. This way it is possible to see only statements that #
# have exceeded some high water mark. #
# This time is reloadable. #
#
# executionthreshold=integer time (milliseconds)
#
executionthreshold=

################################################################
# P6OUTAGE SPECIFIC PROPERTIES #
################################################################
# Outage Detection
#
# This feature detects long-running statements that may be indicative of
# a database outage problem. If this feature is turned on, it will log any
# statement that surpasses the configurable time boundary during its execution.
# When this feature is enabled, no other statements are logged except the long
# running statements. The interval property is the boundary time set in seconds.
# For example, if this is set to 2, then any statement requiring at least 2
# seconds will be logged. Note that the same statement will continue to be logged
# for as long as it executes. So if the interval is set to 2, and the query takes
# 11 seconds, it will be logged 5 times (at the 2, 4, 6, 8, 10 second intervals).
#
# outagedetection=true|false
# outagedetectioninterval=integer time (seconds)
#
outagedetection=false
outagedetectioninterval=

################################################################
# COMMON PROPERTIES #
################################################################

# filter what is logged
filter = true
#sqlexpression = .*statement.*

# comma separated list of tables to include when filtering
include =
# comma separated list of tables to exclude when filtering
exclude =

# sql expression to evaluate if using regex filtering
sqlexpression =


# turn on tracing
autoflush = true

# sets the date format using Java's SimpleDateFormat routine
dateformat=HH:mm:ss

#list of categories to explicitly include
includecategories =

#list of categories to exclude: error, info, batch, debug, statement,
#commit, rollback and result are valid values
#excludecategories=info,debug,result,batch,resultset
excludecategories=info,debug,result,batch,resultset,prepared

#allows you to use a regex engine or your own matching engine to determine
#which statements to log
#
#stringmatcher=com.p6spy.engine.common.GnuRegexMatcher
#stringmatcher=com.p6spy.engine.common.JakartaRegexMatcher
stringmatcher=

# prints a stack trace for every statement logged
stacktrace=false
# if stacktrace=true, specifies the stack trace to print
stacktraceclass=

# determines if property file should be reloaded
reloadproperties=false
# determines how often should be reloaded in seconds
reloadpropertiesinterval=60

#if=true then url must be prefixed with p6spy:
useprefix=false

#specifies the appender to use for logging
#appender=com.p6spy.engine.logging.appender.Log4jLogger
#appender=com.p6spy.engine.logging.appender.StdoutLogger
appender=com.p6spy.engine.logging.appender.FileLogger

# name of logfile to use, note Windows users should make sure to use forward slashes in their pathname (e:/test/spy.log) (used for file logger only)
logfile = spy.log

# append to the p6spy log file. if this is set to false the
# log file is truncated every time. (file logger only)
append=true

#The following are for log4j logging only
log4j.appender.STDOUT=org.apache.log4j.ConsoleAppender
log4j.appender.STDOUT.layout=org.apache.log4j.PatternLayout
log4j.appender.STDOUT.layout.ConversionPattern=p6spy - %m%n

#log4j.appender.CHAINSAW_CLIENT=org.apache.log4j.net.SocketAppender
#log4j.appender.CHAINSAW_CLIENT.RemoteHost=localhost
#log4j.appender.CHAINSAW_CLIENT.Port=4445
#log4j.appender.CHAINSAW_CLIENT.LocationInfo=true

log4j.logger.p6spy=INFO,STDOUT


#################################################################
# DataSource replacement #
# #
# Replace the real DataSource class in your application server #
# configuration with the name com.p6spy.engine.spy.P6DataSource,#
# then add the JNDI name and class name of the real #
# DataSource here #
# #
# Values set in this item cannot be reloaded using the #
# reloadproperties variable. Once it is loaded, it remains #
# in memory until the application is restarted. #
# #
#################################################################
#realdatasource=/RealMySqlDS
#realdatasourceclass=com.mysql.jdbc.jdbc2.optional.MysqlDataSource

#################################################################
# DataSource properties #
# #
# If you are using the DataSource support to intercept calls #
# to a DataSource that requires properties for proper setup, #
# define those properties here. Use name value pairs, separate #
# the name and value with a semicolon, and separate the #
# pairs with commas. #
# #
# The example shown here is for mysql #
# #
#################################################################
#realdatasourceproperties=port;3306,serverName;ibmhost,databaseName;mydb


#################################################################
# JNDI DataSource lookup #
# #
# If you are using the DataSource support outside of an app #
# server, you will probably need to define the JNDI Context #
# environment. #
# #
# If the P6Spy code will be executing inside an app server then #
# do not use these properties, and the DataSource lookup will #
# use the naming context defined by the app server. #
# #
# The two standard elements of the naming environment are #
# jndicontextfactory and jndicontextproviderurl. If you need #
# additional elements, use the jndicontextcustom property. #
# You can define multiple properties in jndicontextcustom, #
# in name value pairs. Separate the name and value with a #
# semicolon, and separate the pairs with commas. #
# #
# The example shown here is for a standalone program running on #
# a machine that is also running JBoss, so the JDNI context #
# is configured for JBoss (3.0.4). #
# #
#################################################################
#jndicontextfactory=org.jnp.interfaces.NamingContextFactory
#jndicontextproviderurl=localhost:1099
#jndicontextcustom=java.naming.factory.url.pkgs;org.jboss.nameing:org.jnp.interfaces

#jndicontextfactory=com.ibm.websphere.naming.WsnInitialContextFactory
#jndicontextproviderurl=iiop://localhost:900
Then copy the driver

Tomcat

cp ~/liferay/ext/lib/development/p6spy.jar ~/liferay/tomcat-6.0.18/lib/ext
Jboss

cp ~/liferay/ext/lib/development/p6spy.jar ~/liferay/jboss-tomcat-5.0.0/server/default/lib/
Create the liferay datasources file

Tomcat
 
Edit file ~/liferay/tomcat-6.0.18/conf/context.xml


<Context>
...
<Resource name="jdbc/LiferayPool" auth="Container" type="javax.sql.DataSource" driverClassName="com.p6spy.engine.spy.P6SpyDriver" url="jdbc:mysql://localhost:3306/lportal?useUnicode=true&amp;characterEncoding=UTF-8&amp;useFastDateParsing=false" username="root" password="root" maxActive="100" maxIdle="30" maxWait="10000" />
...
Jboss

Delete ~/liferay/jboss-tomcat-5.0.0/server/default/deploy/hsqldb-ds.xml.
Edit file ~/liferay/jboss-tomcat-5.0.0/server/default/deploy/liferay-ds.xml

<?xml version="1.0" encoding="UTF-8"?>
<datasources>

    <local-tx-datasource>
        <jndi-name>jdbc/LiferayPool</jndi-name>
        <use-java-context>false</use-java-context>
             <connection-url>jdbc:mysql://localhost:3306/lportal?useUnicode=true&amp;characterEncoding=UTF-8&amp;useFastDateParsing=false</connection-url>

        <driver-class>com.p6spy.engine.spy.P6SpyDriver</driver-class>

        <user-name>root</user-name>
        <password>root</password>
        <min-pool-size>5</min-pool-size>
    </local-tx-datasource>
    <local-tx-datasource>
        <jndi-name>DefaultDS</jndi-name>
        <connection-url>jdbc:mysql://localhost:3306/lportal?useUnicode=true&amp;characterEncoding=UTF-8&amp;useFastDateParsing=false</connection-url>
        <driver-class>com.p6spy.engine.spy.P6SpyDriver</driver-class>
        <user-name>root</user-name>
        <password>root</password>
        <metadata>
          <type-mapping>mySQL</type-mapping>
        </metadata>
    </local-tx-datasource>
</datasources>

Modify/Create ~/liferay/ext/ext-impl/src/portal-developer.properties


jdbc.default.jndi.name=jdbc/LiferayPool
Stop server
Deploy using "ant deploy" from ~/liferay/ext
Start server and confirm file "spy.log" appears whenever the server was run from. I commonly enter the home directory and from there start the server. That will start the server from the user home directory. We can then look into the queries from spy.log file, created in the home directory:


tail -f ~/spy.log
4. Customize liferay copying any property from ~/liferay/portal/portal-impl/src/portal.properties and pasting it into ~/liferay/ext/ext-impl/classes/portal-ext.properties. For example to remove the captcha for new registrations use this property:


captcha.max.challenges=0
Below is an important one that removes the chat portlet. You better do it ASAP as it hits performance in your local environment


layout.static.portlets.all=
Run "ant deploy-properties" from ~/liferay/ext and restart the server (Changes through the extension environment require a server restart). Try opening an account to verify the captcha is not there. Another file that can be included to modify default Liferay behaviors is system.properties.

5. Be sure you have now a user account you have created through registration "create account". Do not forget to change the automatic generated password from "my account"

6. There is an ant task deploy-fast to deploy anything below ext-web/docroot into the app server however only tomcat comes predefined there.

JBoss

Go ahead and add the below for that ant task at /Users/nurquiza/liferay/ext/ext-impl/build-parent.xml

        <if>
            <equals arg1="${app.server.type}" arg2="jboss-tomcat" />
            <then>
                <copy todir="${app.server.portal.dir}">
                    <fileset dir="docroot">
                        <include name="**/*.css" />
                        <include name="**/*.dtd" />
                        <include name="**/*.gif" />
                        <include name="**/*.jar" />
                        <include name="**/*.jpg" />
                        <include name="**/*.js" />
                        <include name="**/*.jsp" />
                        <include name="**/*.jspf" />
                        <include name="**/*.png" />
                        <include name="**/*.properties" />
                        <include name="**/*.tld" />
                        <include name="**/*.vm" />
                        <include name="**/*.xml" />
                    </fileset>
                </copy>
            </then>
        </if>




6. From Eclipse create a new java project from existing source pointing to the "ext" folder.
Note: I do not like that much running the server inside eclipse, I prefer just to connect directly to the server debug port.

Tomcat

Add the below line to ~/liferay/tomcat-6.0.18/bin/setenv.sh


JAVA_OPTS="$JAVA_OPTS -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n"
JBoss

Uncomment the below line from /Users/nurquiza/liferay/jboss-tomcat-5.0.0/bin/run.conf


JAVA_OPTS="$JAVA_OPTS -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n"

You will need to restart the server for it to start listening on debug port = 8787
From Eclipse go to Menu|Run|Debug Configuration then right click on "Remote Java Application" and select "New". Select as name "local-liferay" for example. Select port 8787 and then hit "Apply". You should be able to see all current running in the server threads from Menu|Window|Open Perspective|Debug.

7. Create a new java project using plugin folder.

8. Let us customize an existing core portlet. Note that many core portlet use just JSP and helper Java code which does not really respect the MVC pattern. For example the "Dictionary" portlet View code can be seen from the portal source code at ~/liferay/portal/portal-web/docroot/html/portlet/dictionary. Let us copy view.jsp to ~/liferay/ext/ext-web/docroot/html/portlet/dictionary


cp ~/liferay/portal/portal-web/docroot/html/portlet/dictionary/view.jsp ~/liferay/ext/ext-web/docroot/html/portlet/dictionary/
Edit the JSP, run "ant deploy-fast" from ~/liferay/ext/ext-web. Login and confirm changes are there.

9. Plugin SDK Development can be used to develop 5 kind of plugins. They are themes, layouts, portlets, hooks and web plugins. The first two I already introduced in the first tutorial and now I will show how to develop a simple JSP portlet:


cd ~liferay/plugin/portlets
./create.sh plugin_sdk_sample_1 "My first plugin SDK Portlet"
cd plugin_sdk_sample_1-portlet/
ant deploy
At this point portlet "My first plugin SDK Portlet" can be included in any page fo the portal using "Add Application" from the Liferay Dock. The new portlet can be customized changing the view.jsp and the JSPPortlet.java
To use Eclipse you will need to update the "Java Build Path" to point to the src folder of the new plugin and any new plugin you want to build/debug from Eclipse.

10. Extension Development is used to develop and extend existing portlets. Even though the recommended way to develop portlets is using plugin SDK the reality is it has limitations that the extension environment does not have. Let us create a simple JSP portlet called ext_sample_1.
Edit /Users/nurquiza/liferay/ext/ext-web/docroot/WEB-INF/portlet-ext.xml

<portlet>
        <portlet-name>ext_sample_1</portlet-name>
        <display-name>Extension Sample Portlet # 1</display-name>
        <portlet-class>com.liferay.util.bridges.jsp.JSPPortlet</portlet-class>
        <init-param>
            <name>view-jsp</name>
            <value>/html/portlet/ext/ext_sample_1/view.jsp</value>
        </init-param>
        <expiration-cache>0</expiration-cache>
        <supports>
            <mime-type>text/html</mime-type>
        </supports>
        <resource-bundle>com.liferay.portlet.StrutsResourceBundle</resource-bundle>
        <security-role-ref>
            <role-name>power-user</role-name>
        </security-role-ref>
        <security-role-ref>
            <role-name>user</role-name>
        </security-role-ref>
  </portlet>




Edit ~/liferay/ext/ext-web/docroot/WEB-INF/liferay-portlet-ext.xml


<portlet>
   <portlet-name>ext_sample_1</portlet-name>
</portlet>


Edit ~/liferay/ext/ext-web/docroot/WEB-INF/liferay-display.xml


<category name="category.example">
  <portlet id="ext_sample_1" />
</category>



Add file ~/liferay/ext/ext-web/docroot/html/portlet/ext/ext_sample_1/view.jsp with content:


<h1>Hello Liferay extension environment!</h1>

Edit /Users/nurquiza/liferay/ext/ext-impl/src/content/Language-ext.properties


javax.portlet.title.ext_sample_1=Extension Sample Portlet # 1
category.example=Tutorial
Let us deploy the portlet:


cd ~/liferay/ext/
ant deploy
You could also use "ant deploy" from ext-web and from ext-impl.
this takes time. In my local machine 3567 files are copied into ROOT.war and on top of that the server needs to be restarted.
Select "Add application" from Liferay dock. Portlet "Extension Sample Portlet # 1" should show up below "Tutorial" category
11. Let us create now a Struts portlet. Let us call it ext_sample_2:

Edit /Users/nurquiza/liferay/ext/ext-web/docroot/WEB-INF/portlet-ext.xml

<portlet>
                <portlet-name>ext_sample_2</portlet-name>
                <display-name>Extension Sample Portlet # 2 (Struts)</display-name>
                <portlet-class>com.liferay.portlet.StrutsPortlet</portlet-class>
                <init-param>
                    <name>view-action</name>
                    <value>/ext/ext_sample_2/view</value>
                </init-param>
                <expiration-cache>0</expiration-cache>
                <supports>
                    <mime-type>text/html</mime-type>
                </supports>
                <resource-bundle>com.liferay.portlet.StrutsResourceBundle</resource-bundle>
                <security-role-ref>
                    <role-name>power-user</role-name>
                </security-role-ref>
                <security-role-ref>
                    <role-name>user</role-name>
                </security-role-ref>
</portlet>




Edit ~/liferay/ext/ext-web/docroot/WEB-INF/liferay-portlet-ext.xml


<portlet>
   <portlet-name>ext_sample_2</portlet-name>
   <struts-path>ext/ext_sample_2</struts-path>
   <use-default-template>false</use-default-template>
</portlet>


Edit ~/liferay/ext/ext-web/docroot/WEB-INF/liferay-display.xml


<category name="category.tutorial">
  <portlet id="ext_sample_2" />
</category>



Edit ~/liferay/ext/ext-web/docroot/WEB-INF/struts-config.xml


<action path="/ext/ext_sample_2/view" forward="portlet.ext.ext_sample_2.view" />


Edit ~/liferay/ext/ext-web/docroot/WEB-INF/tiles-defs.xml


<definition name="portlet.ext.ext_sample_2" extends="portlet" />
<definition name="portlet.ext.ext_sample_2.view" extends="portlet.ext.ext_sample_2">
  <put name="portlet_content" value="/portlet/ext/ext_sample_2/view.jsp" />
</definition>


Create file ~/liferay/ext/ext-web/docroot/html/portlet/ext/ext_sample_2/init.jsp


<%@ include file="/html/portlet/init.jsp" %>
Create file ~/liferay/ext/ext-web/docroot/html/portlet/ext/ext_sample_2/view.jsp


<%@ include file="/html/portlet/ext/ext_sample_2/init.jsp" %>
<h1>Hello Liferay extension environment (From Struts)!</h1>

Edit /Users/nurquiza/liferay/ext/ext-impl/src/content/Language-ext.properties


javax.portlet.title.ext_sample_2=Extension Sample Portlet # 2 (Struts)
category.tutorial=Tutorial
Let us deploy the portlet:


cd ~/liferay/ext/
ant deploy
12. Any further development you do you will need the portal source so go ahead and download liferay-portal-src-5.2.3.zip and uncompress it to ~/liferay/portal, then create a Java project in eclipse pointing to that folder. All liferay sources are there so you can debug your projects even navigating through the core implementation. It is not a bad idea to point directly to the official SVN TAG repository so you are aware right away if the portal source is locally modified by accident. Remember, all changes must be done from the extension environment and never from the portal source.

13. Existing plugin projects can be hosted in their own project SVN paths, you just need to check those projects into the proper plugin-sdk folder. Do not keep all binary files on SVN. I still do not understand why Liferay does not support maven out of the box.

14. Extension projects most likely will be composed of subfolders of ext-impl, ext-service and ext-web. Try keeping those folders *only* on SVN to minimize download time per project. It is again a very bad idea to host binary files on SVN, especially JAR files. Maven should come to our rescue for this matter.

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

Wednesday, October 07, 2009

Liferay and Semantic WEB

By default most of what you get from Liferay will come full of tables still used for layout purposes.

After knowing about the existence of layouts I went ahead I gave it a try and voila I got rid of tables:

1. Assuming liferay was installed in ~/liferay:

cd ~/liferay/plugin/layouttpl
./create.sh 3-column-with-divs "3 Columns with divs"

2. Edit file ~/liferay/plugin/layouttpl/3-column-with-divs-layouttpl/docroot/3_column_with_divs.tpl

<div id="content-wrapper">
<div id="layout-grid">
<div id="first-div">
$processor.processColumn("column-1")
</div>
<div class="second-div">
$processor.processColumn("column-2")
</div>
<div class="third-div">
$processor.processColumn("column-3")
</div>
</div>
</div>


3. Install the layout:

cd ~/liferay/plugin/layouttpl/3-column-with-divs-layouttpl
ant

4. Now from the Liferay Server login with a proper account and select your newly created layout. Drop simple portlets like "Dictionary" and "Sign in".

5. Take a look at the source code to confirm no tables are doing any layout. If you get any tables they are coming from specific portlets.

Most of the back-end developers that are forced to do look and feel themselves still use tables and so do not expect many out of the box portlets with good separation of concerns even though in year 2009 it should be clear that tables are just to present tabular data.

Followers