Milen Dyankov's blog

Liferay Beginner's Guide - review

2012-02-01T06:34:59Z

As I promised a few weeks ago, in this post I'll share my thoughts about "Liferay Beginner's Guide" book. As with earlier reviews, don't expect any judgments, recommendations or generalizations. Those are to be made by you. I'll only concentrate on what I found interesting (or boring) and worth mentioning (for one reason or another). So let me try to summarize over 350 pages in a few lines.

The first thing to mention is that you will not have to write a single line of code (apart from configuration). This book seems to be meant for ..., hmm. I was about to write "administrators" but thats not the right term here. Please help me find the English term for a adventurous webmaster who goes like - download, make a couple of clicks to configure and then "go live". In another words, I have the impression the authors goal was to show that Liferay is just as easy to install and configure as all these popular CMS systems written in PHP. Whether that's the truth or not, you'll have to decide for yourself.

The first 60 pages will teach you to ... install. No, sure it's not that hard to install Liferay. The book will teach you to install everything you (may eventually) need - Java, MySQL, OpenOffice, and then a combination of Liferay and a few of the major application servers out there (like JBoss, Glassfish, Weblogic). Don't expect any detailed description or explanation of what's where in configuration files. The book goes like "copy the file", "click here" and "type this there". If this procedure fails for some reason, you'll have to look for help somewhere else.

Also the whole installation part assumes your OS is Windows. As most of you probably still use this "state of the art" OS, the approach is probably OK if you install locally to give it try. But once you decide to go on-line, you'll have to either pay the price for Windows hosting or find another book to tell you how to do the same installation and configuration in some "better suited for the net" OS.

The next 200 pages will walk you through portal configuration as well as site and content management. As usual, some things are better explained then other, but if you are a novice you'll get the idea of how Liferay was meant to work. By the way, in case you want my advice, as soon as you think you have figured it all out, go read the chapter again. If the impression remains, switch to more advanced book. No, don't get me wrong, it's not that there is something wrong with the book. Just keep in mind, it was meant to be for beginners and some Liferay features (permissions for example) deserve a book of their own.

The most odd (at least for me) part of the book is in the next 60 or so pages and attempts to explain how to set up an on-line shop. I have to admit, the authors do their best to explain the Liferay's out of the box features in this context. But the question that still bothers me is "Why would beginner be interested in setting up on-line store with Liferay?" I mean, are there chapters about setting up an on-line shops in any "A popular CMS written in PHP beginner's guide" book? I have no idea what was the authors' intention. Perhaps, showing up that Liferay is more than simply CMS. Well it is! It's a portal! But it's definitely not an e-commerce suite! The fact that out of the box you get a couple of portlets which have some basic product catalog and shopping cart functionality, does not make it such. Setting up an on-line store is NOT about having a shopping cart on the web site. It's rather complex subject that requires good understating of security and at least some understanding of what terms like "Product bundling", "SKU", "Price lists", "Upselling", "Cross-selling", etc mean. Sorry for emphasizing this but please trust me, even if you memorize the whole chapter, you are NOT ready to go live with your first on-line store.

OK, this post became too long so time to sum it up. The book is definitely for beginners. But actually it's a good thing, as I don't recall any other Liferay book targeting this audience. So if you are trying to figure out what is Liferay, what it offers and where you are supposed to click, then it may be an useful guide. Of course, It will not tell you the whole story, but at least it will answer most of the questions a beginner asks. It's very likely the book will significantly reduce the time you spend googling for answers. It may even save me and many other people some time, as we would eventually spend less time answering basic questions on Liferay forums ;).

Liferay Beginner's Guide

2012-01-13T10:18:30Z

If you are following any Liferay related sites, forums, tweets, ..., then for sure you've heard about the new book titled "Liferay Beginner's Guide". The book was released in December 2011 and it is getting a lot more attention that I would ever expect. To be honest I'm kind of surprised there are so many Liferay beginners out there. So I volunteered to review the book hoping to check for myself whether all this buzz is only the result of good marketing strategy or it really provides the beginners with the answers they need.

While I don't consider myself a Liferay expert, during the last few years, besides developing Liferay extensions, I had a chance to help a few people start using Liferay in both my company and Liferay forums. I'm curious whether this book would have been any helpful in those cases if it existed back then.

The good news is, a couple of days ago I received my e-book copy and started reading. Hopefully in a few weeks I'll be able to post a review which eventually will help you decide whether it's worth buying. Meanwhile you can check the free chapter to get an idea of how the book is written, organized and styled.

And of course, if you are one of those how have already read the book, do not hesitate to comment and point out things you found good, bad, odd or in any other way worth mentioning.

Simple mobile device emulator in Firefox

2011-10-27T23:22:12Z

After my "Pluggable mobile device detection" presentation during Liferay Europe Symposium a lot of people asked about the mobile device emulator I was using. The truth is, it's not a real "emulator" but a simple combination of html page and a Firefox user script. However, it does the trick and for most people seems to be good enough (at least for a start). So, I made a promise to share it and finally found the time to blog about it.

But before I go into details, here is a short video which demonstrates what it does (for those of you who didn't attend Liferay Europe Symposium and have no idea what I'm writing about):

Now the details. First, make sure you have recent Firefox version installed. You'll also need one of the following Firefox extensions:

NOTE: I've only tested it with Scriptish but it should work with Greasemonkey as well.

Having this in place you are ready to "install" the emulator. It's source code is available on GitHub. The page folder contains the host page together with required js, css and image files. I personally have Apache running locally on my machine so I have these files in its <DocumentRoot> and access the emulator via http://localhost/phone_emulator.html. However feel free to use any HTTP server you like (it may even work if you simply put it into a folder and access it via file:///path/to/folder/phone_emulator.html).

The HTML file provides the GUI:

the URL text box
the device tabs (it uses tabifier library to create the tabs from div elements)
the background image and the iframe element for each device

If you wish to add more devices simply

add the following code replacing ${...} with appropriate values
<div class="device" title="${TEXT TO BE DISPLAYED IN THE TAB}"> <div id="${UNIQUE DEVICE ID}"> <input type="hidden" class="deviceUA" id="${UNIQUE DEVICE ID}_ua" value="${DEVICE'S USER AGENT STRING}" /> <iframe class="deviceResult" id="${UNIQUE DEVICE ID}_result"></iframe> </div> </div>
add appropriate CSS styles to display the background image and position the iframe

