Completely Custom Configuration
A configuration UI is generated automatically when you create a configuration interface. But in some cases you want a completely custom UI for your configuration. For example, you plan to handle the configuration programmatically instead of using Liferay’s Configuration Admin. Or maybe you want the flexibility of creating a completely custom UI. Here’s how to do it.
See the Example Project
Start a new Liferay DXP instance by running
Sign in to Liferay at http://localhost:8080 using the email address test@liferay.com and the password test. When prompted, change the password to learn.
Then, follow these steps:
-
Download and unzip Completely Custom Configuration.
-
From the module root, build and deploy.
NoteThis 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.
-
Verify that the example module is working. Open your browser to
https://localhost:8080
. -
Navigate to Control Panel → Configuration → System Settings → Third Party. Click U2G5 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 three configurable attributes: fontColor
, fontFamily
, and fontSize
.
Note that under the @ExtendedObjectClassDefinition
annotation, generateUI
is set to false
. This excludes the configuration UI from being auto-generated.
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 Screen
-
Declare the class as an implementation of
ConfigurationScreen
with the@Component
annotation. -
Set the category key, the configuration entry’s key, and its localized name. In the sample project, the category key is set to
third-party
in System Settings. The string value for the configuration’s name is set by the language key in the bundle’sLanguage.properties
file.
- For this example, the configuration scope is set to
system
. To learn more, see Scoping Configurations.
- The
render()
method usesConfigurationProvider
to get the configuration. The servlet context provides access to the request dispatcher, which allows the custom JSP to read the configuration.
- Make sure to use the
@Reference
annotation to define the module’s symbolic name.
Add the Web-ContextPath
Specify your bundle’s Web-ContextPath
in the bnd.bnd
file. For example, the sample project has Web-ContextPath: /u2g5-web
in the Bnd file. This is what registers the ServletContext
object in the Configuration Screen file. Note that a servlet context is created automatically for portlets, but since this sample doesn’t have a portlet, you must add this line to the Bnd file.
Create a Custom JSP
-
Import the configuration interface to the JSP.
-
Access the configuration values from the request object.
-
The attributes
fontColor()
,fontFamily()
,fontSize()
can now be used in the JSP.
This sample project demonstrates a basic example of how to use ConfigurationScreen
to read and display configuration values in a custom JSP. In your application, write your own code and create a completely custom configuration UI to meet your needs.