Creating Your First Liferay Portlet

Step-by-Step Guide for Beginners (Liferay 7.x)

Introduction

If you are new to Liferay DXP, the very first real development milestone is:

❓ How do I create my first Liferay Portlet?

A Portlet is the core UI building block of Liferay.
Everything you see in a Liferay portal page is rendered by one or more portlets.

In this blog, you will learn:

• What a portlet really is

• The tools you need

• How to create a Hello World portlet

• How the portlet lifecycle works

• How to deploy and test it

• Common beginner mistakes

---

What Is a Liferay Portlet?

A Portlet is a modular Java UI component that:

• Runs inside the Liferay portal

• Renders part of a page

• Handles user actions

• Talks to services and APIs

• Is deployed as an OSGi module

Examples:

• Approval dashboard

• Task inbox

• Data entry form

• Reports view

• Workflow UI

👉 Think of a portlet as a mini web application inside the portal.

---

Prerequisites

Before you start:

✔ Java 11 or 17
✔ Liferay 7.3 or 7.4
✔ Liferay Workspace (recommended)
✔ Gradle (bundled with workspace)
✔ IDE: IntelliJ / Eclipse

---

Step 1 – Create a Liferay Workspace

Liferay Workspace is the recommended project structure.

blade init liferay-workspace
cd liferay-workspace

This creates:

liferay-workspace/
 ├── modules/
 ├── themes/
 ├── wars/
 └── build.gradle

---

Step 2 – Generate a New Portlet Module

Use Blade CLI:

blade create -t mvc-portlet -p com.example.hello hello-portlet

This creates:

modules/hello-portlet/
 ├── src/main/java/
 ├── src/main/resources/
 ├── bnd.bnd
 └── build.gradle

---

Step 3 – Understand the Portlet Class

Open the generated Java class:

@Component(
    immediate = true,
    property = {
        "com.liferay.portlet.display-category=category.sample",
        "com.liferay.portlet.instanceable=true",
        "javax.portlet.display-name=Hello Portlet",
        "javax.portlet.init-param.template-path=/",
        "javax.portlet.init-param.view-template=/view.jsp",
        "javax.portlet.name=hello_portlet",
        "javax.portlet.resource-bundle=content.Language",
        "javax.portlet.security-role-ref=power-user,user"
    },
    service = Portlet.class
)
public class HelloPortlet extends MVCPortlet {
}

What this means

• @Component → Registers this class as an OSGi portlet

• MVCPortlet → Default Liferay MVC framework

• view.jsp → UI template

• display-category → Where it appears in UI

---

Step 4 – Create the UI (view.jsp)

Edit:

src/main/resources/META-INF/resources/view.jsp

<%@ taglib uri="http://liferay.com/tld/theme" prefix="liferay-theme" %>
<%@ taglib uri="http://java.sun.com/portlet_2_0" prefix="portlet" %>

<h2>Hello Liferay Portlet!</h2>

<p>Welcome to your first Liferay Portlet.</p>

---

Step 5 – Build and Deploy the Portlet

From workspace root:

./gradlew deploy

If Liferay is running, you should see:

STARTED hello-portlet

---

Step 6 – Add the Portlet to a Page

1. Login to Liferay

2. Go to a page

3. Click Add → Widgets

4. Find Hello Portlet

5. Drag it onto the page

🎉 You just created your first Liferay Portlet.

---

Understanding the Portlet Lifecycle

A portlet goes through:

init() → render() → processAction() → destroy()

In Liferay MVC:

• doView() → Render UI

• processAction() → Handle form submits

• serveResource() → AJAX calls

---

Step 7 – Add an Action Method

Update your portlet class:

public class HelloPortlet extends MVCPortlet {

    public void submitForm(ActionRequest request, ActionResponse response) {

        String name = ParamUtil.getString(request, "name");

        request.setAttribute("name", name);
    }
}

Update view.jsp:

<portlet:actionURL name="submitForm" var="submitUrl" />

<form action="${submitUrl}" method="post">
    <input type="text" name="name" placeholder="Enter your name" />
    <button type="submit">Submit</button>
</form>

<c:if test="${not empty name}">
    <p>Hello ${name}!</p>
</c:if>

---

How Portlets Integrate with BPM & APIs

In real projects, portlets:

• Call Spring Boot APIs

• Trigger BPM processes (Camunda / jBPM)

• Display workflow tasks

• Show business dashboards

Example:

restTemplate.postForObject(
    "http://localhost:8080/start-process",
    payload,
    Void.class
);

---

Common Beginner Mistakes 🚨

❌ Putting heavy business logic inside the portlet
❌ Tight DB coupling
❌ Ignoring OSGi dependencies
❌ Hardcoding URLs
❌ No error handling
❌ No logging

---

Best Practices (Production-Proven)

✔ Keep portlets thin (UI only)
✔ Move business logic to Spring Boot
✔ Use REST APIs
✔ Externalize configs
✔ Use headless APIs
✔ Add logging & monitoring

---

Interview Question (Very Common)

Q: What is a Liferay Portlet?
A: A modular Java UI component deployed as an OSGi bundle inside the Liferay portal.

---

Final Takeaway

❗ A Liferay Portlet is not just a JSP.
❗ It is a full OSGi module with lifecycle, services, and UI.

Once you understand how to build a basic portlet, you can:

• Build workflow dashboards

• Create approval portals

• Integrate BPM engines

• Build enterprise UI

💼 Professional Support Available

If you are facing issues in real projects related to enterprise backend development or workflow automation, I provide paid consulting, production debugging, project support, and focused trainings.

Technologies covered include Java, Spring Boot, PL/SQL, Azure, CMS and workflow automation (jBPM, Camunda BPM, RHPAM).

📧 Contact: ishikhanirankari@gmail.com | info@realtechnologiesindia.com

🌐 Website: IT Trainings | Digital metal podium