Configuration Form Renderer

When you create a configuration interface, a configuration UI is automatically generated. But in some cases you want customize the look and feel of the UI. For example, you want to modify the UI to match the design aesthetics of your company. Here’s how to do it with a ConfigurationFormRenderer implementation.

See the Example Project

Start a new Liferay DXP instance by running

docker run -it -m 8g -p 8080:8080 liferay/dxp:2024.q2.11

Sign in to Liferay at http://localhost:8080 using the email address [e-mail] and the password test. When prompted, change the password to learn.

Then, follow these steps:

1. Download and unzip Configuration Form Renderer.

   curl https://resources.learn.liferay.com/dxp/latest/en/building-applications/core-frameworks/configuration-framework/liferay-b7r2.zip -O
   

   unzip liferay-b7r2.zip
   

2. From the module root, build and deploy.

   ./gradlew deploy -Ddeploy.docker.container.id=$(docker ps -lq)
   

   note

   This command is the same as copying the deployed jars to /opt/liferay/osgi/modules on the Docker container.

3. Confirm the deployment in the Liferay Docker container console.

   STARTED com.acme.b7r2.web_1.0.0 [1034]
   

4. Verify that the example module is working. Open your browser to https://localhost:8080.

5. Navigate to Control Panel → Configuration → System Settings → Third Party. Click B7R2 Configuration.

   

   Note that this view is delivered by a custom JSP file.

Create the Configuration Interface

Define the configurable attributes in the configuration interface. The sample project has one configurable attribute: b7r2Color.

public interface B7R2WebConfiguration {

	@Meta.AD(deflt = "blue", name = "b7r2-color", required = false)
	public String b7r2Color();

}

Note that when using ConfigurationFormRenderer, the generateUI annotation is not necessary to hide the generated UI.

note

A ConfigurationBeanDeclaration is required for Liferay versions before DXP 7.4 U51 or Portal 7.4 GA51. See ConfigurationBeanDeclaration with Previous Versions of Liferay.

Implement the Configuration Form Renderer

1. Create an implementation of ConfigurationFormRenderer. In the @Component annotation, declare the service as a ConfigurationScreen.class.

   @Component(service = ConfigurationScreen.class)
   

2. Override the getPid() method. Make sure to return the full configuration ID as specified in the configuration class’s @Meta.OCD annotation.

@Override
public String getPid() {
	return "com.acme.b7r2.web.internal.configuration.B7R2WebConfiguration";
}

1. Override the getRequestParameters() method. In the method, read the parameters sent by the custom UI and put them in a map where the keys match the fields found in the configuration interface.

@Override
public Map<String, Object> getRequestParameters(
	HttpServletRequest httpServletRequest) {

	String b7r2Color = ParamUtil.getString(httpServletRequest, "b7r2Color");

	return new HashMap<String, Object>() {
		{
			put("b7r2Color", b7r2Color);
		}
	};
}

1. Override the render() method. In the example, ConfigurationProvider accesses the configuration object. The servlet context provides access to the request dispatcher, which allows the custom JSP to read the configuration.

2. Make sure to use the @Reference annotation to define the module’s symbolic name.

   @Reference(
   	target = "(osgi.web.symbolicname=com.acme.b7r2.web)"
   )
   

Add the Web-ContextPath

Specify your bundle’s Web-ContextPath in the bnd.bnd file. For example, the sample project has Web-ContextPath: /b7r2-web in the Bnd file. This is what registers the ServletContext object in the configuration form renderer file. Note that a servlet context is created automatically for portlets, but since this sample doesn’t have a portlet, you must add a servlet context to the bnd.bnd file.

Create a Custom JSP

1. Import the configuration interface to the JSP.

   <%@ page import="com.acme.u2g5.web.internal.configuration.B7R2WebConfiguration" %>
   

2. Access the configuration values from the request object.

   <%
   B7R2WebConfiguration b7r2WebConfiguration = (B7R2WebConfiguration)request.getAttribute(B7R2WebConfiguration.class.getName());
   %>
   

3. Use an <aui:input> tag to read any new configuration inputs a user submits on the JSP file.

   <aui:input name="b7r2Color" value="<%= b7r2WebConfiguration.b7r2Color() %>" />
   

This sample project demonstrates a basic customized configuration UI with the use of ConfigurationFormRenderer. In your application, write your own code to further customize the look and feel of your configuration UI.