Transition From Portlet Preferences To The Configuration API

blog-banner

To store portlet level configuration data, we are mostly using  Portlet preferences. There is also another way available to configure Liferay Portal CE 7.0 applications which is Configuration API. I am going to show how we can move from portlet preferences to  Configuration API.

 

The main benefit of using the Configuration API is we can configure default settings of portlet through System Settings UI.

Here is a complete guide for how we can switch from the traditional way to store portlet preferences to the new way with  Configuration API. Below are detailed steps to do so:

Step - 1

Create a jsp to get inputs of configuration,

Give it a name  configuration.jsp

Add all configuration input fields in this configuration jsp

Example:

<liferay-portlet:actionURL portletConfiguration="<%= true %>" var="<%= configurationActionURL %>" />
<liferay-portlet:renderURL portletConfiguration="<%= true %>" var="<%= configurationRenderURL %>" />

<aui:form action="<%=configurationActionURL%>" method="post" name="fm" />

<aui:input name="redirect" type="hidden" value="<%= configurationRenderURL %>" />
<aui:input name="<%=Constants.CMD%>" type="hidden" value="<%=Constants.UPDATE%>" />
<aui:input name="displayCountry" label="Country" value="<%= portletInstanceConfiguration.displayCountry() %>"/>
<aui:button type="submit"></aui:button>

</aui:form>

Step - 2

Create a jsp to get inputs of configuration, Give it a name configuration.jsp Add all configuration input fields in this configuration jsp

There are mainly three kinds of portlet configuration Scopes:

  • Portlet Instance
  • Group
  • Company

Create a Java interface for the configuration

  • As per Liferay, Interface name should be
    • [Portlet name]PortletInstanceConfiguration for the Portlet Instance scope
    • [Portlet name]GroupServiceConfiguration for the Group scope, However you can choose different names
  • This interface will use two annotations:  @ExtendedObjectClassDefinition and  @Meta.OCD.
    • @ExtendedObjectClassDefinition is used to specify the desired scope and to specify the category in System Settings where these preferences are displayed.
    • @Meta.OCD is used to add  id which is used to identify the configuration interface and it must be the fully qualified class name of the interface. Another two properties are  localization (to localize portlet configuration) and  name (to specify the name of the configuration as it will appear in System Settings)
    • Example:

      @ExtendedObjectClassDefinition(
          category = "[category]",
          scope = ExtendedObjectClassDefinition.Scope.PORTLET_INSTANCE
      )
      @Meta.OCD(
          id = "[package].[PortletName]PortletInstanceConfiguration",
          localization = "content/Language", 
          name = "[name]"
      )
      public interface [PortletName]PortletInstanceConfiguration {
          @Meta.AD(required = false)
          public String displayCountry();
      }
  • Replace [category] with a category name of your choice (You can give an existing category of System Settings or provide a custom category name which will be added to System Settings in Liferay Portal).
  • Localization is used to translate it to several languages
  • Replace [name] with a configuration name of your choice

Step - 3

Override the processAction method so that it reads a URL parameter from the action request, sets the value as a portlet preference, and invokes the processAction method of the SettingsConfigurationAction ancestor class

Example:

public class [PortletName]ConfigurationAction extends DefaultConfigurationAction { @Override public String getJspPath(HttpServletRequest request) { return "/configuration.jsp"; } @Override public void processAction(PortletConfig portletConfig, ActionRequest actionRequest, ActionResponse actionResponse) throws Exception { String displayCountry = ParamUtil.getString(actionRequest, "displayCountry"); setPreference(actionRequest, "displayCountry", displayCountry); super.processAction(portletConfig, actionRequest, actionResponse); } @Override @Reference( target = "(osgi.web.symbolicname=[symbolic_name])", unbind = "-" ) public void setServletContext(ServletContext servletContext) { super.setServletContext(servletContext); } }
  • Replace [symbolic_name] by the bundle’s symbolic name which you can find in bundle’s bnd.bnd file

Step - 4

Create one class that implements the  ConfigurationBeanDeclaration interface to know about the Configuration class.

Example:

@Component
public class [PortletName]PortletInstanceConfigurationBeanDeclaration
        implements ConfigurationBeanDeclaration {
    @Override
    public class getConfigurationBeanClass() {
        return [PortletName]PortletInstanceConfiguration.class;
    }
}

Step - 5

Now, Change the configuration JSP by adding following code to retrieve the configuration using the Configuration API. If the portlet configuration scope is  Portlet Instance the configuration can be retrieved from  portletDisplay.

Example:

[PortletName]PortletInstanceConfiguration portletInstanceConfiguration = 
    portletDisplay.getPortletInstanceConfiguration(
       [PortletName]PortletInstanceConfiguration.class);

After getting configuration object, you can retrieve preferences as follow:

String displayCountry = portletInstanceConfiguration.displayCountry();

Step - 6

In case where the  portletDisplay is not available, or when the scope is  Group or  Company then use the  PortletProvider class.

  • In OSGI component, we can obtain reference to the  ConfigurationProvider by following code:
    @Component(service = Entity)
    public class Entity {
    protected void methodWhichNeedsConfiguration() {
    _configurationProvider.getGroupConfiguration(
     [PortletName]GroupServiceConfiguration.class, groupId);
    }
    @Reference
                private ConfigurationProvider _configurationProvider;
          }
    
  • To use configuration data in services which are created by Service Builder then use below code
    public class EntityServiceImpl {
    	protected void methodWhichNeedsConfiguration() {
    		   _configurationProvider.getGroupConfiguration(
    			[PortletName]GroupServiceConfiguration.class, groupId);
    	}
    	@Reference
    	private ConfigurationProvider _configurationProvider;
    }
    
  • For any other cases other than above, We can use  ConfigurationProviderUtil to obtain the configuration.
    [PortletName]GroupServiceConfiguration groupConfiguration =   
    ConfigurationProviderUtil.getGroupConfiguration([PortletName]GroupServiceConfiguration.class, groupId);
    

That's it..!! You are ready to go with Configuration API.

Contact us

For Your Business Requirements

Text to Identify Refresh CAPTCHA
Background Image Close Button

2 - 4 October 2024

Hall: 10, Booth: #B8 Brussels, Belgium