Finally, you need to install the user script. Its purpose is to omit "same origin" policy and load requested URL in every available iframe, each time changing the User-Agent header appropriately. The scripts is by default hooked to http://localhost/phone_emulator.html location and will not run if you have placed the HTML file somewhere else. However you may edit the
// @include http://localhost/phone_emulator.html* line and provide one or more different locations.

This is it! Just type http://localhost/phone_emulator.html in Firefox and you should have the emulator runnig. To make sure you have installed it correctly, check the little green Scriptish icon in Firefox's status bar. It should say that 1 user script is enabled.

Disclaimer:
This is not a real emulator and should not be used as such. It was NOT tested and is known to have at least the following issues/limitations:

the rendering is done by Firefox which may support a lot more features then actual device's browser
it only emulates the page in the provided location. If you click on a link it the emulator it will be loadded using standard Firefox User-Agent header!
some Javascripts (particularly Google APIs) and/or CSS may cause conflicts and not display properly

You've been warned, use it on your own risk ;) And of course if you feel you can make it better, extend it or build something else on top of it, go ahead and do so (just let me know).

Liferay - preserve GWT portlet state between reloads

2011-03-23T05:53:31Z

One of the problems with GWT (which is even more noticeable in portal environment) is preserving it's state between page reloads. In a GWT-only application (or single portlet on the page case) one can give user no other option but using only GWT controls to practically avoid page reloads. In most cases however this is not really possible nor wise thing to do. In portlet environments in particular, reloading the page is a very commmon thing to do, giving all portlets a chance to refresh their content after some action has taken place. The thing is, GWT portlets will, by default, render their initial state, which may not be what user expects.

For example, consider the GWT Chatroom portlet I was using in my previous posts Liferay GWT portlet - how to make it "instanceable" and use GWT RPC and Liferay GWT portlet - replacing GWT-RPC with JSON. Imagine user has entered a chatroom. Then she clicks on some other portlet on the page. The page is reloaded and Chatroom portlet returns to it's initial state. The user will have to enter the room again every time she clicks on another portlet. Let's see how this can be fixed.

Many people think about GWT state as a summary of the states of all used GWT widgets (text fields, combo boxes, grids, tabs, ...). Instead I prefer to think in terms of application or "business logic" states. If you change the point of view, it may turn around not all GUI components contain significant information that must be saved and restored. For example it may be not so important to have particular tab selected or value of particular text box updated.

In case of Chatroom portlet, there are 2 states:

initial state - the user is not in a chatroom (she may never entered one or just left one)
chatroom entered - the user is in a chatroom

In fact this is made very clear in the code by providing 2 methods displayInitialState and displayChatroomState responsible for rendering appropriate GUI elements in particular states. Up until now during Chatroom initialization the displayInitialState method was called. To fix the above problem the initialization has to be changed to call appropriate method depending on what is the current state. The question is where (on the client side) one can store portlet state information so it survives page reloads.

The obvious answer is "cookies". However it has some drawbacks (the major one being the fact that they may be unsupported/disabled in some browsers). Fortunately back in 2008 Thomas Frank wrote and made public a very clever JavaScript library called sessvars.js which uses widow.name property to store information that need to survive page reloads. In order to use it in the portlet it has to be added to the page and this is what this commit does.

Now in order to actually save and load portlet state, the ChatroomPortlet object (defined in chatrooms.js) has to be extended with 2 new methods: setState and getState. These methods respectively write to or read from a map (key being portlet id and value portlet state) which thanks to sessvars.js can survive page reloads.

Having this prepared, the Chatroom class can be refactored to render portlet differently depending on it's state. This can be combined with GWT's history mechanism to handle clicks on browser's back and forward buttons. This is how modified the code looks like. Basically the steps were as follows:

provide saveState method to both save the current state and add history token
call saveState method every time portlet state changes
provide handleState method to render portlet UI according to current state
make Chatroom class implement ValueChangeHandler and provide onValueChange method to handle history tokens.
provide getStateFromToken method to retrieve the portlet state from history token.

All of the above mentioned changes are in this commit. Feel free to explore what has changed and how.

Liferay GWT portlet - replacing GWT-RPC with JSON

2011-03-17T17:05:14Z

This is a continuation of my previous post Liferay GWT portlet - how to make it "instanceable" and use GWT RPC. The approach described there uses Liferay specific functionality called PortalDelegateServlet. This way one can easily use GWT RPC which somewhat simplifies client-server communication. However if you need to develop a JSR 286 portlet you need a more standard compatible way of doing AJAX calls. For this reason JSR 286 defines serverResource method and this post will show how to refactor the code to replace GWT RPC calls with exchanging JSON messages using serverResource method.

Let GWT know the prtlet URLs

First thing to do is to tell GWT what are the proper URLs to call the portlet. Therefore creating a Chatroom instance based on portlet id only, is no longer enough. To overcome this you need to provide a JavaScript object holding portlet URLs. I, for example, have called it ChatroomPortlet and it's defined in chatrooms.js file.

Then, in view.jsp, create and store that object instead of portlet id. Of course for the purpose of this example only resourceURL is needed but in a real world scenario you'll probably also need renderURL and actionURL. To map this JavaScript object to GWT class create JSNI class ChatroomJsObject

Next you need to modify Chatroom's constructor to accept ChatroomJsObject instead of String representing portlet id. Of course this reflects how GWTEntryPoint creates Chatroom instances.

Have a look at my commit to see what has changed.

Create the JSR 286 portlet

Now you need to write a portlet and implement serveResource method. Basically the method contains the same logic that used to be in ChatroomServiceImpl. The only difference is that now it gets its input form JSON object and responds with JSON object. The portlet code is available here. Of course don't forget to replace the default MVCPortlet with your own in portlet.xml

Again there is commit which does above modifications, so you can check what has changed.

Update GWT client-server calls

Having the portlet ready, it's time to change the GWT code to send and receive JSON to resourceURL instead of using GWT RPC. For this to work you need to add 2 GWT modules to Chatrooms.gwt.xml:

<inherits name="com.google.gwt.http.HTTP" /> <inherits name="com.google.gwt.json.JSON" />

