Introduction to Customization with Ext

Customization with Ext projects is deprecated and should only be used if absolutely necessary.

There are two types of Ext projects deployable to Liferay DXP:

• Ext plugins: used to customize Liferay DXP’s core functionality. For example, overwriting a class in a core artifact like com.liferay.portal.kernel.
• Ext modules: used to customize OSGi modules. For example, overwriting a JSP in the com.liferay.login.web module (see the Login Web Ext sample).

Ext projects are powerful tools used to extend Liferay DXP’s default core and/or module projects. They, however, increase the complexity of your Liferay DXP instance because they are a fork of the default project. Ext projects are not recommended unless there is absolutely no other way to accomplish your task.

Liferay DXP 7.2 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 project, weigh the cost. Ext projects 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 projects to merge your changes with Liferay DXP’s.

Before diving into Ext projects, first consider if an Ext project is even necessary at all.

Making the Decision to Use Ext Projects

There are many parts of Liferay DXP that now provide an extension point via OSGi bundle. You should follow this three step process to decide whether an Ext project is necessary:

1. Find the OSGi extension point that you need.

2. If an OSGi extension point does not exist, use an Ext project.

3. Research new extension points after every release of Liferay DXP. When a new version of Liferay DXP provides the extension point you need, always use the extension point to replace the existing Ext project.

So how do you find an OSGi extension point?

Your first step is to examine the custom projects that extend popular Liferay DXP extension points stored in the Liferay Blade Samples repository. For more information on these sample projects, see Sample Projects. Usable extension points are also documented throughout Liferay’s Developer Network categorized by the Liferay DXP section involved. For example, Overriding MVC Commands describes how to extend a Liferay DXP extension point. Want to learn how to customize JSPs? Those processes are documented too!

You’re now equipped to make an informed decision on using Ext projects.

Licensing and Contributing

Liferay DXP is Open Source software licensed under the LGPL 2.1 license. If you reuse any code snippet and redistribute it, whether publicly or to a specific customer, make sure your modifications are compliant with the license. One common way is to make the source code of your modifications are available to the community under the same license. Make sure you read the license text yourself to find the option that best fits your needs.

If your goal in making changes is fixing a bug or improving Liferay DXP, it could be of interest to a broader audience. Consider contributing it back to the project. That benefits all users of the product including you, since you won’t have to maintain the changes with each newly released version of Liferay DXP. You can notify Liferay of bugs or improvements at issues.liferay.com. Check out Liferay’s Participation information to learn all the ways that you can contribute to Liferay projects.

In summary, an Ext project 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 project, see if you can implement all or part of the desired functionality through Widget Templates or extension points, without introducing the complexity that’s inherent with Ext projects. If you need to use an Ext project, make your customization as small as possible and follow the instructions in this section carefully to avoid issues.