Custom Admin Portlet Plugin

Last Updated: Apr 27, 2020
documentation for the dotCMS Content Management System

This bundle is an example of how to create and add Portlets for use in the dotCMS administrative console using an OSGI bundle plugin.

This example includes the code to create three different types of Portlets, all of which are supported by dotCMS:

  • Velocity Portlet: a Portlet implementation that will display portlet content using a velocity file
  • Jsp Portlet: a Portlet implementation that will display portlet content using a jsp file
  • Struts Portlet: a Portlet implementation that will call an Struts Action class that will use a jsp file in order to display portlet content.


dotCMS uses the Struts 1 Forever package, which fixes all known security issues with Apache Struts, and which is continually maintained and patched.

How to create an OSGI bundle for Portlets

In order to create this OSGI plugin, you must create a META-INF/MANIFEST file to be included in the OSGI jar.

In this file you must specify (see the included plugin as an example):

Bundle-NameThe name of your bundle.
Bundle-SymbolicNameA short and unique name for the bundle.
Bundle-ActivatorPackage and name of your Activator class (example: com.dotmarketing.osgi.portlet.Activator).
DynamicImport-PackageDynamically add required imports the plugin without having to add them explicitly.
Import-PackageThis is a comma separated list of the names of packages to import. In this list there must be the packages that you are using inside your osgi bundle plugin and are exported and exposed by the dotCMS runtime.


In order to work inside Apache Felix OSGI runtime, the import and export directive must be bidirectional.

In dotCMS you must declare the set of packages that will be available to the OSGI plugins, either through the dotCMS backend (select Dev Tools -> Plugins and click Exported Packages) or by editing the file dotCMS/WEB-INF/felix/osgi-extra.conf.

An OSGI plugin can not import the packages and use them inside the OSGI bundle until after the packages have been added to the list of exported packages.



conf/ FolderContains the configuration files for the Portlets definitions.
Important: Both files in this folder are MANDATORY (!).
conf/portlet.xmlThe standard JSR-286 portlet configuration file.
conf/liferay-portlet.xmlDefines some optional Liferay-specific enhancements for JSR-286 portlets that are installed on a Liferay Portal server.
ext/ FolderContains the files used by the defined Portlets.
ext/view.vtlVelocity file used by the Velocity Portlet.
ext/hello.jspJsp file used by the Jsp Portlet.
ext/strutshelloworld/view.jspUsed by the Struts Portlet and invoked inside the HelloWorldAction.
ext/strutshelloworld/view_hello.jspUsed by the Struts Portlet and invoked inside the HelloWorldAction.


Simple Action class that extends com.dotmarketing.portal.struts.DotPortletAction.

The conf/portlet.xml file has the definition for a StrutsPortlet and that definition has a reference to the mapping for the HelloWorldAction.


Extends com.dotmarketing.osgi.GenericBundleActivator and implements BundleActivator.start().

This activator has 2 main important fragments of code:

  • It manually registers an ActionMapping for the dotCMS Struts action class HelloWorldAction that is used by the StrutsPortlet defined in the configuration files (conf/).
  • It manually registers the Portlets making use of the method registerPortlets.

Please Note: The unregisterServices() call on the stop method is MANDATORY (!). This enables dotCMS to clean and remove the registered Portlets and related code (like the ActionMappings registered in Struts).

Multilingual Support

The creation of the Portlets will generate the following language keys and use them as the title for the Portlets:

  • javax.portlet.title.EXT_HELLO_WORLD
  • javax.portlet.title.EXT_JSP_HELLO_WORLD
  • javax.portlet.title.EXT_STRUTS_HELLO_WORLD

In order to add multilingual values for those keys:

  1. Select Content Model -> Languages from the dotCMS backend.
  2. For each language you wish to support:
    • Click the flag icon next to the language name.
    • Click the +Add New Propery button at the bottom of the screen to add each of the language keys listed above to the language.

On this page


We Dig Feedback

Selected excerpt: