Creating a Soy Portlet

To create a Soy portlet, you’ll need these key components:

  • A module that publishes a portlet component with the necessary properties
  • Controller code to handle the request and response
  • Soy templates to implement your view layer

Configuring the Web Module

First, familiarize yourself with a Soy portlet’s anatomy. You may recognize it, since a Soy portlet extends an MVC portlet:

  • my-soy-portlet
    • bnd.bnd
    • build.gradle
    • package.json
    • src/main/
      • java/path/to/portlet/
        • action/
          • *
      • resources/META-INF/resources/
        • content/
        • (MetalJS component)
        • (Soy template)

Now that you know the basic structure of a Soy portlet module, you can configure it. You can use the soy portlet Blade template to build your initial project if you wish. Otherwise, you can follow the instructions in this section to manually configure the module.

Specifying OSGi Metadata

Add the OSGi metadata to your module’s bnd.bnd file. A sample BND configuration is shown below:

Bundle-Name: Liferay Hello Soy Web
Bundle-Version: 1.0.3
Include-Resource: package.json

In addition to the standard metadata, notice the Require-Capability property. This specifies that this bundle requires modules that provide the capability soy with a type of metal to work. Also note the Include-Resource property. You must include your package.json file to load the Soy Portlet’s JavaScript files.

Specifying JavaScript Dependencies

