Foundations of Liferay Client Extensions

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.

Client extension projects reside in your Liferay workspace.

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:

  1. Assemble Block (optional): This section configures how the project is packaged during the build process.
  2. 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:

assemble:
  - from: [the folder containing files you want to copy into the LUFFA]
    include: [the file or glob match of files to include from the folder]
    into: [the folder into which the files are copied]
  - fromTask: [a Gradle task to execute before the assembly step]

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:

liferay-sample-theme-favicon:
    name: Liferay Sample Theme Favicon
    type: themeFavicon
    url: favicon.*.ico

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:

.
├── batch
│   └── **/*.batch-engine-data.json
├── *.client-extension-config.json
├── Dockerfile
├── LCP.json
├── static
│   └── **/*
├── WEB-INF
│   └── liferay-plugin-package.properties
└── [microservice resources]

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:

curl -o com.liferay.sample.workspace-latest.zip https://repository.liferay.com/nexus/service/local/artifact/maven/content\?r\=liferay-public-releases\&g\=com.liferay.workspace\&a\=com.liferay.sample.workspace\&\v\=LATEST\&p\=zip

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.

  • Anatomy of Client Extension YAML Files

  • Building Client Extensions

  • Grouping Different Types of Client Extensions

  • Liferay Sample Workspace

  • Conclusion

Loading Knowledge

Capabilities

Product

Education

Contact Us

Connect

Powered by Liferay
© 2024 Liferay Inc. All Rights Reserved • Privacy Policy