To be able to convert JSON response to GWT class you'll have to provide another JSNI class ChatroomMessageJsObject. Finally the Chatroom class itself needs to be updated:

replace the body of sendMessageToServer method to create JSON object and send it to the portlet bu using RequestBuilder
replace the body of getMessages method to covert JSON object from response to list of ChatroomMessageJsObject to be displayed.
convert lastMessageTime form Date to long as there are some issues with passing dates in JSON

As usual you can refer to my commit to get an idea what and how has changed.

That's it. You are ready. Optionally you can do some cleanup by removing unused classes like I did.

Liferay multi-device extension

2011-03-10T04:52:15Z

Almost every portal related RFI/RFP my company has received in the last couple of years contained some requirements about mobile version. Fortunately the times when every device had it's own idea of how web content should be served are gone. Nowdays we can afford to pretty much ignore WML, C-HTML, ... as almost any modern device understands at least XHTML Mobile Profile. However this does not always mean there can be one mobile version for all. Here are some typical requirements:

make a dedicated version for iPhone (imitate iPhone interface to make it look like native application)
allow to switch between mobile and desktop version if device is smartphone
provide alternative input methods if device does not have QWERTY keyboard
design dedicated version for tablets

I have spent some time thinking about how to address this issues with Liferay Portal. Having some experience with WURFL, Volantice and designing web applications for mobile devices in general, I thought it would be great if I could dynamically change Liferay's look and feel based on device capabilities. And this is how Liferay multi-device extension was born.

Actually now there are 3 Liferay plug-ins which work together to deliver this functionality:

