예제를 통해 알아보는 XE Addon 개발하기

이번에는 "실시간 새글 및 댓글 알림 애드온 HelloMaster v4.0" 을 분석하여 Addon의 실행과정을 알아본다. 이전에 모듈에 대한 글에서 언급했는지는 기억이 안나지만, 애드온은 "특정 프로시져가 실행되는 위치에 추가로 삽입되는 코드"라고 생각하면 쉽다. 일종의 include()라고 할까. 물론 제약사항도 어느정도 있지만 약간의 트릭?으로 해결이 가능하며 이에 대해서는 나중에 다루기로 하고, 우선 HelloMaster소스를 분석해 보기로 한다.

해당 압축파일을 받으면 hellomaster라는 폴더 아래에 hellomaster.addon.php라는 파일과, conf/info.xml 파일을 볼 수 있다. conf/info.xml파일에는 애드온의 정보와 추가적인 변수를 설정해 줄 수 있으며, addon.php파일은 말그대로 원하는 기능을 담는 소스를 의미한다. 우선 conf/info.xml을 보자.

* conf/info.xml

<?xml version="1.0" encoding="utf-8" ?>

   <addon version="0.2.1">

  <title xml:lang="ko">캐릭터 개인비서 HelloMaster 실시간 알림 애드온</title>

   <author email_address="kawon@paran.com" link="http://www.funion.net" date="2009. 7. 01">

     <name xml:lang="ko">HelloMaster 개발팀</name>

     <description xml:lang="ko">게시판에 글 등록시 : 관리자의 HelloMaster 개인비서에게 실시간 알림 메세지 전송 댓글 등록시 : 작성자의 HelloMaster 개인비서에게 실시간 알림 메세지 전송 사용방법 1. http://www.funion.net에서 HelloMaster 설치프로그램을 다운로드 받아 설치 2. 사용자 등록 : 회원가입(zbxe)시 등록한 메일주소와 동일한 메일주소를 입력하셔야 식별이 가능하므로 유의 바랍니다.</description>

</author>

   <extra_vars>

   <var name="admin_mail">

       <title xml:lang="ko">관리자 메일주소</title>

       <description xml:lang="ko">HelloMaster 사용자등록시 등록한 메일주소를 입력하세요. 복수의 전체 관리자를 등록할경우 쉼표(,)로 구분해서 입력하세요. 게시판마다 담당자가 있을경우 게시판아이디:이메일주소로 입력하세요. 예) aaa@naver.com, freeboard:bbb@daum.net, notice:ccc@naver.com, ddd@paran.com</description>

  </var>
</extra_vars>

</addon>

중요한 부분은 <extra_vars>의 <var>아래 부분이다. 관리자의 메일주소를 관리자 페이지에서 입력하면 이 값은 admin_mail이라는 변수로 등록되어 애드온에서 사용될 수 있다. 아래의 애드온 관리자 페이지 화면을 보면 이해가 쉽게 될 것이다.

[그림 1] 애드온 관리자 페이지.

다음으로는 핵심 코드인 hellomaster.addon.php를 살펴본다. 뒷부분은 프로그램 실행코드이며 애드온과는 큰 상관이 없기 때문에 생략한다.

hellomaster.addon.php

