Liferay Portal 첫 포틀릿 개발 완전 가이드: Hello World부터 배포까지

Liferay 포털에서 첫 포틀릿을 개발하고 배포하는 방법을 단계별로 알려드립니다. 초보자도 따라할 수 있는 가장 간단한 예제를 알아보겠습니다.

---

개발 환경 준비

Liferay 포틀릿 개발을 위해 아래 3가지 필수 도구를 설치합니다:

필수 설치 항목

JDK 11: Oracle 공식 사이트에서 다운로드하여 설치합니다. Liferay 7.4는 Java 11을 권장하며, 환경 변수 설정도 함께 진행해야 합니다.

Liferay DXP 7.4: Liferay 공식 홈페이지에서 무료 커뮤니티 에디션을 다운로드합니다. 압축 해제 후 tomcat-9.0.x/bin/startup.sh (Linux/Mac) 또는 startup.bat (Windows)로 실행합니다.

Blade CLI: 터미널에서 npm install -g blade-cli 명령어로 설치합니다. 이는 Liferay 개발을 위한 공식 명령줄 도구입니다.

서버 실행 확인

Liferay 서버는 localhost:8080에서 실행되며, 초기 설정 완료 후 관리자 계정으로 로그인할 수 있습니다.

---

Liferay 워크스페이스 생성

모든 프로젝트는 워크스페이스 내에서 관리됩니다. 워크스페이스는 여러 모듈을 포함할 수 있는 상위 프로젝트 구조입니다.

# 터미널에서 실행
blade init -v 7.4 hello-world-workspace
cd hello-world-workspace

이 명령어는 Liferay 7.4 버전에 맞는 워크스페이스를 생성하고, 필요한 Gradle 설정과 폴더 구조를 자동으로 만들어줍니다.

---

Hello World 포틀릿 프로젝트 생성

Blade CLI로 MVC 포틀릿 템플릿을 사용하여 기본 포틀릿을 생성합니다:

blade create -t mvc-portlet -p com.example.hello -c HelloWorldPortlet hello-world-portlet

생성된 파일 구조

hello-world-portlet
├── src
│   └── main
│       ├── java/com/example/hello
│       │   └── HelloWorldPortlet.java
│       └── resources/META-INF/resources
│           ├── init.jsp
│           └── view.jsp
├── build.gradle
└── bnd.bnd

주요 파일 설명

• HelloWorldPortlet.java: 포틀릿의 메인 컨트롤러 클래스
• view.jsp: 사용자에게 보여질 화면 템플릿
• init.jsp: 공통 태그 라이브러리와 변수 선언
• bnd.bnd: OSGi 번들 설정 파일

---

포틀릿 코드 커스터마이징

HelloWorldPortlet.java 확인

생성된 Java 파일의 기본 구조를 확인해보겠습니다:

@Component(
    immediate = true,
    property = {
        "com.liferay.portlet.display-category=category.sample",
        "javax.portlet.display-name=Hello World Portlet",
        "javax.portlet.init-param.template-path=/",
        "javax.portlet.init-param.view-template=/view.jsp",
        "javax.portlet.name=" + HelloWorldPortletKeys.HELLO_WORLD,
        "javax.portlet.resource-bundle=content.Language",
        "javax.portlet.security-role-ref=power-user,user"
    },
    service = Portlet.class
)
public class HelloWorldPortlet extends MVCPortlet {
    // 기본 MVC 포틀릿 기능 상속
}

화면 커스터마이징

view.jsp 파일을 열어 메시지를 수정합니다:

<%@ include file="/init.jsp" %>

<div class="hello-world-portlet">
    <h1>Hello Liferay World!</h1>
    <p>나의 첫 포틀릿이 성공적으로 배포되었습니다.</p>
    <p>현재 시간: <%= new java.util.Date() %></p>
    
    <div class="alert alert-info">
        <strong>축하합니다!</strong> Liferay 포틀릿 개발의 첫걸음을 성공했습니다.
    </div>
</div>

<style>
.hello-world-portlet {
    padding: 20px;
    border-radius: 8px;
    background-color: #f8f9fa;
}

.hello-world-portlet h1 {
    color: #0066cc;
    margin-bottom: 15px;
}
</style>

---

포틀릿 빌드 및 배포

프로젝트 빌드

프로젝트 폴더에서 아래 명령어를 실행합니다:

# hello-world-portlet 폴더에서 실행
blade deploy

또는 Gradle을 직접 사용할 수도 있습니다:

./gradlew deploy

배포 성공 확인

콘솔에서 다음과 같은 메시지를 확인할 수 있습니다:

[INFO] hello-world-portlet-1.0.0.jar 배포 완료
[INFO] 총 1개 포틀릿 사용 가능
[INFO] Bundle hello-world-portlet_1.0.0 [XXX] started

---

포틀릿 페이지 추가

관리자 인터페이스 접근

1. 브라우저에서 http://localhost:8080 접속
2. 관리자 계정으로 로그인
3. 상단 추가(+) 버튼 클릭

포틀릿 배치

1. 응용 프로그램 → 샘플 카테고리 선택
2. Hello World Portlet 찾기
3. 원하는 위치에 드래그 앤 드롭
4. 저장 버튼 클릭

결과 확인

페이지에 커스터마이징한 메시지와 스타일이 적용된 포틀릿이 표시됩니다.

---

고급 기능 추가

폼 처리 기능 추가

사용자 입력을 받는 간단한 폼을 추가해보겠습니다:

<%@ include file="/init.jsp" %>

<portlet:actionURL name="processForm" var="processFormURL" />

<div class="hello-world-portlet">
    <h1>Hello Liferay World!</h1>
    
    <aui:form action="<%= processFormURL %>" method="post">
        <aui:input name="userName" label="이름을 입력하세요" required="true" />
        <aui:button type="submit" value="인사하기" />
    </aui:form>
    
    <c:if test="<%= Validator.isNotNull(renderRequest.getAttribute('greeting')) %>">
        <div class="alert alert-success">
            <%= renderRequest.getAttribute("greeting") %>
        </div>
    </c:if>
</div>

액션 메서드 추가

HelloWorldPortlet.java에 폼 처리 메서드를 추가합니다:

@ProcessAction(name = "processForm")
public void processForm(ActionRequest actionRequest, ActionResponse actionResponse) {
    String userName = ParamUtil.getString(actionRequest, "userName");
    String greeting = "안녕하세요, " + userName + "님! Liferay에 오신 것을 환영합니다.";

    actionRequest.setAttribute("greeting", greeting);
    actionResponse.setRenderParameter("greeting", greeting);
}

---

문제 해결 가이드

일반적인 문제와 해결책

증상	원인	해결책
배포 실패	빌드 캐시 문제	blade gw clean 후 재배포
화면 미노출	브라우저 캐시	브라우저 캐시 삭제 → 새로고침
클래스 로드 오류	OSGi 번들 충돌	Liferay 서버 재시작
포틀릿 목록에 없음	카테고리 설정 오류	bnd.bnd 파일의 카테고리 확인

디버깅 팁

로그 확인: Liferay 서버 콘솔에서 오류 메시지를 확인합니다.

Gogo Shell 사용: telnet localhost 11311로 OSGi 콘솔에 접속하여 번들 상태를 확인할 수 있습니다.

개발자 도구: 브라우저의 개발자 도구를 사용하여 JavaScript 오류나 네트워크 문제를 진단합니다.

---

다음 단계 및 확장 방향

추가 학습 주제

Service Builder: 데이터베이스 연동을 위한 서비스 레이어 생성
REST API 구현: 외부 시스템과의 데이터 교환을 위한 RESTful 서비스 개발
테마 개발: 포털 전체의 디자인과 레이아웃 커스터마이징
워크플로우 통합: 승인 프로세스와 비즈니스 로직 구현

실무 활용 예시

게시판 포틀릿: CRUD 기능을 포함한 완전한 게시판 시스템
대시보드 포틀릿: 차트와 그래프를 활용한 데이터 시각화
사용자 관리 포틀릿: 권한 관리와 사용자 프로필 기능

---

마무리

이제 여러분은 Liferay 포틀릿 개발의 첫걸음을 떼었습니다. 다음 단계는 폼 추가, 데이터베이스 연동, REST API 구현으로 확장해보세요.
Liferay의 강력한 OSGi 모듈 시스템과 Spring Framework 통합을 활용하면 전문가 수준의 엔터프라이즈 포털을 구축할 수 있습니다. 지속적인 학습과 실습을 통해 더욱 복잡하고 실용적인 포틀릿을 개발해보시기 바랍니다.