Ext plugins are powerful tools used to extend Liferay DXP. They, however, increase the complexity of your Liferay DXP instance and are not recommended unless there is absolutely no other way to accomplish your task. Liferay DXP 7.0 provides many extension points that let you customize almost every detail of Liferay DXP. If there’s a way to customize what you want with an extension point, do it that way instead. See the More Extensible, Easier to Maintain section for more details on the advantages of using Liferay DXP’s extension points.
Before deciding to use an Ext plugin, weigh the cost. Ext plugins let you use internal APIs and even let you overwrite Liferay DXP core files. This puts your deployment at risk of being incompatible with security, performance, or feature updates released by Liferay. When upgrading to a new version of Liferay DXP (even if it’s a maintenance version or a service pack), you have to review all changes and manually modify your Ext plugin to merge your changes with Liferay DXP’s. Additionally, Ext plugins aren’t hot deployable. To deploy an Ext plugin, you must restart your server. Additional steps are also required to deploy or redeploy to production systems.
In this tutorial, you’ll learn how to
Before diving into creating an Ext plugin, however, first consider if an Ext plugin is necessary.
There are many parts of Liferay DXP that now provide extension points via OSGi bundle. You should follow this three step process to decide whether an Ext plugin is necessary:
- Find the OSGi extension point that you need. You can follow the Finding Extension Points tutorial as a guide.
- If an OSGi extension point does not exist, use an Ext plugin.
- Research new extension points after every release of Liferay DXP. When a new version of Liferay DXP provides the extension point need, always use the extension point to replace the existing Ext plugin.
So how do you find an OSGi extension point?
Your first step is to examine the custom module projects that extend popular Liferay DXP extension points stored in the Liferay Blade Samples repository. For more information on these sample projects, see the Liferay Sample Projects tutorial. Usable extension points are also documented throughout Liferay’s Customer Portal categorized by the Liferay DXP section involved. For example, Overriding MVC Commands and Customizing the Product Menu are articles describing how to extend a Liferay DXP extension point. Want to learn how to override module JSPs or Liferay DXP core JSPs? Those processes are documented too!
There are a few corner cases where you may need an Ext plugin to customize a part of Liferay DXP that does not provide an extension point. Refer to the top of this tutorial for Ext plugin use cases supported by Liferay.
Now that you know how to make an informed decision on using Ext plugins, if you still need to use them, you’ll learn how to create one next.
An Ext plugin is a powerful tool for extending Liferay DXP. Because it increases the complexity of your Liferay DXP installation, you should only use an Ext plugin if you’re sure you can’t accomplish your goal in a different way. You can only create Ext plugins from a Plugins SDK. If you’re using a Liferay Workspace to create your @project@ projects, you can merge a Plugins SDK instance into the workspace.
Follow the steps below, replacing the project name with your own, to create a custom Ext plugin:
Go to File → New → Liferay Plugin Project.
Enter your project’s name and its display name. In the figure below, example is used for both. Note that the Display name field is automatically filled in with the capitalized version of the Project name.
Select the Ant (liferay-plugins-sdk) option for your build type.
Select the Ext plugin type. Then click Next.
If you have not yet configured a Plugins SDK, select Next and choose the Plugins SDK for which you want to generate the Ext plugin. Once you have your Plugins SDK configured, click Finish.
The Plugins SDK automatically appends
-ext to the plugin project name when it
creates your Ext plugin’s project folder. Your Ext plugin project is added to
your configured Plugins SDK instance and is also available via Developer Studio’s Package
Explorer for further development.
To create a new Ext plugin from the command line, navigate to the
in your Liferay Plugins SDK and enter the command below appropriate for your
operating system. The two arguments after the
create command are the project
name and display name, respectively. The examples below use the project name
example and the display name Example. Make sure to specify values you want
to use for your Ext plugin’s project name and display name.
In Linux or Mac OS, enter:
./create.sh example "Example"
In Windows, enter:
create.bat example "Example"
BUILD SUCCESSFUL message from Ant tells you there’s a new folder (e.g.,
example-ext for a project named example) inside your Plugins SDK’s
ext folder. The Plugins SDK automatically appends
-ext to the project name.
There are a few things to note about an Ext plugin’s folder structure. Below is a listing of an Ext folder structure:
Here are detailed explanations of the
ext-impl/src: Contains the custom implementation classes and classes that override core classes from
ext-lib/global: Contains libraries to be copied to the application server’s global classloader upon deployment of the Ext plugin.
ext-lib/portal: Contains libraries to be copied inside Liferay’s main application. These libraries are usually necessary because they’re invoked from classes you add in
ext-kernel/src: Contains classes that should be available to other plugins. In advanced scenarios, this folder can be used to hold classes that overwrite classes from
ext-web/docroot: Contains the web application’s configuration files, including
WEB-INF/struts-config-ext.xml, which lets you customize Liferay’s core struts classes. Note that for Liferay DXP 7.0, there are very few entities left to override in the
struts-config.xmlfile. Any JSPs that you’re customizing also belong here.
ext-util-taglib: These folders are needed only in scenarios where you must customize these Liferay libraries:
util-taglib.jar, respectively. If you’re not customizing any of these libraries, you can ignore these folders.
By default, several files are also added to the plugin. Here are the most significant files:
build.xml: The Ant build file for the Ext plugin project.
docroot/WEB-INF/liferay-plugin-package.properties: Contains plugin-specific properties, including the plugin’s display name, version, author, and license type.
portlet-ext.xml: Used to overwrite the definition of a built-in portlet. The
portlet.xmlfile contains very few portlet configurations in Liferay DXP 7.0 because portlets were modularized and moved out of core. To override this file, copy the complete definition of the desired portlet from
portlet-custom.xmlin Liferay’s source code, then apply the necessary changes.
liferay-portlet-ext.xml: This file is similar to
portlet-ext.xml, but is for additional definition elements specific to Liferay. The
liferay-portlet.xmlfile contains very few definition elements in Liferay DXP 7.0 because portlets were modularized and moved out of core. To override the remaining definition elements, copy the complete definition of the desired portlet from
liferay-portlet.xmlin Liferay’s source code, then apply the necessary changes.
tiles-defs-ext.xml: These files are used to customize the struts actions used by core portlets. Since most portlets were modularized and moved out of core in Liferay DXP 7.0, the
tiles-defs.xmlfiles are sparsely used.
web.xml: Used to overwrite web application configurations and servlet information for Liferay DXP 7.0.
Great! You’ve now created an Ext plugin and are familiar with its folder structure and its most significant files. Next, you’ll use your Ext plugin to customize Liferay DXP.
An Ext plugin changes Liferay DXP itself when the plugin is deployed; it’s not a separate component that you can easily remove at any time. For this reason, the Ext plugin development process is different from other plugin types. It’s important to remember that once an Ext plugin is deployed, some of its files are copied inside the Liferay installation; the only way to remove the changes is by redeploying an unmodified Liferay application. You’re also responsible for checking that patches and fix packs do not conflict with your Ext plugin.
The Liferay DXP 7.0 compatible Plugins SDK is designed to only develop/deploy one
Ext plugin. This means that all your customizations should live inside one Ext
plugin. The Plugins SDK does not check for conflicts among multiple Ext plugins
stored in the
/ext folder, so do not develop/deploy multiple Ext plugins
The Plugins SDK lets you deploy and redeploy your Ext plugin during your development phase. Redeployment involves cleaning (i.e., removing) your application server and unzipping your specified Liferay bundle to start from scratch. That way, any changes made to the Ext plugin during development are properly applied, and files removed from your plugin by previous changes aren’t left behind in the Liferay DXP application. Because of this added complexity, you should use another plugin type to accomplish your goals whenever possible.
Before digging in to the details, here’s an overview of the Ext plugin development processes described below:
- Configure your Plugins SDK environment to develop Ext plugins for Liferay DXP on your application server.
- Deploy and publish your Ext plugins for the first time.
- Redeploy normally or use a clean redeployment process after making changes to your Ext plugin.
- Package your Ext plugin for distribution.
- A list of advanced customization techniques.
It’s time to learn each step of the development process.
Before deploying an Ext plugin, you must edit the
file in the root folder of your Plugins SDK. If the file doesn’t yet exist,
create it now. Substitute
[username] with your user ID on your computer.
Once you’ve opened your build properties file, add the following
properties–make sure the individual paths reflect the right locations on your
app.server.zip.name property must specify the path to your Liferay DXP
.zip file. The
work folder you specify for the
ext.work.dir property is
where you’ve unzipped your Liferay DXP runtime. The
app.server.dir property must
point to your application server’s directory in your work folder. Look in your
Liferay DXP bundle at the path to the application server to determine the value to
use for your
For example, if your work folder is
C:/work, specify it as your
ext.work.dir property’s value. If your Liferay DXP bundle
.zip file is
app.server.zip.name property to that file’s path. If the relative
path to the application server within the Liferay DXP bundle
.zip file is
liferay-dxp-digital-enterprise-7.0-sp2\tomcat-8.0.32, specify an
app.server.dir property value
Next you’ll modify the Ext plugin you created and deploy it.
Your environment is set up and you’re ready to start customizing. Once you’re finished, you can deploy the plugin.
Now you’ll learn how to deploy your plugin using Liferay Developer Studio or the command line.
Drag your Ext plugin project from your Package Explorer onto your server to deploy your plugin. Liferay Developer Studio automatically restarts the server for the server to detect and publish your Ext plugin.
After deploying, if you don’t see your customizations in the portal, your Ext plugin may not have successfully deployed. To confirm whether the Ext plugin deploys successfully, try deploying from the command line; the Ant deployment targets report success or failure.
Open a command line window in your Ext plugin project folder and enter one of these commands:
ant deploy ant direct-deploy
direct-deploytarget deploys all changes directly to the appropriate folders in the Liferay application. The
deploytarget creates a
.warfile with your changes and then deploys it to your server. Either way, your server must be restarted after the deployment. Using
direct-deployis preferred for deploying an Ext plugin during development if your application server supports it. Direct deploy doesn’t work in WebLogic or WebSphere application server environments.
BUILD SUCCESSFULmessage indicates your plugin is now being deployed. Your console window running Liferay DXP shows a message like this:
Extension environment for [your project]-ext has been applied. You must reboot the server and redeploy all other plugins
If any changes applied through the Ext plugin affect the deployment process itself, you must redeploy all other plugins. Even if the Ext plugin doesn’t affect the deployment process, it’s a best practice to redeploy all your other plugins following initial deployment of the Ext plugin.
ant deploytarget builds a
.warfile with your changes and copies them to the auto-deploy folder inside the Liferay DXP installation. When the server starts, it detects the
.warfile, inspects it, and copies its contents to the appropriate destinations inside the deployed and running Liferay application.
Restart the server so that it detects and publishes your Ext plugin.
Once your server restarts, open Liferay DXP to see the customizations you made with your Ext plugin.
Frequently, you’ll want to add further customizations to your original Ext plugin. You can make unlimited customizations to an Ext plugin that has already been deployed, but the redeployment process is different from other project types. You’ll learn more on redeploying your Ext plugin next.
So far, Ext plugin development has been similar to the development of other plugin types. You’ve now reached the point of divergence. When the plugin is first deployed, some of its files are copied into the Liferay DXP installation. After changing an Ext plugin, you’ll either clean redeploy or redeploy, depending on the modifications you made to your plugin following the initial deployment. You’ll learn about each redeployment method and when to use each one.
If you removed part(s) of your plugin, if there are changes to your plugin that can affect plugin deployment, or if you want to start with a clean Liferay DXP environment, undeploy your plugin and clean your application server before redeploying your Ext plugin. By cleaning the application server, the existing Liferay DXP installation is removed and the bundle specified in your Plugins SDK environment is unzipped in its place. See the instructions below to learn more about this process.
Remove the plugin from the server. While selecting the Ext plugin in the Servers view, select the plugin’s Remove option.
Clean the application server. Remember to shut down the application server before cleaning it. This is required on Windows because the server process locks the installed Liferay bundle’s files.
While selecting the Ext plugin project in the Package Explorer view, select the plugin’s Liferay → Clean App Server… option.
Start the Liferay server.
Drag the Ext plugin and drop it onto the Liferay server.
While selecting the Liferay server in the Servers view, click the Publish option.
Stop the Liferay DXP server.
To deploy your Ext plugin, enter the following commands into your console:
cd [your-plugin-ext] ant clean-app-server ant direct-deploy
Start the Liferay DXP server.
If you only added to your plugin or made modifications that don’t affect the plugin deployment process, you can redeploy the Ext plugin. Follow the steps based on the tool you’re using.
Right-click your plugin located underneath your server and select Redeploy.
Using the same procedure as for initial deployment. Open a command line window
in your Ext plugin project’s directory and execute either
ant deploy or
After your plugin is published to Liferay DXP, verify that your customizations are available.
Next you’ll learn how to package an Ext plugin for distribution and production.
Once you’re finished developing an Ext plugin, you can package it in a
file for distribution and production deployment.
With your Ext plugin project selected in the Package Explorer view, select the project’s Liferay → SDK → war option.
From your Ext plugin’s directory execute
.war file is written to your
Now that you’ve learned the basics of Ext plugin development, you’ll look at some advanced customizations.
Liferay DXP uses several internal configuration files for its own architecture; in addition, there are configuration files for the libraries and frameworks Liferay DXP depends on, like Struts and Spring. Configuration could be accomplished using fewer files with more properties in each, but maintenance and use is made easier by splitting up the configuration properties into several files. For advanced customization needs, it may be useful to override the configuration specified in multiple configuration files. Liferay DXP provides a clean way to do this from an Ext plugin without modifying the original files.
All the configuration files in Liferay DXP are listed below by their path in an Ext plugin folder. Here are descriptions of what each file is for and the path to the original file in Liferay DXP:
- Description: Overrides the default field properties of the data models used by Liferay DXP’s core portlets. These properties determine how the form fields for each model are rendered.
- Original file in Liferay DXP:
- Description: Overrides the Spring configuration used by Liferay DXP and any of its core portlets. It’s most commonly used to configure specific data sources or swap the implementation of a default service with a custom one.
- Original file in Liferay DXP:
- Description: Overrides the core portlets’ declarations. It’s most commonly used to change the init parameters or the roles specified.
- Original file in Liferay DXP:
- Description: Overrides the Liferay-specific core portlets’ declarations. It core portlets included in Liferay DXP. Refer to the liferay-portlet-app_7_0_0.dtd file for details on all the available options. Use this file with care; the code of the portlets may be assuming some of these options to be set to certain values.
- Original file in Liferay DXP:
- Description: Overrides the portlets that are shown in the interface for adding applications and the categories in which they’re organized.
- Original file in Liferay DXP:
You’ll learn how to deploy your Ext plugin in production next.
Often, you can’t use Ant to deploy web applications in production or pre-production environments. Additionally, some application servers such as WebSphere or WebLogic have their own deployment tools and don’t work with Liferay DXP’s auto-deployment process. Here are two methods to consider for deploying and redeploying an Ext plugin in production.
You can use this method in any application server that supports auto-deployment;
What’s the benefit? The only artifact that needs to be transferred to the
production system is your Ext plugin’s
.war file, produced using the
.war file is usually small and easy to transport. Execute these
steps on the server:
Redeploy Liferay DXP:
If this is your first time deploying your Ext plugin to this server, skip this step. Otherwise, start by executing the same steps you first used to deploy Liferay DXP on your app server. If you’re using a bundle, unzip it again. If you installed Liferay DXP manually on an existing application server, you must redeploy the Liferay DXP
.warfile and copy both the libraries required globally by Liferay DXP and your Ext plugin to the appropriate folder within the application server.
Copy the Ext plugin
.warinto the auto-deploy folder. For a bundled Liferay DXP distribution, the
deployfolder is in Liferay’s root folder of your bundle (e.g.,
Once the Ext plugin is detected and deployed by Liferay DXP, restart your Liferay DXP server.
Some application servers don’t support auto-deploy; WebSphere and WebLogic are
two examples. With an aggregated
.war file, the Ext plugin is merged before
deployment to production. A single
.war file then contains Liferay DXP plus the
changes from your Ext plugin. Before you deploy the aggregated Liferay DXP
.war file, copy the dependency
.jar files for Liferay DXP and your Ext plugin
to the global application server class loader in the production server. The
precise location varies from server to server; refer to
Deployment to get the details for your application
To create the aggregated
.war file, deploy the Ext plugin first to the
Liferay DXP bundle you are using in your development environment. Once it’s
deployed, restart the server so that the plugin is fully deployed and shut it
down again. Now the aggregated file is ready.
.war file by zipping the Liferay web application folder from within
the app server. Copy into your application server’s global classpath all of the
libraries on which your Ext plugin depends.
Now, perform these actions on your server:
Redeploy Liferay DXP using the aggregated
Stop the server and copy the new version of the global libraries to the appropriate directory in the application server.
Next, you’ll learn about Liferay’s licensing and contributing standards.
If you’re using the Tomcat app server and have not upgraded to Liferay DE SP4+,
you must modify your app server’s
conf/Catalina/localhost/ROOT.xml file. Add
the following code to that file:
Be sure to place this code within the existing
An Ext plugin is a powerful way to extend Liferay DXP. There are no limits to what you can customize, so use it carefully. Before using an Ext plugin, see if you can implement all or part of the desired functionality through Application Display Templates or a different plugin type. OSGi modules offer you a lot of extension capabilities themselves, without introducing the complexity that’s inherent with Ext plugins. If you need to use an Ext plugin, make your customization as small as possible and follow the instructions in this tutorial carefully to avoid issues.