Writing the My Greeting Portlet

Now that you are familiar with the structure of a portlet, it's time to actually make it do something useful. Our portlet will have two pages. view.jsp will display the greeting and provide a link to the edit page. Edit.jsp will show a form with a text field allowing the greeting to be changed, along with a link back to the view page. MVCPortlet class will handle the rendering of our JSPs, so for this example we won't have to write a single Java class.

First, we don't want multiple greetings on the same page, so we are going to make the My Greeting portlet non-instanceable. To do this, edit liferay-portlet.xml and change the value of the element instanceable from true to false so that it looks like this:

<instanceable>false</instanceable>

Next, we will create our JSP templates. Start by editing view.jsp and replacing its current contents with the following:

<%@ taglib uri="http://java.sun.com/portlet_2_0" prefix="portlet" %>

<%@ page import="javax.portlet.PortletPreferences" %>

<portlet:defineObjects />

<%

PortletPreferences prefs = renderRequest.getPreferences();

String greeting = (String)prefs.getValue(

    "greeting", "Hello! Welcome to our portal.");

%>

<p><%= greeting %></p>

<portlet:renderURL var="editGreetingURL">

    <portlet:param name="jspPage" value="/edit.jsp" />

</portlet:renderURL>

<p><a href="<%= editGreetingURL %>">Edit greeting</a></p>

Next, create edit.jsp in the same directory as view.jsp with the following content:

<%@ taglib uri="http://java.sun.com/portlet_2_0" prefix="portlet" %>

<%@ taglib uri="http://liferay.com/tld/aui" prefix="aui" %>

<%@ page import="javax.portlet.PortletPreferences" %>

<portlet:defineObjects />

<%

PortletPreferences prefs = renderRequest.getPreferences();

String greeting = renderRequest.getParameter("greeting");

if (greeting != null) {    

    prefs.setValue("greeting", greeting);

    prefs.store();

%>

    <p>Greeting saved successfully!</p>

<%

}

%>

<%

greeting = (String)prefs.getValue(

    "greeting", "Hello! Welcome to our portal.");

%>

<portlet:renderURL var="editGreetingURL">

    <portlet:param name="jspPage" value="/edit.jsp" />

</portlet:renderURL>

<aui:form action="<%= editGreetingURL %>" method="post">

    <aui:input label="greeting" name="greeting" type="text" value="<%= greeting %>" />

    <aui:button type="submit" />

</aui:form>

<portlet:renderURL var="viewGreetingURL">

    <portlet:param name="jspPage" value="/view.jsp" />

</portlet:renderURL>

<p><a href="<%= viewGreetingURL %>">← Back</a></p>

Deploy the portlet again by entering the command ant deploy in your my-greeting-portlet folder. Go back to your web browser and refresh the page; you should now be able to use the portlet to save and display a custom greeting.

Tip: If your portlet deployed successfully, but you don't see any changes in your browser after refreshing the page, Tomcat may have failed to rebuild your JSPs. Simply delete the work folder in liferay-portal-[version]/tomcat-[tomcat-version] and refresh the page again to force them to be rebuilt.

There are a few important details to notice in this implementation. First, the links between pages are created using the <portlet:renderURL> tag, which is defined by the http://java.sun.com/portlet_2_0 tag library. These URLs have only one parameter named jspPage, which is used by MVCPortlet to determine which JSP to render for each request. You must always use taglibs to generate URLs to your portlet. This restriction exists because the portlet does not own the whole page, only a fragment of it, so the URL must always go to the portal who is responsible for rendering, not only your portlet but also any others that the user might put in the page. The portal will be able to interpret the taglib and create a URL with enough information to be able to render the whole page.

Second, notice that the form in edit.jsp has the prefix aui, signifying that it is part of the Alloy UI tag library. Alloy greatly simplifies the code required to create nice looking and accessible forms, by providing tags that will render both the label and the field at once. You can also use regular HTML or any other taglibs to create forms based on your own preferences.

Another JSP tag that you may have noticed is <portlet:defineObjects/>. The portlet specification defined this tag in order to be able to insert into the JSP a set of implicit variables that are useful for portlet developers such as renderRequest, portletConfig, portletPreferences, etc.

One word of warning about the portlet we have just built. For the purpose of making this example as simple and easy to follow as possible, we have cheated a little bit. The portlet specification does not allow to set preferences from a JSP, because they are executed in what is known as the render state. There are good reasons for this restriction, that are explained in the next section.