multi-device-ext plugin (https://github.com/azzazzel/liferay-multi-device-ext) is the core plug-in. It provides the look and feel change logic, generic data model and "extension points" for other plug-ins which deliver things like device recognition and rule definition. It does so by employing Liferay's internal bus and can dynamically switch to new implementation when compatible plug-in is deployed. If you know how to replace Lucene with Solr, you know what I'm talking about.
wurfl-web (https://github.com/azzazzel/liferay-wurfl-web) plug-in delivers device recognition based on WURFL. It contains WURFL API but does not contain WURFLD DB and patches. By default it expects to find the database in ${liferay.home}/wurfl/wurfl-latest.zip however you may change this in portal-ext.properties:

# Wurfl's main devices file wurfl.main=${liferay.home}/wurfl/wurfl-latest.zip # Wurfl's patch files wurfl.patches=

device-rules-hook (https://github.com/azzazzel/liferay-device-rules-hook) extends Liferay's look and feel management interface by adding additional tab "Device Rules". At the moment rules can be based on device's brand, model, operating system, browser and pointing method as well as whether the device is tablet, has QWERTY keyboard

Here is how it works:

The plug-ins are not yet in Liferay community plug-ins repository. I could'n figure out how to upload the EXT plugin and the other two make no sense without it. You can download plug-ins from here: http://sourceforge.net/projects/liferaymultidev/files/ or get the source code from https://github.com/azzazzel and build them yoursef. If you do so, please let me know what you think.

Liferay GWT portlet - how to make it "instanceable" and use GWT RPC

2011-01-29T14:46:35Z

Every once in a while somebody asks about writing Liferay portlets in GWT. It seems a lot of people are successfully using GWT with Liferay but surprisingly I couldn't find any complete tutorial on the subject. There are a of course tutorials explaining the basics but what they concentrate on, is how to build single-instance and client-side-only portlets. This is good enough to get you started but chances are sooner or later you'll need to place two instances of the same GWT portlet on the same page and/or implement GWT RPC to make use of the Liferay services.

I've reached that point myself sometime ago and unfortunately had to solve the problem myself. Then I wrote sample portlet called gwt-chatrooms-portlet to demonstrate the solution and hopefully save you some time. So here is a step by step tutorial how to create GWT portlet for Liferay 6.0.5 which:

allows many instances to be placed on the same page
uses GWT RPC for client-server communication

The gwt-chatrooms-portlet is very simple portlet allowing users to enter chat room (by typing in it's name) and then chat with other users. Here is screenshot :

As you can see, multiple instances can be added on the same page allowing users to chat in more than one room at a time. Message persistence API is generated using Liferay's ServiceBuilder. The GWT client code uses GWT RPC to receive room messages from the server and store new ones. Here is how to build it.

Generate the portlet in Liferay SDK

OK first things first. Make sure you have Liferay 6.0.5 and Liferay plugins SDK-6.0.5 installed and configured. Then create new portlet by tying :
create.sh gwt-chatrooms "Chatrooms - Sample GWT portlet"
in <LIFERAY_SDK_HOME>/portlets. This will create gwt-chatrooms-portlet folder and the standard set of files. This is in my first commit.

Add GWT compile task to the build

Before you continue with actual development, you have to add an ant task to <LIFERAY_SDK_HOME>/portlets/gwt-chatrooms-portlet/build.xml responsible for compiling GWT code. The code is available here. You have probably noticed my task uses ${gwt.sdk} variable. To use it as is you have to set it's value in <LIFERAY_SDK_HOME>/build.<USER_NAME>.properties file :
gwt.sdk=<GWT_HOME>

Create GWT module and entry point class

Now you are ready for GWT portlet development. Create GWT module file gwt-chatrooms-portlet/docroot/WEB-INF/src/com/commsen/sample/portlet/chatrooms/Chatrooms.gwt.xml

<module rename-to='Chatrooms'>
  <inherits name='com.google.gwt.user.User'/>
  <inherits name='com.google.gwt.user.theme.standard.Standard'/>
  <entry-point class='com.commsen.sample.portlet.chatrooms.client.GWTEntryPoint'/>
  <source path='client'/>
  <source path='shared'/>
</module>

and GWT entry point class <LIFERAY_SDK_HOME>/portlets/gwt-chatrooms-portlet/docroot/WEB-INF/src/com/commsen/sample/portlet/chatrooms/client/GWTEntryPoint.java

public class GWTEntryPoint implements EntryPoint {
   @Override
   public void onModuleLoad() {
      RootPanel.get("chatrooms-portlet").add(new HTML("This is the <b>GWT chat rooms</b> portlet."));
   }
}

In view.jsp remove the default message and add div element with id "chatrooms-portlet" - this is the container for GWT code. Next replace default value of "footer-portlet-javascript" in <LIFERAY_SDK_HOME>/portlets/gwt-chatrooms-portletdocroot/WEB-INF/liferay-portlet.xml with "/Chatrooms/Chatrooms.nocache.js" (assuming "Chatrooms" is the name of your GWT module). Here are my changes.

Before you deploy and see your portlet in action you need to also add

<ajaxable>false</ajaxable>

into portlet's configuration in liferay-portlet.xml file to make sure Liferay will not use AJAX to load portlet's content . However if you try to place 2 instance of the portlet on the same page you'll be surprised that one of them (or even both in some browsers) shows up empty. This is because the HTML page now has more than one div element with the same id "chatrooms-portlet".

Make GWT code recognize portlet instances

To overcome the problem you can make use of portlet's instance id and add it to the id of the div element in every portlet. To prepare for this change, create a javascript array (say chatroomPortletInstances) to hold portlet instance ids. Here is how I did it. Then modify view.jsp so that it adds the portlet id into chatroomPortletInstances and make the div id contain the portlet id. See my code for example.

Now you need to let the GWT code "know" about portlet instances. So instead of doing all initialization in the entry point class (which I consider bad practice anyway) create a dedicated class (say Chatroom) with constructor accepting portlet id as parameter. This way you can create dedicated Chatroom instance for every portlet instance. In order to do that you need to know the ids of all portlet instances available on the page and this is where chatroomPortletInstances array comes in. Thanks to GWT's JSNI is as easy as

public static native JsArrayString getPortletInstances() /*-{ return $wnd.chatroomPortletInstances; }-*/;

Now all that's left is to iterate over portlet instances and create Chatroom instance for each. Of course feel free to use my code as example.

Now you can place as many GWT portlet instances as you wish on the same portal page!

If you want to test it, go to portlet's folder ant type

ant clean gwtc deploy

Generate Liferay services with ServiceBuilder

The portlet needs to persist the chatrooms' messages in Liferay's database. Thus you need to have at least some services and persitence API on the server side. Fortunately with Liferay's ServiceBuilder almost everything can be generated by providing a single XML file. Here is the one I used. I'm not going to explain in details how ServiceBuilder works (please see Liferay's documentation). In case you are not really trying to learn but simply follow the instructions, here is the one-liner: Place the XML file in WEB-INF folder and then doant build-serviceit will generate everything you need.

The most important things to notice are the Message interface (represents chatroom message) and the MessageLocalServiceUtil class which provides convenient static methods for creating, storing and retrieving Message objects. By the way this commit contains all the files generated by ServiceBuilder in case you are curious.

Implement the view and GWT RPC

Finally it is time to get your hands dirty with some real GWT stuff. First you need to create standard GWT RPC service to save and receive messages. So create the ChatroomService and ChatroomServiceAsync interfaces in client code and ChatroomServiceImpl in server side code. They need to have 2 methods saveMessage and getMessages.

In the implementation code of those methods in ChatroomServiceImpl you can call appropriate methods form MessageLocalServiceUtil or use Liferay's utility class PortalUtil to get access to other Liferay services (for example to get the current user). Here is what I did.

Then you need to code the view. It's really up to you how you design the front end but of course I'll use my version of Chatroom class to point out the key elements:

sendMessageToServer method uses ChatroomService to send user's message
getMessages method is continuously called by GWT timer to refresh the chatroom view
somewhat mysterious code at line 52

By now you may think that you are ready. Simply configure ChatroomServiceImpl servlet in web.xml, compile, deploy and enjoy. In fact if you do so, there will be unpleasant surprise. The problem with this standard GWT approach is that you will be calling the ChatroomServiceImpl servlet directly and not through the portal. This means the portal will never have a chance to do it's magic. This means non of it's service classes will be available for the servlet. This means you'll see a nice NoClassDefFoundError in your server's logs.

Luckily since version 4.3.x Liferay has built in solution for this problem. It's called PortalDelegateServlet. I'm oversimplifying the concept here but basically it allows you to define a servlet in portal's context. There is special delegate servlet, mapped at /delegate location. Liferay extensions can configure sub-contexts to redirect to their own servlets after the portal is done with the magic. Having this in mind there are 2 more things you need to do:

configure your portlet to use PortalDelegateServlet
change the address of your servlet in GWT's front-end code

For the first one have a look at how I have done it and for the second one ... well that is the "somewhat mysterious code at line 52" mentioned above. Of course complete list of changes described in this section is in my final commit.

And this is it. Compile, deploy, enjoy!

Liferay User Interface Development

2010-12-11T15:56:00Z

The last 6 months were extremely busy for me. A lot had happened in both private and professional aspects. Having that in mind I'm quite happy I manged to deal with completely new experience - being a technical reviewer of "Liferay User Interface Development" - a new book published recently by Packt Publishing. Despite the lack of spare time I was somehow able to read and comment on drafts of 10 chapters covering things like theme development, layout templates, velocity templates, tag libraries, AlloyUI, and much more. Hopefully my comments and opinions ware useful for the authors and help them improve the book.

I still don't have the published book (I'm about to receive my copy soon) but based on what I have read in the drafts I can say it's worth recommendation. The book puts together most of the peaces related to UI development in Liferay. Of course it does not cover all the details (no book can do this) but it often goes beyond the basics. In fact one of the chapters I found very informative and well organized is freely available on-line (http://www.packtpub.com/sites/default/files/2626OS-Chapter-5-Advanced-Theme.pdf) so you can check for yourself. There is also quite good chapter about AlloyUI - especially useful if you have to move form Liferay 5.2 to Liferay 6.0 and replace JQuery with AlloyUI. The migration and upgrade process is also one of the subjects in the final chapter "User Interface in Production" which among others covers things like workflows, social UI and friendly URLs.

Of course, there are too many options when it comes to UI development (JSF, Struts & Tiles, Vaadin, JQuery, AlloyUI, Liferay UI taglib, Velocity, Freemarker to mention just a few) and it's not possible to describe them all in details. This book concentrates on Liferay's approach to UI development which (in version 6) is a powerful mix of Velocity templates, tag libraries and AlloyUI. And yes, if you use Vaadin or JSF or Freemarker for your day to day work, it may not be a book for you as all you'll find in it about this technologies is references to online recourses. But going back back to "standard" UI approach, the authors really try to teach the reader by providing many examples, mini tutorials and references to portal's and portlet's source code.

One thing I was pointing out while reviewing the book was the lack of good reference documentation in two areas: tag libraries and Velocity variables and macros . One may argue whether such a book is the best place to provide such documentation. Maybe not, I'm not sure. On the other hand comparing the number of questions posted on Liferay's forums about what tags are available and what their parameters mean with briefness of documentation available at http://docs.liferay.com/portal/6.0/taglibs, makes me thing that more in depth information on the subject would make this book more attractive for wider group of Liferay users. Same thing about Velocity macros and variables. Event the most advanced reference about velocity variables in Liferay I know about - http://www.myoffice24x7.com/web/manual/howto/explore-velocity-variables/-/velocity-explorer/journal - seems to be incomplete and sometimes inaccurate. I don't know if my suggestions were taken into account. Honestly, I doubt the authors had enough time and room to be able to dig deeply into those subjects. But hopefully at least those tags, variables and macros used in the examples and better described.

But please don't get me wrong. The fact that I will always point out something that in my opinion can be done better does not mean the book is bad. Assuming one don't need to get deeply into Liferay's internals and do not worry too much about what exactly any particular line in the sample code does, this book provides complete information about Liferay UI development. I personally learned a lot of new things although I've been using Liferay for a few years. The bottom line is: whether you have been mastering Liferay portal for a while or just entering the world of Liferay, this book will help you understand how to develop complex and user friendly user interfaces in Liferay Portal 6.0

Liferay plug-ins adapted to work with Liferay 6.0.5

2010-11-08T21:12:16Z

As soon as Liferay 6.0.5 was released I decided to adapt my plug-ins to the newest framework version. But as we all know, being determined to do something is not the same as having the time to do it. The good news is, a few days ago I finally quit saying myself "never mind, you'll do it tomorrow" and started getting things done. And now I'm happy to announce that Custom Global Markup, Tailgate and Liferay-UI Taglib Demo are already upgraded to work with Liferay 6.0.5.

Please read my previous posts "Custom global markup portlet" and "Writing Liferay portlet to display a file in a way "tail -f" does" for more information about Custom Global Markup and Tailgate respectively.

The plugins for 5.2.3 versions ware build by liferay-maven-sdk and this was one of my biggest concerns. I was a bit warred about how difficult will be to move to the native Maven support in Liferay 6. However, not trusting my own experience and struggling to think logically, I realized it should be only a matter of modifying the POM. And indeed it was. I simply removed 5.2.3 dependencies and maven plugins and added 6.0.5 ones (here is the diff) and I was able to build my plugins using Liferay's 6 maven artifacts. Even ServiceBuilder worked without problems and additional configurations.

Apart from adapting the code there is one more significant change. While version control and issue tracker remain on GitHub, binary files were moved to new SourceForge project called "liferay-plugins". You are welcome to visit it and download, comment, rate, review, .... There are also some screenshots of the plug-ins.

While I thought having screenshots is cool, a (much younger) collegue of mine, pointed out that these days every self respecting project has instructional videos on YouTube. Well, my generation didn't spend their whole childhood in front of the TV so please excuse my ignorance. Not to give anyone another reason to complain here are the videos:

Just added 'J' in front of WebThumb

2010-07-22T22:21:42Z

Yep, good guess, a Java API to bluga.net webthumb in now available. Making your Java application display website thumbnails is now something really easy to implement. Get your API KEY form bluga.net webthumb, download JWebThumb and start requesting and fetching thumbnails with just a few lines of code.

Why bluga.net webthumb? Nope, I'm not gonna tell you it's the best tool out there, having unique features, ... or any of this marketing bla bla. The truth is, it was the first tool I found, that met my requirements

custom size thumbnails
support for both JPG an PNG
web services or REST based API
either creates thumbnail instantly or sends notification when done
free version

I gave it a try and it turned out it's quite fast and reliable. Not that I have been heavily using it, but so far I haven't had any problems with it. Most of the time when I request a thumbnail it estimates it will take about 20 second but in fact my servlet receives notification in less than 2 seconds.

So, after a few days of playing with webthumb's API I had a pile of Java snippets testing different aspects of it. Organizing the chaos resulted in version 0.1 of JWebThumb project. Added data model and error handling on the top of that and 0.2 version was ready to go public (under LGPL). As usual Maven helped create a project site from where you can learn how to use JWebThumb, the source code is on GitHub and downloads are available on SourceForge. If you find a bug or missing feature don't hesitate to create an issue.

I consider 0.2 an early beta version. It works but it's not extensively tested and may have bugs. It uses XStream for XML serialization and deserialization thus you can not yet use it on GAE. So version 0.3 is already underway having XStream replaced by Simple so it works on GAE. But before I release it I would like to test it a bit more and perhaps add support for 'status' requests missing in 0.2. So stay tuned, it shouldn't take too long.

More "Simple" than "XStream"

2010-07-19T22:56:21Z

I guess every Java developer dealing with JAVA/XML serialization/deserialization knows about XStream. I was using it for years until yesterday. What happened yesterday? I found out XStream dos not work out of the box with GAE. Well is's not exactly XStream's fault. A lot of stuff does not work properly with GAE due to its limitations and odd security restrictions. But my hope to quickly find patch/workaround, went away as soon as I realized the problem was reported to XStream over an year ago (http://jira.codehaus.org/browse/XSTR-566) and there is still no good solution.

This way I was forced to look for alternatives. And I found Simple! Conceptually it's a very similar to XStream. Serialization is really simple to use and revolves around several annotations and a single persister object. I got the impression it's noticeably faster than XStream. It's feature list is quite long (it even claims to be bean version tolerant) but so far I've used the standard stuff like converters, transformers, persister, etc.

However since "Simple"

does not depend on 3rd party libraries
is available in central Maven repository
works out of the box with GAE
is capable of doing everything XStream is doing

it's about to become my number one XML serialization/deserialization tool. At least until I discover it's dark sides.

Liferay Portal 6 Enterprise Intranets review

2010-07-04T07:56:19Z

A few weeks ago I was asked by Packt publishing to review the new Liferay Portal 6 Enterprise Intranets book. Going through over 650 pages took me some time but finally I'm ready to share my thought about it.

By now you are probably scanning the text for something like "In general this is ____ book". Don't bother, I'm not going to generalize in this post. In fact, what you put in place of ____ depends on who you are, what is your Liferay background, and what you expect to learn.

I'm a software developer and I have been using Liferay for a few years now. When I heard about the book, my imagination draw a visions of me learning "how Liferay internal mechanisms work" or "what some of those strange configuration parameters are used for" or "how to tweak portlets' functionality and performance" or ... Of course, none of this had happened! This does not mean the book is bad, it only means I had too big expectations. If you are like me, then you may even get bored trying to read it form side to side.

One thing that I really miss in this book is pointing out what's new in Liferay 6. I know well 5.2.x version and I would appreciate a special style or sign indicating new (or updated) feature in Liferay 6. This way more advanced readers could concentrate on things that are potentially of their interest and skip the part they are already familiar with. If it wasn't for the review I would probably scan through the first few chapters for things I don't know (and yes there are some interesting features to learn even if you already know Liferay) and then pay more attention at the last ones. The good news is the chapter 11 called "Ongoing Admin Tasks" is freely available online so you can have a look and see how it compares to the level of your knowledge.

But since "This book is for system administrators or experienced users (not necessarily programmers) who want to install and use Liferay in their teams or businesses without dealing with complex code. Prior knowledge of Liferay is not expected for this book." I decided to pretend I know almost nothing about Liferay and simply followed the instructions in the book (I wish I had the PDF version, it would save me some typing). When I got rid of "come on, I already know all this" attitude, I had to admit the book is quite well organized. Each chapter typically starts with explaining the basic functionality then goes through some configuration options and ends up instructing the reader how to define appropriate permissions. Sure, after the first two chapters you already know the pattern for defining permissions and there is no need to repeat it over and over again. But on the other hand if you intend to later one use the book as a quick reference or cheat-sheet, it may come handy.

The book will explain almost (as with every book the thing you are particularly interested in, will be probably missing) every intranet feature you may need. Moreover it sometimes goes a bit off topic as I can hardly imagine configuring WAP or SEO for intranet site. It will not give too much details though, only enough to get you started and sometimes make small customizations. For example, it will not tell you how exactly portlet properties affect Liferay, but will give you a list of all properties related to current component with short explanation.

Being frequent reader of Liferay forums I'm convinced there is need for such book. The number of questions starting with "How can I ..." speaks for itself and from what I've noticed people are already referring to this book for answers. But even if you are more advanced Liferay user, you may still find in the book valuable information about open search, clustering, reporting and audit logging, integration with Alfresco, CMIS and many others. Just remember, don't expect too much details.

Writing Liferay portlet to display a file in a way "tail -f" does

2010-05-03T22:10:42Z

Don't know about you but I can't imagine debugging enterprise class applications without having "tail -f /path/to/log.file" running in dedicated console window. During development and testing phases (assuming work is done "in house") there is usually no problem with this approach as the whole team have access to servers' log files. This is not always the case with staging and production environments though. These days a lot of companies execute strong security policies which sometimes means that application is only accessible via HTTP. In such case, depending on how you SLA looks like, "log files provided on demand via e-mail or FTP" may not be an option.

Facing this kind of problem in recent Liferay based project, made me think about creating a portlet capable of displaying log files. Something like WWW based version of "tail -f". This is how Tailgate was born (for those of you looking for solution here is download page). The rest of this post will concentrate on explaining why it was not "a max 2h of coding" as I thought in the begging.

Tailgate portlet needs to dynamically show new lines as they are written to the file without reloading the whole portal page. Assuming one portlet instance is configured to display only one file, the solution appears to be straightforward and rather simple:

while page is displayed { browser sends AJAX request server checks if there are new lines in given file server responds with list of new lines browser adds lines to appropriate DOM element }While this is in general the whole functionality, there are a few things to consider on both front-end (client) and back-end (server) side.

front-end

As far as front-end is concern there are 2 main things to consider:

Multiple instances on the same page

This is a bit tricky and requires good understanding of how portals work. When a portlet is developed it contains common code for all instances. So if multiple instance can be placed on the same portal page then the common code should be able to distinguish instances. This is even more important with AJAX requests.

In this case we have a common logic for sending and receiving AJAX requests and updating DOM model. However when portlet instance sends AJAX requests it needs to provide instance specific set of parameters as part of the URL. Also when response is received only DOM elements belonging to this particular instance need to be updated.

The common JavaScript code is provided in tailgate.js file. The portlet uses also jQuery timers module (jquery.timers.js) which provides high level abstraction of setTimeout and setInterval. These files are part of the portlet code. Including them in HTML page is done by adding

<header-portlet-javascript>/js/jquery.timers.js</header-portlet-javascript> <header-portlet-javascript>/js/tailgate.js</header-portlet-javascript>

to WEB-INF/liferay-portlet.xml. This way Liferay will add appropriate links in HEAD section of HTML page and will do this only once regardless of how many portlet instances page contains.

The tailgate.js defines the Tailgate object and tailgateInstances map for holding information about Tailgate instances:

var tailgateInstances = new Array(); function Tailgate(lines, url) { this.lines=lines this.url=url }

When portlet instance is rendered it takes care to prefix DOM element ids with it's namespace

<button id="<portlet:namespace />_start">Start</button> <button id="<portlet:namespace />_stop">Stop</button> ... <ul id="<portlet:namespace />list" class="tailgate">

, add itself to tailgateInstances map

<script type="text/javascript"> tailgateInstances["<portlet:namespace />"] = new Tailgate(<%=prefs.getValue("lines","100")%>, "<liferay-portlet:resourceURL />");

and pass the namespace to called functions

jQuery("#<portlet:namespace />_start").click(function(){ startReading("<portlet:namespace />"); }) jQuery("#<portlet:namespace />_stop").click(function(){ stopReading("<portlet:namespace />"); }) </script>

Note that all functions in tailgate.js are designed to accept namespace as parameter. This way when called they can either get appropriate Tailgate instance from tailgateInstances map and then check for given property (for example url), or find and update DOM elements prefixed with this namespace.

Control the CPU and memory usage

Monitored file can change very fast (application could add few megabytes is just a second) therefore at first it seems to be very important to query back-end as often as possible. This however results in very high CPU usage. In fact going down below 10ms may force you to kill your browser in order to recover your system. Experimenting with different values I finally decided that refresh rate of one second is a reasonable compromise.

Another thing is memory. If lines are only added but never deleted then after a while the browser will be trying to display a tens of megabytes of HTML code. Therefore Tailgate is configured to only display last X lines. It renders each line as <li> element and when new line is added, a new <li> element is added to the parent <ul>. Then it checks the size of <ul> and if it's bigger than X, old lines are deleted from DOM model. Luckily jQuery comes with convenient methods so this is really easy to implement:

jQuery('#'+namespace+'list').append(data); var maxLines = tailgateInstances[namespace].lines; var lines = jQuery('#' + namespace + 'list li').length; if (lines > maxLines) { jQuery('#' + namespace + 'list li').slice(0, lines - maxLines).remove(); }

back-end

The line "server checks if there are new lines in given file" in the above pseudo algorithm is also way oversimplified.

The RandomAccessFile class provides the functionality to position at specific place in file and start reading. However creating a new instance on every request is not a very smart thing to do. Even if it is somehow cached per portlet instance, there still could be many instances monitoring the same file (in the future each may provide different filtering, highlighting, etc.) Also, depending on what file system is used (for example old versions of NFS), there may be some locking issues when multiple threads try to access the given file at the same time. Therefore it looks like the optimal solution would be to have one thread continuously reading the file and updating in memory buffers provided by specific instances. Here is the activity diagram:

This looks simple enough but again there are a couple of things to think about:

synchronization

Since there are two thread operating on the same buffer (one writing and one reading) the buffer's read and write operations need to be synchronized. Otherwise a typical Memory Consistency Errors may occur.

buffer size

Buffers need to have fixed size in order to avoid memory leaks! Since the front-end also displays a limited amount of data, the same configuration parameter can be used to define both the number of lines displayed and buffered. Then every time a new line is added to the the oldest one is removed if buffer the size is reached:

public boolean addLine(final String line) { boolean result; synchronized (buffer) { result = buffer.add(line); if (buffer.size() > maxSize) { buffer.remove(); } } return result; }

when to stop reading

If you have carefully examined the activity diagram above you may have noticed that buffers are never unregistered. This is not an error, it is simply impossible to tell when a buffer is no longer needed. One may argue that user could send us appropriate message by clicking on something saying "I'm done watching, please stop the buffer!". My experience shows such approach is often misunderstood and misused (by that I mean used too often or not at all). So how can one prevent FileMonitor thread from running forever (it will run as long as there are buffers)? Let the garbage collector do it's job!

Buffers are stored in portlet sessions, so instead of relaying on user interaction, Tailgate relays on buffers being garbage collected once portlet session is closed. As you probably know an object becomes eligible for garbage collection when there are no hard references to it. Is this the case with buffers? As the diagram shows, buffers are referenced in 2 other places (marked in red) - FileMonitoringEngine needs to keep track of which buffer is assigned to which monitor and FileMonitor needs to maintain a list of buffers to write to. But here is the difference, in order to leverage the garbage collector's ability to determine buffers' reachability, both FileMonitoringEngine and FileMonitor use weak references. FileMonitoringEngine uses in fact standard WeakHashMap to store the mapping. FileMonitor only needs a Set of weak references but there is no WeakHashSet class. In JDK 6 there is a convenient "newSetFromMap(Map<E,Boolean> map)" method available in java.util.Collections class. In order to be compatible with JDK 5 the behavior of this the JDK 6 method had to be implemented as part of Tailgate portlet.

This way as soon as portlet session gets garbage collected there are no hard references to the buffer and it is collected as well. When all buffers are garbage collected the FileMonitor thread ends. The first request instantiating new buffer will start new FileMonitor thread which will again run as long as there is someone interested in receiving results.

Conclusion

I'm well aware I'm not writing anything really revealing here. But after spending some hours on Tailgate portlet I thought I would write about the problems and solutions. Hopefully you at least learned a little something from this experience. In case you are interested, Tailgate's source code is available at GitHub.

Custom global markup portlet

2010-04-05T22:40:01Z

What would you do if a customer demands to "integrate" his Liferay based corporate portal with Google Analytics, Geminus, ClickTale, Crazy Egg, and whole bunch of other analytics tools available out there?

As you probably know, such services typically provide some piece of javascript (code or file) which needs to be added to every page of monitored web site. Each service also provides unique customer code/key (which is either already part of the javascript provided or needs to be placed in specific place). Regardless of whether using all of them at the same time is a smart thing to do, there are a few technical problems to solve:

How to add custom code to every portal page
How to deal with unique codes/keys through development, testing, staging, production phases
How to minimize the impact of changing/removing custom code in production environment

There are few ways to solve the first case

Make the code part of the theme.

This is easy to do but it has some drawbacks. First of all, depending on how theme is applied, the code may end up on every page in every community or only in few rarely visited pages. Also if your portal uses a number of themes than you need to either make a common theme and make the rest extend it, or you need to add it to each theme. This approach may be a serious maintenance challenge.

You may solve the problem with unique codes/keys by using portal properties but you'll not be able to easily modify or remove the java script code if you have disabled (and you should) hot deployment on production servers.

Create custom portlet and add it to every page.

Samuel Kong's excellent post http://www.liferay.com/web/samuel.kong/blog/-/blogs/adding-a-javascript-to-every-page explains how to add javascript to every page. However be aware that if you blindly follow the example you'll add the code to EVERY page (not every page in given community). Following this approach you'll have to choose between two options

one portlet having all javascript codes
separate portlet per javascript code (or group of codes)

The first one is only acceptable if all javascript codes can ALWAYS be placed together and it kind of violates the "design by responsibility" concept. The second approach on the other hand deploys a lot of boilerplate code which in some cases may have impact on performance.
Unique codes/keys may be provided in portlet preferences but still it's not very convenient when portlets are automatically added via layout.static.portlets.all property. Also, as you have probably guessed, this approach does not solve the problem with modifying/removing javascript code in production environment.

Use custom-global-markup-portlet

custom-global-markup-portlet was written to solve all of the problems described above. The portlet is based on Samuel Kong's example, but it also provides convenient management interface in Liferay's control panel:

As you can see from the above screenshot portal administrator can easly add/modify/delete any markup (javascript, CSS, HTML, ...). Here is how the portal look like after you save the above markups:

As you may have already noticed there are a few important features. First of all the markup can be divided into multiple entries and each entry can be enabled/disabled and placed on top (in <head> section) or bottom (before </html>) of the page. All entries are persisted into database which eliminates potential problems with maintaining different portlet preferences in different environments (development, staging, production). Also note that custom-global-markup-portlet is community scoped, which allows adding markup to pages of specific community.

You can download the latest version of custom-global-markup-portlet here: http://github.com/azzazzel/Liferay-plugins/downloads. It is part of Commsen Lifery plugins which is free and open source project hosted at GitHub and released under LGPL license. It is developed with liferay-maven-sdk and uses Git SCM

Creating Liferay portlet with liferay-maven-sdk

2009-10-09T21:47:50Z

This post will demonstrate how liferay-maven-sdk can be employed to build a Liferay portlet using Liferay's Service Builder feature. For this purpose we will create service-builder-portlet which is capable of displaying a list of players and adding a new player to this list. The model, persistence layer and data access services will be generated by Service Builder.
But first things first. Download and install liferay-maven-sdk if you haven't done so already (have a look at "Download and Install" page for instructions). Once liferay-maven-sdk is installed in your local repository, you can create the portlet.

So enter the folder (or create one) where you keep your portlets and execute

mvn archetype:generate

you should see a list of available archetypes starting with

Choose archetype: 1: local -> liferay-portlet-archetype (Liferay portlet archetype) 2: local -> liferay-theme-archetype (Liferay theme archetype) 3: internal -> appfuse-basic-jsf (AppFuse archetype for creating a web application with Hibernate, Spring and JSF) 4: internal -> appfuse-basic-spring (AppFuse archetype for creating a web application with Hibernate, Spring and Spring MVC) ... Choose a number: (1/2/3/4/...) :1

Type 1 and press enter to choose liferay-portlet-archetype. Then provide groupId, artifactID, package and version. For example:

Define value for groupId: : com.commsen.liferay.examples.portlet.servicebuilder Define value for artifactId: : service-builder-portlet Define value for version: 1.0-SNAPSHOT: : 1.0 Define value for package: com.commsen.liferay.examples.portlet.servicebuilder: :

Additionally you may execute

mvn eclipse:eclipse

to setup Eclipse IDE if, that is what you are using! At this time your portlet skeleton is ready and you may compile it and even create WAR, but it of course does nothig special.

Let's now add data model and services. Create file service-builder-portlet/src/main/webapp/WEB-INF/service.xml :

<?xml version="1.0"?> <!DOCTYPE service-builder PUBLIC "-//Liferay//DTD Service Builder 5.2.0//EN" "http://www.liferay.com/dtd/liferay-service-builder_5_2_0.dtd"> <service-builder package-path="com.commsen.liferay.examples.portlet.servicebuilder"> <namespace>SB</namespace> <entity name="Player" local-service="true" remote-service="true">  <column name="playerId" type="long" primary="true" />  <column name="name" type="String" /> <column name="active" type="boolean" /> <column name="score" type="int" /> <column name="birthday" type="Date" /> <column name="description" type="String" />  <order by="asc"> <order-column name="name" /> </order>  <finder name="ActivePlayers" return-type="Collection"> <finder-column name="active" /> </finder> </entity> </service-builder>

The portlet projects created by liferay-portlet-archetype contain maven profile with lifray-maven-plugin’s build-service goal attached to generate-sources phase. To run ServiceBuilder you need to activate the profile:

mvn -P build-service package

If you read carefully the messages you will realize that service and persistence classes were generated in service-builder-portlet/src/main/java-service-api/ folder. Also there should be a few implementation files in service-builder-portlet/src/main/java/.

Now we'll add custom methods. Open the following file service-builder-portlet/src/main/java/com/commsen/liferay/examples/portlet/servicebuilder/service/impl/PlayerLocalServiceImpl.java and paste this code:

public void addPlayer(String name, boolean active, int score, Date birthday, String desc) throws PortalException, SystemException { long playerId = CounterLocalServiceUtil.increment(); Player player = PlayerUtil.create(playerId); player.setName(name); player.setActive(active); player.setScore(score); player.setBirthday(birthday); player.setDescription(desc); PlayerUtil.update(player, false); } public List<Player> getAllPlayers() throws PortalException, SystemException { return PlayerUtil.findAll(); }

We added methods to the implementation class. The next time we compile the code we need to activate the build-service profile again in order for Service Builder to react on the change and regenerate the API and interfaces. If you want to try it now simply execute

mvn -P build-service compile

Now we can start using these services in our portlet. Open service-builder-portlet/src/main/java/com/commsen/liferay/examples/portlet/servicebuilder/JSPPortlet.java and add this method

@ProcessAction(name = Constants.ADD) public void addPlayer(ActionRequest actionRequest, ActionResponse actionResponse) throws PortletException, IOException { String name = ParamUtil.getString(actionRequest, "name"); boolean active = ParamUtil.getBoolean(actionRequest, "active"); int score = ParamUtil.getInteger(actionRequest, "score"); String description = ParamUtil.getString(actionRequest, "description"); int year = ParamUtil.getInteger(actionRequest, "birthday_year"); int month = ParamUtil.getInteger(actionRequest, "birthday_month"); int day = ParamUtil.getInteger(actionRequest, "birthday_day"); Calendar calendar = Calendar.getInstance(); calendar.set(Calendar.YEAR, year); calendar.set(Calendar.MONTH, month); calendar.set(Calendar.DAY_OF_MONTH, day); try { PlayerLocalServiceUtil.addPlayer(name, active, score, calendar.getTime(), description); } catch (Exception e) { throw new PortletException("Failed to add player", e); } }

This method handles adding players to database by calling the method we created earliar. To complete the portlet we only need the JSP page which displays the list and render HTML form to add users. The page source code is available here.

That's all! We can now create WAR file (mvn package) deploy it and add some players to our database! For more details have a look at portlet's source code available in examples/service-builder-portlet folder of liferay-maven-sdk.