Specify the JavaScript module dependencies in your package.json. At a minimum, you should have the following dependencies and configuration parameters:

	"dependencies": {
		"metal-component": "^2.4.5",
		"metal-soy": "^2.4.5"
	"devDependencies": {
		"liferay-module-config-generator": "^1.2.1",
		"metal-cli": "^4.0.1"
	"name": "my-portlet-name",
	"version": "1.0.0"

This provides everything you need to create a Metal component based on Soy. Note that the version in your package.json should match the Bundle-Version in your bnd.bnd file.

Next you can specify your module’s build dependencies.

Specifying Build Dependencies

Add the dependencies shown below to your build.gradle file:

dependencies {
	provided group: "com.liferay", name: "", version: "3.1.0"
	provided group: "com.liferay.portal", name: "com.liferay.portal.kernel", version: "2.0.0"
	provided group: "com.liferay.portal", name: "", version: "2.0.0"
	provided group: "javax.portlet", name: "portlet-api", version: "2.0"
	provided group: "javax.servlet", name: "javax.servlet-api", version: "3.0.1"
	provided group: "org.osgi", name: "org.osgi.service.component.annotations", version: "1.3.0"

Now that your module build is configured, you can learn how to create the Soy portlet component.

Creating a Soy Portlet Component

Create a Soy Portlet component that extends the SoyPortlet class. This
requires an implementation of the javax.portlet.portlet service to run. Declare this using an @Component annotation in the portlet class:

    immediate = true,
    service = Portlet.class
public class MySoyPortlet extends SoyPortlet {
    public void render(RenderRequest renderRequest, RenderResponse renderResponse) {
        //do things here

Liferay DXP’s SoyPortlet class extends Liferay DXP’s MVCPortlet class, which is an extension itself of javax.portlet.Portlet, so you’ve provided the right implementation.

The component requires some properties as well. A sample configuration is shown below:

        immediate = true,
        property = {
          "javax.portlet.display-name=Hello Soy Portlet",
        service = Portlet.class

Some of these properties may seem familiar to you, as they are the same ones used to develop an MVC portlet. You can find a list of all the Liferay-specific attributes that are available for use as properties in your portlet components in the liferay-portlet-app_7_0_0.dtd.

The javax.portlet... properties are elements of the portlet.xml descriptor

Liferay’s DTD files can be found here

Now that you’ve set your Soy portlet component’s foundation, you can write the controller code.

Writing Controller Code

Soy portlets extend MVC portlets, so they use the same Model-View-Controller framework to operate. Your controller receives requests from the front-end, and it receives data from the back-end. It’s responsible for sending that data to the right front-end view so it can be displayed to the user, and it’s responsible for taking data the user entered in the front-end and passing it to the right back-end service. For this reason, it needs a way to process requests from the front-end and respond to them appropriately, and it needs a way to determine the appropriate front-end view to pass data back to the user.

Render Logic

The render logic is where all the magic happens. After all, what’s the use of a portlet if you can’t see it? Note the init-param properties you set in your Component class:


This directs the default rendering to View ( The template-path property tells the framework the location of your Soy templates. The / above means that the Soy files are located in your project’s root resources folder. That’s why it’s important to follow Liferay DXP’s standard folder structure, outlined above. Here’s the path of a hypothetical web module’s resource folder:


In this case, the file is found at:


That’s the default view of the application. When the init method is called, the initialization parameters you specify are read and used to direct rendering to the default template. Throughout this framework, you can render a different view (Soy template) by setting the mvcRenderCommandName parameter of the javax.portlet.PortletURL to the Soy template. The example below uses a portlet URL called navigationURL to render the view View:

navigationURL.setParameter("mvcRenderCommandName", "View");

Each view, excluding the default template view, must have an implementation of the MVCRenderCommand class. The *MVCRenderCommand implementation must declare itself as a component with the MVCRenderCommand service, and it must specify the portlet’s name and MVC command name using the and properties respectively. Below is an example MVCRenderCommand implementation for a Navigation Soy template:

        immediate = true,
        property = {
        service = MVCRenderCommand.class
public class HelloSoyNavigationExampleMVCRenderCommand
        implements MVCRenderCommand {

        public String render(
                RenderRequest renderRequest, RenderResponse renderResponse) {

                Template template = (Template)renderRequest.getAttribute(

                PortletURL navigationURL = renderResponse.createRenderURL();

                navigationURL.setParameter("mvcRenderCommandName", "View");

                template.put("navigationURL", navigationURL.toString());

                return "Navigation";


The render logic provides the view layer with information to display the data properly to the user. In this case the MVC command name is set to Navigation (the Soy template with namespace Navigation). The MVC render command name for the PortletURL navigationURL is set to View (the Soy template with namespace Navigation), using the mvcRenderCommandName attribute. The navigationURL parameter is passed to the Navigation Soy template as the variable navigationURL, using the template.put() method. Finally, the *MVCRenderCommand class returns the MVC render command name as a String.

Note that Soy portlet parameters are scoped to the portlet class they’re written in. For instance, you can have a navigationURL parameter in two different classes, each with a different value. Below is an example HelloSoyPortlet class that also defines a navigationURL parameter:

public class HelloSoyPortlet extends SoyPortlet {

	public void render(
			RenderRequest renderRequest, RenderResponse renderResponse)
		throws IOException, PortletException {

		PortletURL navigationURL = renderResponse.createRenderURL();

		navigationURL.setParameter("mvcRenderCommandName", "Navigation");

		template.put("navigationURL", navigationURL.toString());

		template.put("releaseInfo", ReleaseInfo.getReleaseInfo());

		super.render(renderRequest, renderResponse);


The navigationURL points to the Navigation Soy template this time. The navigationURL and releaseInfo parameters are passed to the View Soy template. Since this logic should be executed before the default render method, the method concludes by calling super.render.

Now that you understand the render logic, you can learn how the view layer works.

Configuring the View Layer

Your portlet also requires a view layer, and for that you’ll use Soy templates, which is the whole point of developing a Soy portlet, isn’t it? This section briefly covers how to get your view layer working, from including other Soy templates, to creating a MetalJS component for rendering your views.

Soy templates are defined in a file with the extension .soy. The filename is arbitrary. The Soy template’s name is specified at the top of the template using the namespace declaration. For example, this template has the namespace View:

{namespace View}

It can be accessed in another Soy template by calling the render method on the namespace as shown below:

{call View.render data="all"}{/call}

Below is an example View Soy template that includes Header and Footer Soy templates:

{namespace View}

 * Prints the portlet main view.
{template .render}
  <div id="{$id}">
    {call Header.render data="all"}{/call}

    <p>{msg desc=""}here-is-a-message{/msg}</p>

    {call Footer.render data="all"}{/call}

Each view has a corresponding *es.js file (usually with the same name) that imports the Soy templates the view requires and registers the view as a MetalJS component. This file is also used for any additional JavaScript logic your view may have. For example, here is a component for a template:

import Component from 'metal-component/src/Component';
import Footer from './';
import Header from './';
import Soy from 'metal-soy/src/Soy';
import templates from './';

 * View Component
class View extends Component {}

// Register component
Soy.register(View, templates);

export default View;

Now that you understand how to configure a Soy template view, you can learn how to use portlet parameters in your Soy templates next.

Using Portlet Template Parameters in the Soy Template

As mentioned above, the template.put() method exposes portlet parameters to the Soy templates. Once a parameter is exposed, you can access it in the Soy template by defining it at the top with the {@param name: type} declaration. For instance, the hello-soy-web portlet’s View Soy template defines the navigationURL parameter with the code below:

{@param navigationURL: string}

It is then used to navigate between portlet views:

<a href="{$navigationURL}">{msg desc=""}

Some Java theme object variables are available as well. For example, to access the ThemeDisplay object in a Soy template, use the following syntax:


You can also access the Locale object by using {$locale}. Here is the full template for the portlet, which demonstrates the features covered in this section:

{namespace View}

 * Prints the portlet main view.
{template .render}
	{@param id: string}
	{@param layouts: list<[
		friendlyURL: string,
		nameCurrentValue: string
	{@param navigationURL: string}

	<div id="{$id}">
		{call Header.render data="all"}{/call}

		<p>{msg desc=""}here-you-will-find-how-easy-it-is-to-do-things-like{/msg}</p>

		<h3>{msg desc=""}listing-pages{/msg}</h3>

		<div class="list-group">
			<div class="list-group-heading">{msg desc=""}navigate-to{/msg}</div>

			{foreach $layout in $layouts}
				<a class="list-group-item" href="{$layout.friendlyURL}">{$layout.nameCurrentValue}</a>

		<h3>{msg desc=""}navigating-between-views{/msg}</h3>

		<a href="{$navigationURL}">{msg desc=""}click-here-to-navigate-to-another-view{/msg}</a>

		{call Footer.render data="all"}{/call}

Now you know how to create a Soy Portlet!

Liferay MVC Portlet

JSF Portlets with Liferay Faces

« Liferay Soy PortletThe State Object »
Was this article helpful?
0 out of 0 found this helpful