<h3>애드온 개발</h3>
<p>XpressEngine에서 애드온은 후킹, 즉 정상적인 동작을 가로채는 동작을 합니다.</p>
<p>php와 같은 인터프리터 언어에서 가능한 include를 이용하여 동작을 하는 구조입니다.</p>
<p>function이나 class로 애드온을 개발하지 않은 이유는 XE의 정상적인 Context에 native code처럼 끼어들 수 있게 하기 위한 것이였습니다.</p>
<p>이 덕분에 XE의 애드온은 호출 되는 시점에서 native code 처럼 강력하게 동작할 수 있습니다.</p>
<p>다만 매우 신중히 제작해야 전체 동작에 무리를 주지 않게 됩니다.</p>
<p> </p>
<h3>애드온의 호출 시점</h3>
<p>애드온 호출 시점은 다음 4군데입니다.</p>
<ul>
<li>
<p><span class="Apple-style-span" style="font-weight: bold;">before_module_init</span></p>
<ul>
<li>모듈 객체 생성 이전 : 사용자의 요청으로 필요한 모듈을 찾은후 모듈의 객체를 생성하기 이전을 의미합니다.</li>
</ul>
</li>
<li>
<p>before_module_proc</p>
<ul>
<li>모듈 실행 이전 : 모듈의 객체를 실행하고 모듈의 실행을 하기 이전을 의미합니다.</li>
</ul>
</li>
<li>
<p><span class="Apple-style-span" style="font-weight: bold;">after_module_proc</span></p>
<ul>
<li>모듈의 동작 이후 : 생성된 모듈 객체를 실행하고 결과를 얻은 바로 후를 의미합니다.</li>
</ul>
</li>
<li>
<p>before_display_content</p>
<ul>
<li>결과 출력 이전 : 모듈의 결과물과 레이아웃의 적용을 끝내고 출력하기 바로 이전을 의미합니다.</li>
</ul>
</li>
</ul>
<p> </p>
<h4>애드온 호출시 전달 변수</h4>
<p>호출 시점이 4군데마다 전달되는 변수가 각각 다른 것들이 있고 공통적인 것이 있습니다.</p>
<p>전달 변수는 다음과 같습니다.</p>
<ul>
<li>
<p><span class="Apple-style-span" style="font-weight: bold;">공통 전달 변수</span></p>
<ul>
<li>$called_position<br />
어느 시점에서 호출되는지에 대한 정보가 있습니다.<br />
before_module_init, before_module_proc, after_module_proc, before_display_content 4개의 값중 하나를 가지게 됩니다.</li>
<li><span class="Apple-style-span" style="font-weight: bold;">$addon_path</span><br />
호출된 애드온의 경로를 담고 있습니다.</li>
<li>$addon_info<br />
XE의 애드온들은 각각 독자적인 설정과 애드온이 동작하기를 원하는 대상 모듈을 지정할 수 있습니다.<br />
이 정보들이 $addon_info 변수를 통해서 전달됩니다.</li>
</ul>
</li>
<li>
<p><span class="Apple-style-span" style="font-weight: bold;">$called_position = before_module_init</span><br />
before_module_init 호출은 ModuleHandler::__construct() 에서 호출이 됩니다.<br />
ModuleHandler Class의 native code와 같이 동작하게 되고 이 시점에서는 아래와 같은 변수가 등록이 됩니다.<br />
다만 아래 값들은 Context::get() 을 통해 request argument의 변수들을 설정한 것일 뿐 검증된 것은 아닙니다.<br />
blogAPI라는 애드온은 $this->act == 'blogAPI' 일 경우 동작하는 애드온이며 이와 같이 XE가 동작하기 전의 시점에 무언가를 설정하는 시점으로 이해하시면 됩니다.</p>
<ul>
<li>$this->module : 요청된 $module 변수값</li>
<li>$this->mid : 요청된 $mid 변수값</li>
<li>$this->act : 요청된 $act 값</li>
<li>$this->document_srl : 요청된 문서 고유 번호</li>
<li>$this->module_srl : 요청된 모듈 고유 번호</li>
</ul>
</li>
<li>$called_position = before_module_proc<br />
ModuleObject::proc() 즉 요청에 의해 생성된 모듈 객체의 실행 method가 동작하기 전에 호출이 됩니다.<br />
요청되어 생성된 모듈 객체의 모든 변수를 사용할 수 있습니다.<br />
$this 지시자를 통해서 애드온 내에서는 모듈의 일부로서 기능을 수행할 수 있습니다.</li>
<li><span class="Apple-style-span" style="font-weight: bold;">$called_position = after_module_proc</span><br />
ModuleObject::proc() 즉 요청에 의해 생성된 모듈 객체의 실행 method가 실행된 후에 호출이 됩니다.<br />
before_module_proc와 마찬가지로 요청에 의해 생성된 모듈 객체의 모든 변수가 사용 가능합니다.<br />
다만 $output 이라는 변수를 통해서 모듈의 동작 성공 유무를 파악할 수 있습니다.</li>
<li>
<p>$called_position = before_display_content<br />
모든 처리가 끝난 후 결과값을 출력하기 바로 직전인 DisplayHandler::printContent()에서 호출됩니다.<br />
일반적으로 이 시점은 HTML/JSON/XMLRPC 출력 직전이며 출력 직전에 HTML/JSON/XMLRPC 의 변조를 하기 위할때 사용할 수 있습니다.<br />
예를 들어 회원들의 포인트에 따른 레벨 아이콘등을 결과물에 추가할 수 있습니다.</p>
<ul>
<li>$oModule : 요청되어 생성된 모듈의 객체</li>
<li>$output : 출력하려는 HTML/JSON/XMLRPC 결과물</li>
</ul>
</li>
</ul>
<p>이와 같이 XE의 애드온은 요청되는 시점에 따라서 직접 변수를 조작하거나 참조 할 수 있는 기능을 가지고 있습니다.</p>
<p> </p>
<h3>애드온의 제작 규칙</h3>
<p>애드온을 제작하기 위해서는 최소한 아래와 같은 규칙을 지켜야 합니다.</p>
<ul>
<li>위치 : addons/애드온이름</li>
<li>애드온 제작자 정보, 설명 그리고 필요에 따라 관리자로부터 애드온의 변수를 입력받기 위한 info.xml</li>
<li>애드온 동작 파일 : 애드온이름.addon.php</li>
</ul>
<p>위의 3가지를 꼭 지켜야 하며 각각에 대해서는 다시 상세히 설명하도록 하겠습니다.</p>
<p> </p>
<h3>애드온의 디렉토리 구조</h3>
<p><span class="Apple-style-span" style="font-weight: bold;">addons</span></p>
<ul class="arrowListType">
<li>
<p>애드온이름</p>
<ul>
<li>
<p><span class="Apple-style-span" style="font-weight: bold;">conf</span></p>
<ul class="pageListType">
<li>info.xml</li>
</ul>
</li>
</ul>
<ul class="pageListType">
<li><span class="Apple-style-span" style="font-weight: bold;">애드온이름.addon.php</span></li>
</ul>
<ul class="arrowListType">
<li>
<p>Queries</p>
<ul class="pageListType">
<li>queryID.xml</li>
</ul>
</li>
</ul>
</li>
</ul>
<p> </p>
<p>addons디렉토리에 다른 이름의 파일들이 있어도 상관없으며 class등을 사용하여도 됩니다.</p>
<p>다만 native code로 동작시키기 위해 include를 하는 구조라 function(함수)의 선언은 안됩니다.</p>
<p> </p>
<h3>info.xml 제작</h3>
<p>info.xml은 다음과 같이 제작할 수 있습니다.</p>
<ol class="code">
<li><?xml version="1.0" encoding="UTF-8"?></li>
<li><addon version="0.2"></li>
<li>
<p style="margin-left: 2em;"><title xml:lang="ko"><span class="Apple-style-span" style="font-weight: bold;">애드온제목</span></title></p>
</li>
<li>
<p style="margin-left: 2em;"><description xml:lang="ko">애드온에 대한 설명</description></p>
</li>
<li>
<p style="margin-left: 2em;"><version><span class="Apple-style-span" style="font-weight: bold;">애드온의 버전</span></version></p>
</li>
<li>
<p style="margin-left: 2em;"><date>년-월-일</date></p>
</li>
<li>
<p style="margin-left: 2em;"><author email_address="<span class="Apple-style-span" style="font-weight: bold;">제작자 메일 주소</span>" link="제작자 홈페이지 주소"></p>
</li>
<li>
<p style="margin-left: 4em;"><name xml:lang="ko"><span class="Apple-style-span" style="font-weight: bold;">제작자 이름</span></name></p>
</li>
<li>
<p style="margin-left: 2em;"></author></p>
</li>
<li>
<p style="margin-left: 2em;"><extra_vars></p>
</li>
<li>
<p style="margin-left: 4em;"><var name="설정 변수 명(영문)"></p>
</li>
<li>
<p style="margin-left: 6em;"><title xml:lang="ko"><span class="Apple-style-span" style="font-weight: bold;">설정 변수 이름(출력용)</span></title></p>
</li>
<li>
<p style="margin-left: 6em;"><description xml:lang="ko">설정 변수에 대한 설명</description></p>
</li>
<li>
<p style="margin-left: 4em;"></var></p>
</li>
<li>
<p style="margin-left: 2em;"></extra_vars></p>
</li>
<li></addon></li>
</ol>
<p> </p>
<p>extra_vars는 필요하면 생성하고 필요 없으면 <extra_vars /> 와 같이 세부 내역이 없어도 됩니다.</p>
<p>위의 파일을 info.xml 이라는 이름으로 저장하고 conf/info.xml 에 두시면 됩니다.</p>
<p> </p>
<h3>애드온이름.addon.php 제작</h3>
<p>동작하는 애드온 파일은 php로 작성하면 됩니다.</p>
<p>다만 애드온이 호출되는 위치가 대부분 class 객체의 method 내부이기에 함수 선언등은 할 수가 없습니다.</p>
<p>다만 class 를 정의하고 이를 활용하는 것은 가능합니다.</p>
<p>애드온 파일의 시작은 다음과 같이 합니다.</p>
<ol class="code">
<li> </li>
<li><?php</li>
<li>
<p style="margin-left: 2em;">/**</p>
</li>
<li>
<p style="margin-left: 2em;"> * @file 애드온이름.addon.php<br />
* @author 개발자이름 (개발자 이메일)<br />
* @brief 간단한 소개<br />
**/<br />
if(!defined('__ZBXE__')) exit();</p>
</li>
</ol>
<p> </p>
<p>__ZBXE__ 상수는 꼭 확인하여 XE를 통한 호출이 아닌 외부 요청에 의한 실행이 되지 않도록 하셔야 합니다.</p>
<p> </p>
<p>애드온은 called_position에 따라서 동작을 제어할 수 있고 이 제어는 애드온에서 직접 처리를 하여야 합니다.</p>
<p> </p>
<p>XE가 모듈을 찾기 전 최상단 시점에서만 동작하는 애드온을 작성하려면 $called_position = before_module_init 에서 실행하면 됩니다.</p>
<p>따라서 위의 코드 아래에 다음과 같은 코드를 넣으시면 됩니다.</p>
<p> </p>
<ol class="code">
<li>
<p style="margin-left: 2em;">if($called_position != 'before_module_init') return;</p>
</li>
</ol>
<p> </p>
<p>위와 같이 $called_position 값이 before_module_init이 아닐 경우 return 문을 통해서 그 아래의 코드가 실행되지 않도록 합니다.</p>
<p>native code처럼 동작하기에 return 이 아닌 다른 exit() 등의 함수가 사용되면 의도하지 않은 동작을 할 수 있으니 주의하셔야 합니다.</p>
<p> </p>
<p>위의 코드까지가 XE Addon 제작을 위한 준비 단계입니다.</p>
<p>이후 코드는 원하는 것을 동작 시키기 위한 코드를 직접 활용하시면 됩니다.</p>
<p> </p>
<h3>XE XML Query의 사용</h3>
<p>XE Addon에서도 XML Query를 이용하여 다른 모듈드에서 제작된 DB 정보를 활용할 수 있습니다.</p>
<p>이 경우 애드온 디렉토리에 queries 라는 하위 디렉토리를 만들고 xml query문이 정의된 xml 파일을 저장하면 됩니다.</p>
<p>이 경우 다음과 같은 코드로 쿼리를 실행할 수 있습니다.</p>
<p> </p>
<ol class="code">
<li>$output = executeQuery('addon.애드온이름.xml', $전달변수)</li>
</ol>
<p> </p>
<h3>애드온 제작시 주의 사항</h3>
<p>XE의 Addon은 매우 강력한 동작을 수행할 수 있습니다.</p>
<p>다만 상황에 맞게 코드를 잘 작성하지 않을 경우 의도하지 않는 결과 혹은 XE의 동작이 멈출 수가 있습니다.</p>
<p>기본으로 포함된 Addon들을 참고하시기를 권합니다.</p>