Portlet

Exclusive offer: get 50% off this eBook here
Liferay 6.2 User Interface Development

Liferay 6.2 User Interface Development — Save 50%

A comprehensive guide to user interface development with Liferay Portal with this book and ebook

$29.99    $15.00
by Jonas X. Yuan Xinsheng Chen | November 2013 | e-Commerce Open Source

This article by Xinsheng Chen and Dr. Jonas Yuan, the authors of the book Liferay 6.2 User Interface Development, covers the main aspects of portlets and their development. It introduces the ways to develop simple JSR 286 portlets, Spring MVC portlets, and Vaadin portlets. It describes how to implement the view, edit, and help modes of a portlet.

(For more resources related to this topic, see here.)

The Spring MVC portlet

The Spring MVC portlet follows the Model-View-Controller design pattern. The model refers to objects that imply business rules. Usually, each object has a corresponding table in the database. The view refers to JSP files that will be rendered into the HTML markup. The controller is a Java class that distributes user requests to different JSP files. A Spring MVC portlet usually has the following folder structure:

In the previous screenshot, there are two Spring MVC portlets: leek-portlet and lettuce-portlet. You can see that the controller classes are clearly named as LeekController.java and LettuceController.java. The JSP files for the leek portlet are view/leek/leek.jsp, view/leek/edit.jsp, and view/leek/help.jsp.

The definition of the leek portlet in the portlet.xml file is as follows:

<portlet> <portlet-name>leek</portlet-name> <display-name>Leek</display-name> <portlet-class>org.springframework.web.portlet.DispatcherPortlet
</portlet-class> <init-param> <name>contextConfigLocation</name> <value>/WEB-INF/context/leek-portlet.xml</value> </init-param> <supports> <mime-type>text/html</mime-type> <portlet-mode>view</portlet-mode> <portlet-mode>edit</portlet-mode> <portlet-mode>help</portlet-mode> </supports> ... <supported-publishing-event> <qname xmlns:x="http://uibook.com/events">x:ipc.share</qname> </supported-publishing-event> </portlet>

You can see from the previous code that the portlet class for a Spring MVC portlet is the org.springframework.web.portlet.DispatcherPortlet.java class. When a Spring MVC portlet is called, this class runs. It also calls the WEB-INF/context/leek/portlet.xml file and initializes the singletons defined in that file when the leek portlet is deployed. The leek portlet supports the view, edit, and help mode. It can also fire a portlet event with ipc.share as its qualified name.

Yo can use the method to import the leek and lettuce portlets (whose source code can be downloaded from the Packt site) to your Liferay IDE. Then, carry out the following steps:

  1. Deploy the leek-portlet package and wait until the leek portlet and lettuce portlet are registered by the Liferay Portal.
  2. Log in as the portal administrator and add the two Spring MVC portlets onto a portal page.

Your portal page should look similar to the following screenshot:

The default view of the leek portlet comes from the view/leek/leek.jsp file whose logic is defined through the following method in the com.uibook.leek.portlet.LeekController.java class:

@RequestMapping public String render(Model model, SessionStatus status, RenderRequest req) { return "leek"; }

This method calls the view/leek/leek.jsp file.

In the default view of the leek portlet, when you click on the radio button for Snow water from last winter and then on the Get Water button, the following form will be submitted:

<form action="http://localhost:8080/web/uibook/home?p_auth=wwMoBV4C&p_p_id=
leek_WAR_leekportlet&p_p_lifecycle=1&p_p_state=normal&p_p_mode=
view&p_p_col_id=column-2&p_p_col_pos=1&p_p_col_count
=2&_leek_WAR_leekportlet_action=sprayWater"
id=
"_leek_WAR_leekportlet_leekFm" method="post" name=
"_leek_WAR_leekportlet_leekFm">

This form will fire an action URL because p_p_lifecycle is equal to 1. As the action name is sprayWater in the URL, the DispatcherPortlet.java class (as specified in the portlet.xml file) calls the following method:

@ActionMapping(params="action=sprayWater") public void sprayWater(ActionRequest request, ActionResponse response,
SessionStatus sessionStatus) { String waterType = request.getParameter("waterSupply"); if(waterType != null){ request.setAttribute("theWaterIs", waterType); sessionStatus.setComplete(); } }

This method simply gets the value for the waterSupply parameter as specified in the following code, which comes from the view/leek/leek.jsp file:

<input type="radio" name="<portlet:namespace />waterSupply"
value="snow water from last winter">Snow water from last winter

The value is snow water from last winter, which is set as a request attribute. As the previous sprayWater(…) method does not specify a request parameter for a JSP file to be rendered, the logic goes to the default view of the leek portlet. So, the view/leek/leek.jsp file will be rendered. Here, as you can see, the two-phase logic is retained in the Spring MVC portlet, as has been explained in the Understanding a simple JSR-286 portlet section of this article.