<?php
    /**
     * @author 퍼니온 개발팀 (kawon@paran.com)
     * @brief 게시판에 글 등록시 : 관리자의 개인비서에게 실시간 알림 메세지 전송
     *        댓글 등록시 : 작성자의 개인비서에게 실시간 알림 메세지 전송
     **/  
    if(!defined("__ZBXE__")) exit();    //만약 모듈이 XE를 통하지 않고 개별적으로 호출될 때 exit()로 탈출한다.
    if(
        ($this->act == 'procBoardInsertDocument' ||  //게시판에서 게시물을 등록할 경우
        $this->act == 'procBoardInsertComment' ||   //게시판에서 댓글을 달경우.
        $this->act == 'procKinInsert' || //지식인이라는 모듈에서 지식이 등록되었을 경우? 보통은 사용되지 않는다.
        $this->act == 'procKinInsertReply' )    //마찬가지로 지식인 모듈에서 덧글이 달릴경우. 
        && $called_position == 'after_module_proc'){ //모듈 객체의 실행 method가 실행된 후에 호출하겠다.

        if(!$addon_info->mid_list) $selected = true;    //"특정 모듈에서 애드온 사용" 옵션을 지정하지 않았을 경우.
        else {
            $selected = false;  //우선 현재 호출된 모듈에서는 애드온이 사용되지 않는다는 가정을 하고..
            foreach($addon_info->mid_list as $val){     //관리자 페이지에서 지정한 모듈들을 불러온다
                if(trim($val) == $this->mid){   //만약 현재 실행되는 모듈과 관리자가 지정한 모듈이 같을경우
                    $selected = true;   //현재 모듈에서는 이 애드온을 사용할 수 있다.
                    break;  //더이상 관리자가 지정한 모듈을 검색할 필요가 없으므로 루프에서 나간다.
                }
            }
        }

        if($selected){
            $admin_mail = $addon_info->admin_mail;  //관리자 페이지에서 '관리자 메일주소'로 표기된 변수.
            $admin_mail_list = explode(',', $admin_mail);   //쉼표로 구분되므로 쉼표를 기준으로 문자열을 분리한다.

어머 벌써 끝이네. 이대로 끝마치기는 너무 아쉬우므로 공식 위키에 있는 모듈 호출 시점에 대한 글을 첨부해본다.

* 애드온 호출시 전달 변수

호출 시점이 4군데마다 전달되는 변수가 각각 다른 것들이 있고 공통적인 것이 있습니다. 전달변수는 다음과 같습니다.

• 공통 전달 변수

  • $called_position
    어느 시점에서 호출되는지에 대한 정보가 있습니다.
    before_module_init, before_module_proc, after_module_proc, before_display_content 4개의 값중 하나를 가지게 됩니다.
  • $addon_path
    호출된 애드온의 경로를 담고 있습니다.
  • $addon_info
    XE의 애드온들은 각각 독자적인 설정과 애드온이 동작하기를 원하는 대상 모듈을 지정할 수 있습니다.
    이 정보들이 $addon_info 변수를 통해서 전달됩니다.

• $called_position = before_module_init
  before_module_init 호출은 ModuleHandler::__construct() 에서 호출이 됩니다.
  ModuleHandler Class의 native code와 같이 동작하게 되고 이 시점에서는 아래와 같은 변수가 등록이 됩니다.
  다만 아래 값들은 Context::get() 을 통해 request argument의 변수들을 설정한 것일 뿐 검증된 것은 아닙니다.
  blogAPI라는 애드온은 $this->act == 'blogAPI' 일 경우 동작하는 애드온이며 이와 같이 XE가 동작하기 전의 시점에 무언가를 설정하는 시점으로 이해하시면 됩니다.

  • $this->module : 요청된 $module 변수값
  • $this->mid : 요청된 $mid 변수값
  • $this->act : 요청된 $act 값
  • $this->document_srl : 요청된 문서 고유 번호
  • $this->module_srl : 요청된 모듈 고유 번호
• $called_position = before_module_proc
  ModuleObject::proc() 즉 요청에 의해 생성된 모듈 객체의 실행 method가 동작하기 전에 호출이 됩니다.
  요청되어 생성된 모듈 객체의 모든 변수를 사용할 수 있습니다.
  $this 지시자를 통해서 애드온 내에서는 모듈의 일부로서 기능을 수행할 수 있습니다.
• $called_position = after_module_proc
  ModuleObject::proc() 즉 요청에 의해 생성된 모듈 객체의 실행 method가 실행된 후에 호출이 됩니다.
  before_module_proc와 마찬가지로 요청에 의해 생성된 모듈 객체의 모든 변수가 사용 가능합니다.
  다만 $output 이라는 변수를 통해서 모듈의 동작 성공 유무를 파악할 수 있습니다.

• $called_position = before_display_content
  모든 처리가 끝난 후 결과값을 출력하기 바로 직전인 DisplayHandler::printContent()에서 호출됩니다.
  일반적으로 이 시점은 HTML/JSON/XMLRPC 출력 직전이며 출력 직전에 HTML/JSON/XMLRPC 의 변조를 하기 위할때 사용할 수 있습니다.
  예를 들어 회원들의 포인트에 따른 레벨 아이콘등을 결과물에 추가할 수 있습니다.

  • $oModule : 요청되어 생성된 모듈의 객체
  • $output : 출력하려는 HTML/JSON/XMLRPC 결과물

이와 같이 XE의 애드온은 요청되는 시점에 따라서 직접 변수를 조작하거나 참조 할 수 있는 기능을 가지고 있습니다.

참고 : http://xe.xpressengine.net/18180622 (03. 애드온 개발하기)