Configuring a Liferay Workspace

A Liferay Workspace offers a development environment that can be configured to fit your development needs. You’ll learn about the files/folders a workspace provides by default, and then you’ll dive into configuring your workspace.

The top-level files/folder of a Liferay workspace are outlined below:

• bundles (generated): the default folder for Liferay DXP bundles.
• configs: holds the configuration files for different environments. These files serve as your global configuration files for all Liferay servers and projects residing in your workspace. To learn more about using the configs folder, see the Testing Modules section.
• gradle: holds the Gradle Wrapper used by your workspace.
• modules: holds your custom modules.
• plugins-sdk (generated): holds plugins to migrate from previous releases.
• themes: holds your custom themes which are built using the Theme Generator.
• wars (generated): holds traditional WAR-style web application projects.
• build.gradle: the common Gradle build file.
• gradle-local.properties: sets user-specific properties for your workspace. This lets multiple users use a single workspace, letting them configure specific properties for the workspace on their own machine.
• gradle.properties: specifies the workspace’s project locations and Liferay DXP server configuration globally.
• gradlew: executes the Gradle command wrapper
• settings.gradle: applies plugins to the workspace and configures its dependencies.

The build/properties files included in your workspace’s root folder sets your workspace’s Gradle properties and facilitates the build processes of your modules.

Before you begin using your workspace, you should set your workspace Gradle properties in the gradle.properties file. There are several commented out properties in this file. These are the default properties set in your workspace. If you’d like to change a variable, uncomment the variable and set it to a custom value. For instance, if you want to store your modules in a folder other than [ROOT]/modules, uncomment the liferay.workspace.modules.dir variable and set it to a different value.

If you’d like to keep the global Gradle properties the same, but want to change them for yourself only (perhaps for local testing), you can override the gradle.properties file with your own gradle-local.properties file.

Note: Liferay Workspace provides many subprojects for you behind the scenes, which hides some complexities of Gradle. You can learn more about this in the Building Modules section.

Now that you know about a workspace’s default folder structure and how to modify its Gradle properties, you’ll learn how to add a Liferay bundle to your workspace.

Adding a Liferay Bundle to a Workspace

Liferay Workspaces can generate and hold a Liferay Server. This lets you build/test your plugins against a running Liferay instance. Before generating a Liferay instance, open the gradle.properties file located in your workspace’s root folder. There are several configurable properties for your workspace’s Liferay instance. You can set the version of the Liferay bundle you’d like to generate and install by setting the download URL for the liferay.workspace.bundle.url property (e.g., https://releases-cdn.liferay.com/portal/7.0.6-ga7/liferay-ce-portal-tomcat-7.0-ga7-20180507111753223.zip). You can also set the folder where your Liferay bundle is generated with the liferay.workspace.home.dir property. It’s set to bundles by default.

You can download a Liferay DXP bundle for your workspace if you’re a DXP subscriber. Do this by setting the liferay.workspace.bundle.url property to a ZIP hosted on api.liferay.com. For example,

liferay.workspace.bundle.url=https://api.liferay.com/downloads/portal/7.0.10.8/liferay-dxp-digital-enterprise-tomcat-7.0-sp8-20180717152749345.zip

It can be tricky to find the fully qualified ZIP name/number for the DXP bundle you want. You cannot access Liferay’s API site directly to find it, so you must start to download DXP manually, take note of the file name, and append it to https://api.liferay.com/downloads/portal/.

You must also set the liferay.workspace.bundle.token.download property to true to allow your workspace to access Liferay’s API site.

Once you’ve finalized your Gradle properties, navigate to your workspace’s root folder and run

blade server init

This uses workspace’s pre-bundled Blade CLI tool to download the version of Liferay DXP you specified in your Gradle properties and installs your Liferay instance in the bundles folder.

If you want to skip the downloading process, you can create the bundles folder manually in your workspace’s ROOT folder and unzip your Liferay DXP bundle to that folder.

You can also produce a distributable Liferay bundle (Zip or Tar) from within a workspace. To do this, navigate to your workspace’s root folder and run the following command:

./gradlew distBundle[Zip|Tar]

Your distribution file is available from the workspace’s /build folder.

Note: You can define different environments for your Liferay bundle for easy testing. You can learn more about this in the Testing Modules section.

The Liferay Workspace is a great development environment for Liferay module development; however, what if you’d like to also stick with developing WAR-style applications? Liferay Workspace can handle that request too!

Using a Plugins SDK from Your Workspace

Because Liferay DXP 7.0 uses a module-based framework, the current structure of a Liferay Workspace is centered around module development. There are still, however, many situations where you must create WAR-style plugins using the Plugins SDK. Because of this, your workspace can also work with the Plugins SDK. When configuring your SDK in a workspace, you can take advantage of all the new functionality workspaces provide and also use the SDK environment that you’re used to. To learn more about upgrading legacy applications to Liferay DXP 7.0 and what you should consider before converting them to modules, visit the tutorial Planning Plugin Upgrades and Optimizations.

The Blade CLI offers a command that adds and configures your current Plugins SDK environment automatically for use inside a newly generated workspace (e.g., blade init -u). You can learn more about this in the Creating a Liferay Workspace with Blade CLI tutorial. If you created your workspace from scratch and want to use a Plugins SDK, however, you can add one to your workspace by completing one of the two options:

1. Copy your existing Plugins SDK’s files into the workspace.

2. Generate a new Plugins SDK to use in the workspace.

Follow the appropriate section based on the option you want to follow.

Copying an Existing Plugins SDK into Workspace

If you open your workspace’s gradle.properties file, you’ll notice the liferay.workspace.plugins.sdk.dir property sets the Plugins SDK folder to plugins-sdk. This is where the workspace expects any Plugins SDK files to reside. This folder was not generated by default, so you must create it yourself. In your workspace’s root folder, create the plugins-sdk folder. Then copy your legacy Plugins SDK files into the plugins-sdk folder.

The copied Plugins SDK requires many build-related artifacts. To start the artifact download process, execute the following command in your workspace’s root folder:

./gradlew upgradePluginsSDK

The Plugins SDK’s artifacts are downloaded. The Plugins SDK is now ready for use!

Generating a New Plugins SDK in Workspace

You can easily generate a new Plugins SDK for your workspace by executing a single Gradle command in your workspace’s root folder:

./gradlew upgradePluginsSDK

This generates a new Liferay DXP 7.0 Plugins SDK into the folder set by the liferay.workspace.plugins.sdk.dir property, which is configured to plugins-sdk by default in the workspace’s gradle.properties file. You can change the folder name by updating the property. The downloaded Plugins SDK version is the latest release at the time of execution. You can reference the latest Plugins SDK releases here.

Once the downloading is complete, your Plugins SDK is ready to use in your workspace!