Now the theWaterIs request attribute has a value, which is snow water from last winter. So, the following code in the leek.jsp file runs and displays the Please enjoy some snow water from last winter. message, as shown in the previous screenshot:

<c:if test="${not empty theWaterIs}"> <p>Please enjoy some ${theWaterIs}.</p> </c:if>

In the previous screenshot, the Passing you a gift... link is rendered with the following code in the leek.jsp file:

<a href="<portlet:actionURL name="shareGarden"></portlet:actionURL>"
>Passing you a gift ...</a>

When this link is clicked, an action URL named shareGarden is fired. So, the DispatcherPortlet.java class will call the following method:

@ActionMapping("shareGarden") public void pitchBallAction(SessionStatus status, ActionResponse response) { String elementType = null; Random random = new Random(System.currentTimeMillis()); int elementIndex = random.nextInt(3) + 1; switch(elementIndex) { case 1 : elementType = "sunshine"; break; ... } QName qname = new QName("http://uibook.com/events","ipc.share"); response.setEvent(qname, elementType); status.setComplete(); }

This method gets a value for elementType (the type of water in our case) and sends out this elementType value to another portlet based on the ipc.share qualified name. The lettuce portlet has been defined in the portlet.xml file as follows to receive such a portlet event:

<portlet> <portlet-name>lettuce</portlet-name> ... <supported-processing-event> <qname xmlns:x="http://uibook.com/events">x:ipc.share</qname> </supported-processing-event> </portlet>

When the ipc.share portlet event is sent, the portal page refreshes. Because the lettuce portlet is on the same page as the leek portlet, the portlet event is received by the following method in the com.uibook.lettuce.portlet.LettuceController.java class:

@EventMapping(value ="{http://uibook.com/events}ipc.share") public void receiveEvent(EventRequest request, EventResponse response, ModelMap map) { Event event = request.getEvent(); String element = (String)event.getValue(); map.put("element", element); response.setRenderParameter("element", element); }

This receiveEvent(…) method receives the ipc.share portlet event, gets the value in the event (which can be sunshine, rain drops, wind, or space), and puts it in the ModelMap object with element as the key.

Now, the following code in the view/lettuce/lettuce.jsp file runs:

<c:choose> <c:when test="${empty element}"> <p> Please share the garden with me! </p> </c:when> <c:otherwise> <p>Thank you for the ${element}!</p> </c:otherwise> </c:choose>

As the element parameter now has a value, a message similar to Thank you for the wind will show in the lettuce portlet. The wind is a gift from the leek to the lettuce portlet.

In the default view of the leek portlet, there is a Some shade, please! button. This button is implemented with the following code in the view/leek/leek.jsp file:

<button type="button" onclick="<portlet:namespace />loadContentThruAjax();"
>Some shade, please!</button>

When this button is clicked, a _leek_WAR_leekportlet_loadContentThruAjax() JavaScript function will run:

function <portlet:namespace />loadContentThruAjax() { ... document.getElementById("<portlet:namespace />content").innerHTML=
xmlhttp.responseText; ... xmlhttp.open('GET','<portlet:resourceURL escapeXml="false" id=
"provideShade"/>',true); xmlhttp.send(); }

This loadContentThruAjax() function is an Ajax call. It fires a resource URL whose ID is provideShade. It maps the following method in the com.uibook.leek.portlet.LeekController.java class:

@ResourceMapping(value = "provideShade") public void provideShade(ResourceRequest resourceRequest,
ResourceResponse resourceResponse) throws PortletException, IOException { resourceResponse.setContentType("text/html"); PrintWriter out = resourceResponse.getWriter(); StringBuilder strB = new StringBuilder(); strB.append("The banana tree will sway its leaf to cover you from the sun."); out.println(strB.toString()); out.close(); }

This method simply sends the The banana tree will sway its leaf to cover you from the sun message back to the browser. The previous loadContentThruAjax() method receives this message, inserts it in the <div id="_leek_WAR_leekportlet_content"></div> element, and shows it.

About the Vaadin portlet

Vaadin is an open source web application development framework. It consists of a server-side API and a client-side API. Each API has a set of UI components and widgets. Vaadin has themes for controlling the appearance of a web page.

Using Vaadin, you can write a web application purely in Java. A Vaadin application is like a servlet. However, unlike the servlet code, Vaadin has a large set of UI components, controls, and widgets. For example, in correspondence to the <table> HTML element, the Vaadin API has a com.vaadin.ui.Table.java class. The following is a comparison between servlet table implementation and Vaadin table implementation:

Servlet Code

Vaadin Code

PrintWriter out = response.getWriter();

out.println("<table>\n" +

   "<tr>\n" +

   "<td>row 2, cell 1</td>\n" +

   "<td>row 2, cell 2</td>" +

   "</tr>\n" +

   "</table>");

sample = new Table();

sample.setSizeFull();

sample.setSelectable(true);

...

sample.setColumnHeaders(new String[] { "Country", "Code" });

 

Basically, if there is a label element in HTML, there is a corresponding Label.java class in Vaadin. In the sample Vaadin code, you will find the use of the com.vaadin.ui.Button.java and com.vaadin.ui.TextField.java classes.

Vaadin supports portlet development based on JSR-286.

Vaadin support in Liferay Portal

Starting with Version 6.0, the Liferay Portal was bundled with the Vaadin Java API, themes, and a widget set described as follows:

  • ${APP_SERVER_PORTAL_DIR}/html/VAADIN/themes/
  • ${APP_SERVER_PORTAL_DIR}/html/VAADIN/widgetsets/
  • ${APP_SERVER_PORTAL_DIR}/WEB-INF/lib/vaadin.jar

A Vaadin control panel for the Liferay Portal is also available for download. It can be used to rebuild the widget set when you install new add-ons in the Liferay Portal.

In the ${LPORTAL_SRC_DIR}/portal-impl/src/portal.properties file, we have the following Vaadin-related setting:

vaadin.resources.path=/html vaadin.theme=liferay vaadin.widgetset=com.vaadin.portal.gwt.PortalDefaultWidgetSet

In this section, we will discuss two Vaadin portlets. These two Vaadin portlets are run and tested in Liferay Portal 6.1.20 because, at the time of writing, the support for Vaadin is not available in the new Liferay Portal 6.2. It is expected that when the Generally Available (GA) version of Liferay Portal 6.2 is available, the support for Vaadin portlets in the new Liferay Portal 6.2 will be ready.

Vaadin portlet for CRUD operations

CRUD stands for create, read, update, and delete. We will use a peanut portlet to illustrate the organization of a Vaadin portlet. In this portlet, a user can create, read, update, and delete data. This portlet is adapted from a SimpleAddressBook portlet from a Vaadin demo. Its structure is as shown in the following screenshot:

You can see that it does not have JSP files. The view, model, and controller are all incorporated in the PeanutApplication.java class. Its portlet.xml file has the following content:

<portlet-class>com.vaadin.terminal.gwt.server.ApplicationPortlet2
</portlet-class> <init-param> <name>application</name> <value>peanut.PeanutApplication</value> </init-param>

This means that when the Liferay Portal calls the peanut portlet, the com.vaadin.terminal.gwt.server.ApplicationPortlet2.java class will run. This ApplicationPortlet2.java class will in turn call the peanut.PeanutApplication.java class, which will retrieve data from the database and generate the HTML markup. The default UI of the peanut portlet is as follows:

This default UI is implemented with the following code:

HorizontalSplitPanel splitPanel = new HorizontalSplitPanel(); setMainWindow(new Window("Address Book", splitPanel)); VerticalLayout left = new VerticalLayout(); left.setSizeFull(); left.addComponent(contactList); contactList.setSizeFull(); left.setExpandRatio(contactList, 1); splitPanel.addComponent(left); splitPanel.addComponent(contactEditor); splitPanel.setHeight("450"); contactEditor.setCaption("Contact details editor"); contactEditor.setSizeFull(); contactEditor.getLayout().setMargin(true); contactEditor.setImmediate(true); bottomLeftCorner.setWidth("100%"); left.addComponent(bottomLeftCorner);

The previous code comes from the initLayout() method of the PeanutApplication.java class. This method is run when the portal page is first loaded. The new Window("Address Book", splitPanel) statement instantiates a window area, which is the whole portlet UI. This window is set as the main window of the portlet; every portlet has a main window. The splitPanel attribute splits the main window into two equal parts vertically; it is like the 2 Columns (50/50) page layout of Liferay. The splitPanel.addComponent(left) statement adds the contact information table to the left pane of the main window, while the splitPanel.addComponent(contactEditor) statement adds the contact details of the editor to the right pane of the main window.

The left variable is a com.vaadin.ui.VerticalLayout.java object. In the left.addComponent(bottomLeftCorner) statement, the left object adds a bottomLeftCorner object to itself. The bottomLeftCorner object is a com.vaadin.ui.HorizontalLayout.java object. It takes the space across the left vertical layout under the contact information table. This bottomLeftCorner horizontal layout will house the contact-add button and the contact-remove button.

The following screenshot gives you an idea of how the screen will look:

When the + icon is clicked, a button click event will be fired which runs the following code:

Object id = ((IndexedContainer) contactList.getContainerDataSource()).addItemAt(0); contactList.getItem(id).getItemProperty("First Name").setValue("John"); contactList.getItem(id).getItemProperty("Last Name").setValue("Doe");

This code adds an entry in the contactList object (contact information table) initializing the contact's first name to John and the last name to Doe. At the same time, the ValueChangeListener property of the contactList object is triggered and runs the following code:

contactList.addListener(new Property.ValueChangeListener() { public void valueChange(ValueChangeEvent event) { Object id = contactList.getValue(); contactEditor.setItemDataSource(id == null ? null : contactList .getItem(id)); contactRemovalButton.setVisible(id != null); } });

This code populates the contactEditor variable, a com.vaadin.ui.Form.Form.java object, with John Doe's contact information and displays the Contact details editor section in the right pane of the main window. After that, an end user can enter John Doe's other contact details. The end user can also update John Doe's first and last names.

If you have noticed, the last statement of the previous code snippet mentions contactRemovalButton. At this time, the John Doe entry in the contact information table is highlighted. If the end user clicks on the contact removal button, this information will be removed from both the contact information table and the contact details editor. Actually, the end user can highlight any entry in the contact information table and edit or delete it.

You may have seen that during the whole process of creating, reading, updating, and deleting the contact, the portal page URL did not change and the portal page did not refresh. All the operations were performed through Ajax calls to the application server. This means that only a few database accesses happened during the whole process. This improves the site performance and reduces load on the application server. It also implies that if you develop Vaadin portlets in the Liferay Portal, you do not have to know the friendly URL configuration skill on a Liferay Portal project.

In the peanut portlet, a developer cannot retrieve the logged-in user in the code, which is a weak point. In the following section, a potato portlet is implemented in such a way that a developer can retrieve the Liferay Portal information, including the logged-in user information.

Summary

In this article, we learned about portlets and their development. We learned ways todevelop simple JSR 286 portlets, SpringMVC portlets, and Vaadin portlets. We also learned to implement the view, edit, and help modes of a portlet.

Resources for Article:


Further resources on this subject:


Liferay 6.2 User Interface Development A comprehensive guide to user interface development with Liferay Portal with this book and ebook
Published: November 2013
eBook Price: $29.99
Book Price: $49.99
See more
Select your format and quantity:

About the Author :


Jonas X. Yuan

Jonas X. Yuan is a Chief Architect of ForgeLife LLC and an expert on Liferay Portal, e-commerce, and Content Management Systems (CMS). As an open source community contributor, he has published five Liferay books from 2008 to 2012. He is also an expert on Liferay integration with Ad Server OpenX, different search engines, enterprise content including videos, audio, images, documents, and web contents, and other technologies, such as BPM Intalio and Business Intelligence Pentaho, LDAP, and SSO. He holds a Ph.D. in Computer Science from the University of Zurich, where he focused on Integrity Control in federated database systems.

He earned his M.S. and B.S. degrees from China, where he conducted research on expert systems for predicting landslides. Previously, he worked as a Project Manager and a Technical Architect in Web GIS (Geographic Information System).
He is experienced in Systems Development Lifecycle (SDLC) and has deep, hands-on skills in J2EE technologies. He developed a BPEL (Business Process Execution Language) engine called BPELPower from scratch at the NASA data center. As the chief architect, Dr. Yuan successfully led and launched several large-scale Liferay/Alfresco e-commerce projects for millions of users each month.

He has worked on the following books: Liferay Portal Enterprise Intranets, 2008; Liferay Portal 5.2 Systems Development, 2009; Liferay Portal 6 Enterprise Intranets, 2010; Liferay User Interface Development, 2010; Liferay Portal Systems Development, 2012.

Xinsheng Chen

Xinsheng Chen is a web application architect. He holds an MS degree in Computer Science from California State University, San Bernardino. His focus was on online banking applications. He also has a Bachelor's degree from Wuhan University, China. Mr. Chen was previously a QA engineer working at VMware, Inc. He later led a team in developing four educational computer games for a Florida school district. Mr. Chen has rich experience in J2EE technologies. He also has extensive experience in Content Management Systems (CMS), including Alfresco. He has worked on 23 Liferay Portal projects. He is also the co-author of Liferay Beginner's Guide and Liferay User Interface Development.

Books From Packt


Liferay Beginner’s Guide
Liferay Beginner’s Guide

Liferay Portal 6 Enterprise Intranets
Liferay Portal 6 Enterprise Intranets

Liferay Portal Enterprise Intranets
Liferay Portal Enterprise Intranets

Liferay Portal Systems Development
Liferay Portal Systems Development

Liferay User Interface Development
Liferay User Interface Development

Liferay Portal 5.2 Systems Development
Liferay Portal 5.2 Systems Development

Instant Liferay Portal 6 Starter [Instant]
Instant Liferay Portal 6 Starter [Instant]

 Liferay Portal 6.x Enterprise Intranets (Update)
Liferay Portal 6.x Enterprise Intranets (Update)


No votes yet

Post new comment

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
Y
g
L
L
P
q
Enter the code without spaces and pay attention to upper/lower case.
Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software