Writing the My Greeting Portlet

Let’s make our portlet do something useful. First, we’ll give it two pages:

• view.jsp: displays the greeting and provides a link to the edit page.

• edit.jsp: shows a form with a text field, allowing the greeting to be changed, and including a link back to the view page.

The MVCPortlet class handles the rendering of our JSPs, so for this example, we won’t write a single Java class.

First, since we don’t want multiple greetings on the same page, let’s make the My Greeting portlet non-instanceable. Just edit liferay-portlet.xml, changing the value of the element instanceable from true to false. Here’s what it looks like:

<instanceable>false</instanceable>

Now we’ll create our JSP templates. Start by editing view.jsp, found in your portlet’s docroot directory. Replace 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="mvcPath" 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="mvcPath" 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="mvcPath" value="/view.jsp" />
</portlet:renderURL>

<p><a href="<%= viewGreetingURL %>">&larr; Back</a></p>

Deploy the portlet again in Developer Studio or 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.

Figure 3.5: The view page of My Greeting portlet

Figure 3.6: The edit page of My Greeting portlet

---

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. To fix this, 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 note concerning 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 mvcPath. This is used by MVCPortlet to determine which JSP to render for each request. Always use taglibs to generate URLs to your portlet, because the portlet doesn’t own the whole page, only a fragment of it. The URL must always go to the portal responsible for rendering, and this applies to your portlet and 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 render the whole page.

Second, notice that the form in edit.jsp has the prefix aui, signifying that it’s part of the Alloy UI tag library. Alloy greatly simplifies the code required to create attractive and accessible forms by providing tags that 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 you may have noticed is <portlet:defineObjects/>. The portlet specification defined this tag in order to be able to insert a set of implicit variables into the JSP that are useful for portlet developers, such as renderRequest, portletConfig, portletPreferences, etc.

A warning about our newly created portlet: For the purpose of making this example easy to follow, we cheated a little bit. The portlet specification doesn’t allow setting preferences from a JSP, because they are executed in what is known as the render state. There are good reasons for this restriction, and they’re explained in the next section.