Setting Up Client Extension Projects
Client extension projects reside in your Liferay workspace. This workspace provides a structured development environment for building, deploying, and testing your extensions. To begin developing client extensions, you must have a client-extensions
folder to your workspace's root directory (i.e., [WORKSPACE_ROOT]/client-extensions
). This folder is for storing and organizing all your client extension projects.
Inside the client-extensions
folder, you'll create separate subfolders for each project. Projects may contain one or more client extensions, and separate projects can interact with one another. Every project must include a client-extension.yaml
file, which identifies the extensions included in the project and defines their properties and deployment instructions. When you build a project, it produces a deployable ZIP archive called a Liferay Universal File Format Archive (LUFFA).
Anatomy of Client Extension YAML Files
The client-extension.yaml
file provides a structured way to declare and manage the various extensions that make up your project. Each file typically includes two elements:
- Assemble Block (optional): This section configures how the project is packaged during the build process.
- Client Extension Definitions: These sections define the individual client extensions included in the project, along with their properties and configurations.
While the assemble block is optional, each client-extension.yaml
file must include at least one client extension definition.
Assemble Block
When you execute a Gradle build for a client extension project, Gradle automatically packages client extension files in the project's LUFFA. If needed, you can define an assemble
block to configure which build and project files to include. Then, during the Gradle build, the specified files are placed into a build/liferay-client-extension-build/
folder, which Gradle then adds to the project's LUFFA.
The assemble
block is a YAML array that can include multiple instructions, though each set of instructions generally follows this pattern:
See Assembling Client Extensions for more information about these properties.
Client Extension Definitions
In the client-extension.yaml
file, you must separate client extension definitions into separate sections introduced by a unique ID. This ID should follow a hyphenated naming pattern (e.g., liferay-sample-batch-example
). For each definition, you must set the client extension's name
and type
properties. The name
value identifies the client extension in the Liferay UI, while the type
value determines how Liferay handles the client extension when it's deployed.
Depending on the client extension's type, you may need to define additional properties. For example, when defining a theme favicon client extension, you must also set the url
property to the resource's path:
For Liferay Cloud deployments, you can also specify the target virtual instance using the dxp.lxc.liferay.com.virtualInstanceId
property. Learn about additional properties in the Mastering Backend Client Extensions and Mastering Frontend Client Extensions courses.
Building Client Extensions
To build and deploy a client extension project, you can navigate to the project's folder in your terminal and execute the workspace's Gradle Wrapper deploy
command (e.g., blade gw deploy
). This executes the Gradle build task that produces a deployable LUFFA. Each LUFFA has a particular structure and includes component files. By default, this includes all project files, but you can use the project's assemble
block to specify which files to include.
Generally, LUFFAs follow this structure:
See Packaging Client Extensions for more information about the LUFFA's structure.
Grouping Different Types of Client Extensions
Each client extension project can include multiple extensions. However, there are some restrictions on which types of client extensions you can group in the same project. This is because some types have unique deployment and runtime requirements that would conflict if combined.
You can group these types:
Type | Batch | Frontend | Microservice | Configuration |
---|---|---|---|---|
Batch | ✔ | ✔ | ||
Frontend | ✔ | ✔ | ||
Microservice | ✔ | ✔ | ||
Configuration | ✔ | ✔ | ✔ | ✔ |
All client extensions in a project are associated with a Docker container that represents a workload tailored to that project. This container is defined by the project's Dockerfile. Consequently, only certain kinds of client extensions are compatible for grouping.
Liferay Sample Workspace
Liferay offers a comprehensive collection of sample projects to fast-track your client extension development. You can find the sample workspace in Liferay's GitHub repository here. The README
includes short descriptions of each sample project, along with Liferay's naming conventions for client extensions.
To begin working on a client extension, Liferay recommends using one of the provided sample projects as a starting point. First, clone the sample workspace from GitHub to your machine. You can do this through GitHub's UI or by running the following command in your command line:
Once you've cloned the sample workspace, you can copy the appropriate client extension project over to the client-extensions
folder in your local Liferay workspace. Then, in the client-extension.yaml
file, you can update the identifier fields that are relevant to your project.
Conclusion
Client extensions follow a structured project model that lives inside your Liferay workspace. The sample workspace contains client extension projects that you can use as templates or starting points for your custom applications. Next, you'll learn more about how the client extension model departs from the traditional OSGi plugin approach.
Capabilities
Product
Education
Contact Us