Creating URL Routes

If you have the Guestbook Portlet deployed and added to a page, click on the Add Guestbook button. Here’s what the generated URL looks like:

http://localhost:8080/web/guest/home?p_p_id=guestbook_WAR_guestbookportlet&p_p_lifecycle=0&p_p_state=normal&p_p_mode=view&p_p_col_id=column-2&p_p_col_pos=1&p_p_col_count=3&_guestbook_WAR_guestbookportlet_mvcPath=%2Fhtml%2Fguestbook%2Fedit_guestbook.jsp

When you’re done with this section, clicking Add Guestbook will generate the following URL:

http://localhost:8080/web/guest/home/-/guestbook/add_guestbook

Isn’t that a lot more user friendly? You can greatly improve the readability of any portlet URL, and you can do it in two easy steps:

1. Create an XML file defining Friendly URL routes.
2. Add three lines to liferay-portlet.xml.

You’ll learn how to do that next.

Defining Friendly URL Routes

Your Friendly URL is ready to emerge from the beastly URL above. While you’re here, you can clean up the URLs for some of the other links as well. Follow these steps:

1. Create com/liferay/docs/guestbook/portlet/guestbook-friendly-url-routes.xml. It’s standard practice to create this file in the same package as the portlet class.

2. Add this code to the file:

    <?xml version="1.0"?>
    <!DOCTYPE routes PUBLIC "-//Liferay//DTD Friendly URL Routes 6.2.0//EN"
    "http://www.liferay.com/dtd/liferay-friendly-url-routes_6_2_0.dtd">
   
    <routes>
        <route>
            <pattern>/add_guestbook</pattern>
            <implicit-parameter name="p_p_lifecycle">0</implicit-parameter>
            <implicit-parameter name="mvcPath">/html/guestbook/edit_guestbook.jsp</implicit-parameter>
        </route>
        <route>
            <pattern>/{guestbookId}/add_entry</pattern>
            <implicit-parameter name="mvcPath">/html/guestbook/edit_entry.jsp</implicit-parameter>
        </route>
        <route>
            <pattern>/{entryId}/view_entry</pattern>
            <implicit-parameter name="p_p_lifecycle">0</implicit-parameter>
            <implicit-parameter name="mvcPath">/html/guestbook/view_entry.jsp</implicit-parameter>
        </route>
        <route>
            <pattern>/{guestbookId}/view</pattern>
            <implicit-parameter name="p_p_lifecycle">0</implicit-parameter>
            <implicit-parameter name="mvcPath">/html/guestbook/view.jsp</implicit-parameter>
        </route>
    </routes>
   

There are two tags from the XML to focus on:

• The pattern tag inside each <route>is used to define placeholder values for the various parameters that normally appear in the generated URL: in short, it’s the disguise you’re putting on the beastly URL to make it more friendly. When users add a Guestbook, they shouldn’t see every parameter generated by the portal in the URL. Instead, they should see only add_guestbook. Similarly, when they add a Guestbook Entry, you want them to see add_entry. You’ve also included the {guestbookId}. Using this format, you can populate URLs with data retrieved from the database. In this case, guestbookId is available in the Friendly URL because it’s already in the addEntryURL in docroot/html/view.jsp:

    <portlet:param name="guestbookId"
            value="<%=String.valueOf(guestbookId)%>" />
  

• The implicit-parameter tag defines parameters that don’t need to be generated because they’ll always be the same for this URL. All URLs for adding entities and viewing Guestbooks or Guestbook Entries are renderURLs, so the portal doesn’t need to generate the p_p_lifecycle parameter. It can automatically be assumed to be 0. If you remove this parameter from the route, the resulting Friendly URL doesn’t change: you specified in the pattern tag what should be displayed in place of the generated URL. But it’s nice to specify it here so the portal doesn’t need to bother generating it on the fly.

Liferay isn’t yet aware of your intention to use friendly URLs. The next section shows you how to inform the portal.

Declaring Friendly URL Mapping to Liferay

Modify the Liferay portlet descriptor, docroot/WEB-INF/liferay-portlet.xml, by adding these lines after the <indexer-class...> declaration:

    <friendly-url-mapper-class>com.liferay.portal.kernel.portlet.DefaultFriendlyURLMapper</friendly-url-mapper-class>
	<friendly-url-mapping>guestbook</friendly-url-mapping>
	<friendly-url-routes>com/liferay/docs/guestbook/portlet/guestbook-friendly-url-routes.xml</friendly-url-routes>

So what are these tags used for? The friendly-url-routes tag lets you declare an XML file with URL routes that relate to the Liferay URLs. In almost all cases, you’ll use the DefaultFriendlyURLMapper class as the friendly-url-mapper-class. It contains the logic to map your Friendly URL routes to Liferay URLs with parameters. The second tag, friendly-url-mapping, is just a name used to identify the routes. It appears in the URL right before the routes you declare.

Here’s what your friendly portlet URLs look like now:

• Add Guestbook: http://localhost:8080/web/guest/home/-/guestbook/add_guestbook
• Add Entry: http://localhost:8080/web/guest/home/-/guestbook/10616/add_entry
• View Entry: http://localhost:8080/web/guest/home/-/guestbook/10622/view_entry
• View Guestbook: http://localhost:8080/web/guest/home/-/guestbook/10619/view

Now you know how to quickly implement Friendly URLs in a custom portlet. You could leave it at that, but using the guestbookId and entryId in the URL really isn’t as friendly as it could be. The next step is to replace those IDs with the title of the Guestbook or Guestbook Entry.

« Making URLs FriendlyRemoving the Primary Key from Portlet URLs »