Setting and Accessing Configurations

You can use Liferay’s configuration framework to add a settings UI for a MVC Portlet.

See the Example Portlet

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.112-ga112

Sign in to Liferay at http://localhost:8080. Use the email address test@liferay.com and the password test. When prompted, change the password to learn.

Then, follow these steps:

Download and unzip Setting and Accessing Configurations.

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

unzip liferay-n2f3.zip

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.
Confirm the deployment in the Liferay Docker container console.
```
STARTED com.acme.n2f3.web.0.0 [1650]
```
Verify that the example module is working. Open your browser to https://localhost:8080
Add the N2F3 Portlet to a page. You can find the example portlet under Sample Widgets.

The UI shows a welcome message along with the three configurable attributes: font color, font family, and font size.
To change the configuration, navigate to Control Panel → Configuration → System Settings. Under Other click category.n2f3.

Try entering a different font color, font family, and font size. Click the Update button and go back to your page with the published widget. Verify that the attributes have changed.

Here’s how the configuration framework works.

Creating the Configuration Interface

Defining configurable attributes in a configuration interface is enough to generate a configuration UI in System Settings.

In the sample project, the N2F3WebConfiguration.java file is the configuration interface.

@ExtendedObjectClassDefinition(
	category = "n2f3", scope = ExtendedObjectClassDefinition.Scope.COMPANY
)
@Meta.OCD(
	id = "com.acme.n2f3.web.internal.configuration.N2F3WebConfiguration",
	localization = "content/Language", name = "n2f3-configuration-name"
)
public interface N2F3WebConfiguration {

	@Meta.AD(deflt = "blue", required = false)
	public String fontColor();

	@Meta.AD(deflt = "serif", required = false)
	public String fontFamily();

	@Meta.AD(deflt = "16", required = false)
	public int fontSize();

}

Note, for this example interface the scope is set to Scope.COMPANY. See Scoping Configurations for more information.

The interface has three configurable attributes: font color, font family, and font size. Note that color and family are type string and size is type int.

Meta.OCD registers this class as a configuration with a specific ID.

Important

Note that the ID must be the fully qualified class name (FQCN) of the configuration interface.

Meta.AD specifies optional metadata about the attribute such as a default value or whether the attribute is a required field. Note that if an attribute value is required but a default is not set, an administrator must set a value in settings for the application to work properly.

Next, see how the configuration is read by the MVC Portlet.

Reading the Configuration from the Application

In the @Component annotation, the configuration interface class is specified with the configurationPid:
```
configurationPid = "com.acme.n2f3.web.internal.configuration.N2F3WebConfiguration"
```
To access the configuration, the render() method utilizes a ConfigurationProvider. The Configuration Provider API provides methods to retrieve a configuration at different levels of scope. The sample project’s configuration is instance scoped and uses the getCompanyConfiguration() method to retrieve the configuration.

try {
	renderRequest.setAttribute(
		N2F3WebConfiguration.class.getName(),
		_configurationProvider.getCompanyConfiguration(
			N2F3WebConfiguration.class,
			_portal.getCompanyId(renderRequest)));
}

The configuration object is added to the request object and can now be read from the request of the application's JSP.

Accessing the Configuration from a JSP

The following import statement adds the configuration interface to the JSP:

<%@ page import="com.acme.n2f3.web.internal.configuration.N2F3WebConfiguration" %>

The configuration object from the request object is obtained and the configuration values are read.

<%
N2F3WebConfiguration n2f3WebConfiguration = (N2F3WebConfiguration)request.getAttribute(N2F3WebConfiguration.class.getName());
%>

The attributes fontColor(), fontFamily(), fontSize() can now be used in the JSP.

The sample project has three attributes that can be configured. Currently the attributes must be manually entered into a text input field, but this can be further customized.

For example, you can use a dropdown list for the font family attribute instead of an input field. In the project’s configuration interface, replace the @Meta.AD annotation with this:

@Meta.AD(
	optionLabels = {"Arial", "Georgia", "Helvetica", "Tahoma", "Verdana"},
	optionValues = {"arial", "georgia", "helvetica", "tahoma", "verdana"},
required = false)

Redeploy the example module.

The font family is now a dropdown selection.

Now the font family attribute is a dropdown selection.

ConfigurationBeanDeclaration with Previous Versions of Liferay

Important

For Liferay DXP 7.4 U51+ and Liferay Portal 7.4 GA51+, a ConfigurationBeanDeclaration class is not required. The configration interface is registered with the Configuration Provider API automatically.

On Liferay versions before 7.4 Update/GA 51, the configuration class must be registered with a ConfigurationBeanDeclaration to use it with the Configuration Provider API. The ConfigurationBeanDeclaration class has one method that returns the configuration interface class. This helps the system keep track of configuration changes as they happen. For example, for the N2F3 portlet, create a class like this:

@Component(service = ConfigurationBeanDeclaration.class)
public class N2F3WebConfigurationBeanDeclaration
	implements ConfigurationBeanDeclaration {

	@Override
	public Class<?> getConfigurationBeanClass() {
		return N2F3WebConfiguration.class;
	}

}

In this example, place the class in the com.acme.n2f3.web.internal.settings.definition package.

Capability: