Configuring Soy Portlet Template Parameters on the Client Side

Portlet template parameters are set in the Soy Portlet’s server-side code. MetalJS’s state class provides a STATE object that exposes these parameters as properties so you can access them on the client side. This tutorial covers how to configure your view component’s STATE object and its properties on the client side so you can update the UI.

This tutorial references the example below.

An Example Header State Portlet

This tutorial references the example portlet covered in this section. It includes one view with a header that reads Hello Soy by default.

Figure 1: The example Soy portlet has a configurable header.

Figure 1: The example Soy portlet has a configurable header.

The text in the header following Hello is provided by the header state property defined in its *mvcRenderCommand class. Deploy the provided file to follow along with this tutorial. The example portlet’s *MVCRenderCommand class and Soy template appear below for reference:

*MVCRenderCommand class:

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

	public String render(
		RenderRequest renderRequest, RenderResponse renderResponse) {

		Template template = (Template)renderRequest.getAttribute(

		String header = "Soy";

		template.put("header", header);

		return "View";


{namespace View}

 * Prints the portlet main view.
{template .render}
	{@param id: string}
	{@param header: string}

	<div id="{$id}">

		<h1>Hello {$header}</h1>

		<p>You can update the header with the portlet's header State properties.</p>

Configuring the State properties

Soy Portlets are registered automatically using the Liferay.component API, so you can use this API to retrieve your portlet and update its state properties. You can test this in your browser’s developer console.

Follow these steps:

  1. Open the console in your web browser.

  2. Retrieve your portlet’s component by passing the Soy portlet’s ID in the method Liferay.component(). For example, you can access the example portlet’s component with the code below:


    This returns the Soy portlet’s component Object containing the state properties along with properties inherited from the prototype. Alternatively, you can access the STATE object directly by calling the getState() method:

  3. Now that you retrieved your Soy portlet’s component, you can access its state properties the same way you would access any object’s properties: the dot notation or the bracket notation. For example, you can use the code below to retrieve the portlet’s header state property:



  4. Update the state property’s value:

    Liferay.component("portletID").stateProperty = "new value";


    Liferay.component("portletID")["stateProperty"] = "new value";

    or you can pass a configuration object with the setState() method:

    Liferay.component("portletID").setState({stateProperty: new value});

    For example, you can change the example portlet’s header to read Hello Hamburger instead, if you don’t like soy:

    Liferay.component('_MyStateSoyPortlet_').setState({header: 'Hamburger'});

Figure 2: You can change the example portlets header state property on the client side.

Figure 2: You can change the example portlet's header state property on the client side.

Now you know how to configure Soy portlet state properties on the client side!

Understanding the State Object’s Architecture

Configuring Portlet Template Parameter State Properties

« Configuring Portlet Template Parameter State PropertiesSpring MVC »
Was this article helpful?
0 out of 0 found this helpful