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

Login to Liferay
Go to a page
Click Add → Widgets
Find Hello Portlet
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-services.html

📩 Email: ishikhanirankari@gmail.com | info@realtechnologiesindia.com
🌐 IT Trainings | Digital metal podium

✔ Available for quick consulting calls and project-based support
✔ Response within 24 hours

🎥 Learn IT with Shikha on YouTube

Prefer learning through videos? Watch practical tutorials on Kafka, Camunda, Alfresco, Java, Spring Boot, Microservices and Enterprise Architecture.

▶ Subscribe to Learn IT with Shikha on YouTube

Search This Blog

Learn IT with Shikha Blogs

Creating Your First Liferay Portlet