misol's XE

간단한 XpressEngine(XE) 애드온 만들기 - 1/2
http://xe.imsoo.net/1
이 글은 간단한 XpressEngine(XE) 애드온 만들기 시리즈의 2번째 글입니다. 애드온 정보파일에 관련된 내용을 보시고 싶으시면 링크된 글을 읽어주시기 바랍니다.

이제!! 2번째 글을 시작합니다. 두번째 글은 간단히 끝내려 합니다. 왜냐?! PHP파일의 기본적인 규칙을 따르고 있는 것 이외에 설명 드릴 수 있는 부분은 많지 않기 때문입니다. 만드는 목적에 따라서 알아야 하는 상황이 너무 다양합니다. 이 글에서는 그래서, 많은 애드온들에서 공통적으로 필요한 내용에 대해서만 설명합니다.

• 애드온 실행파일(PHP)에서 알아야 할 것들
• 실행 순서 $called_position
• 파일 인코딩
• 파일 이름
• 알아두면 좋은 것들
• if(!defined("__ZBXE__")) exit();
• 요청 방식 구분하기 Context::getResponseMethod()
• XE Core의 많은 변수들을 주고 받게 해주는 Context::get()과 Context::set()
• Context::get()
• Context::set()
• before_display_content 에서 $output
• debugPrint()
• ./config/config.inc.php
• 참고하면 좋은 파일들

애드온 실행파일(PHP)에서 알아야 할 것들

실행 순서 $called_position

애드온은 XE Core가 모듈을 실행하는 여러단계 사이사이에 실행됩니다. 현재 4군데에서 실행되는데 $called_position이라는 변수에 어디서 실행되는 것인지 정보가 담겨 있습니다. $called_position는 네가지 값을 가집니다. 그 네가지 값은 아래와 같습니다.

• before_module_init
• before_module_proc
• after_module_proc
• before_display_content

실행하려는 코드가 어디서 실행되어야 하는지 목적에 맞게 이용하시면 됩니다. 예를 들어서 모듈이 로드되고 실행은 되기 전에 애드온 코드가 실행되어야 겠다고 생각하시면 $called_position == 'before_module_proc' 인 순간을 캐치하시면 되고, 모듈 실행이 완료되고 템플릿 코드가 실행된 이후, 레이아웃이 씌어지기 직전에 실행되어야 한다고 생각하시면 $called_position == 'before_display_content'를 선택하세요.

물론, 꼼수(XE Core가 업데이트 되면 실행을 보장할 수는 없습니다.)를 조금 부리면, XE Core구조상 약간은 변칙적인 방법으로 애드온 실행 위치를 바꾸어 끼워넣을 수 있습니다만, 이 글에서는 다루지 않겠습니다.

if($called_position != 'before_display_content' || Context::getResponseMethod() != 'HTML') return;

위 코드와 같이 쓰게 되면, 위 코드 아래에 적힌 코드들은 before_display_content에서만 실행됩니다. 그리고 HTML모드로 실행되고 있는 경우에만 코드가 실행되는데, 이 부분을 이제 다루어 보도록 합시다.

파일 인코딩

파일 인코딩은 UTF-8로 저장하셔야 합니다.

그런데!! UTF-8로 저장을 했는데, 오류가 나는 경우가 있습니다. 이는 대부분 BOM(Byte Order Mark)가 파일에 입력되었기 때문입니다. 인터넷에 'UTF-8 BOM'으로 검색해 보시면 해결책을 많이 얻으실 수 있습니다. 참고하시기 바랍니다.

구글의 검색 결과
http://tln.kr/5n3dp
검색어는 'PHP UTF-8 BOM 코드'를 입력하였습니다.

네이버의 검색 결과
http://tln.kr/5n3du

파일 이름

PHP 파일의 이름은 정해진 형식에 맞추어져야 합니다. 그렇지 않으면 실행이 안되어요 ㅠ;;

만약 애드온 디렉토리 명이 abc라면 PHP 파일 이름이 abc.addon.php여야 실행이 됩니다.
정리하면, ./addons/abc/abc.addon.php 와 같은 위치에 파일이 위치하겠지요.

알아두면 좋은 것들

if(!defined("__ZBXE__")) exit();

애드온 실행파일 맨 앞에 써주면 좋습니다. 혹시나, 애드온 파일이 위치한 곳으로 직접 접속하더라도, XE를 통한 실행이 아니면, 실행되지 않도록 합니다.

요청 방식 구분하기 Context::getResponseMethod()

애드온만의 실행 조건으로 XE가 배려하고 있는 것은 사실 called position이 유일합니다. 그렇지만,  Context::getResponseMethod()도 자주 쓰이니 알아두도록 합시다.

 Context::getResponseMethod()은 XE 실행 중에 값이 바뀌어서 다른 값을 반환하기도 하지만, 세가지 값 중 하나를 가지는 것이 기본입니다. 그 세가지 값은 아래와 같습니다.

• HTML
• XMLRPC
• JSON

눈치가 빠르시면 대충 감이 오실 것입니다. HTML이 일반적으로 사람이 보게되는 페이지입니다. HTML 규격으로 출력이 되지요. 일반적으로 브라우저가 어떻게 요청을 보내냐에 따라서 처음 결정이 된 값이 XE Core의 판단에도 바뀌지 않으면 그 값을 유지하는 것 같습니다. 그렇지만, XE Core 판단에 따라 중간에 값이 바뀌기도 합니다. 어떤 상황에 애드온이 동작할 것인지 스스로 판단하여 적절한 값을 확인하도록 합시다~!

XMLRPC는 XML규격으로 출력되는 모든 페이지가 가지는 규격입니다. 다만, RSS와 ATOM 페이지의 경우에도 XMLRPC를 가지지만, 제 기억에 모듈 실행 전 후로 HTML이었다가 XMLRPC로 바뀌는 것으로 아는데, 자세한 것은, 만드시는 분이 확인하셔야 합니다.

JSON은 JSON으로 응답할때 갖고 있는 값입니다.

XE Core의 많은 변수들을 주고 받게 해주는 Context::get()과 Context::set()

애드온은 모듈이 실행되는 중간에 끼어서 변수를 조작하는 것이 주 목적입니다. 그러려면, XE내에서 변수를 주로 어떻게 불러오는지, 어떻게 설정하는지 알아야겠지요? ^^

이미 함수 이름에서 분위기가 팍팍 풍기고 있습니다. 네! Context::get()은 변수에 할당된 값을 가져오는 함수이고 Context::set()은 변수에 값을 설정하는 함수입니다.

Context::get()

Context::get('변수명') 이런 식으로 씁니다. 이런 식으로 많은 변수들을 불러올 수 있는데, post나 get방식으로 전달된 변수들도 이렇게 불러올 수 있습니다.

자주 쓰이는 변수로 mid와 document_srl이 있는데, Context::get('mid'), Context::('document_srl')과 같은 식으로 불러옵니다.

Context::set()

Context::set('변수명', 값) 이런 식으로 씁니다. 예를 들어서 $data 라는 변수에 어떤 값이 있고 이를 xe_data라는 변수에 넣고 싶다면, Context::set('xe_data', $data);라고 쓰면 됩니다.

before_display_content 에서 $output

$called_position이 4가지 값을 가지고, XE가 한회 요청으로 실행되는 동안 4번 애드온이 실행된다고 앞에 말씀 드렸습니다. 그런데 이 네번 중에 가장 마지막이 before_display_content입니다. 모듈 처리가 완료되고 레이아웃 씌우기 직전이지요. 이때 $output이라는 데이터를 자주 이용하게 됩니다. $output은 모듈이 처리하고 이제 막 출력될 데이터를 가지고 있습니다. 그래서 이 부분을 많이 가공하게 됩니다.
어떤 값을 가지고 있는지 관심 갖고 지켜봐주세요 ^^;

debugPrint()

debugPrint()는 적절히 이용하면 편리합니다. 확인해보고 싶은 값이 있다면, debugPrint($sth)과 같은 식으로 쓰기만 하면 됩니다.

이렇게 쓴 값을 확인하고, debugPrint가 값을 출력하도록 설정하기 위해서는 한가지 선행 작업이 필요합니다.

./config/config.inc.php

./config/config.inc.php 는 XE의 기본 환경 설정을 해주는 파일입니다. 이 파일 내용을 잘 읽어보면,

if(!defined('__DEBUG__')) define('__DEBUG__', 0);
부분과

if(!defined('__DEBUG_OUTPUT__')) define('__DEBUG_OUTPUT__', 0);
부분, 등 __DEBUG라는 머릿말을 가진, 전역변수 선언 부분이 상당히 많습니다. 주석을 잘 읽어보시고 원하는 값으로 설정하시면, debugPrint 함수를 유용하게 쓰실 수 있을 겁니다.

그리고 마지막으로, debugPrint 함수는, 배포 전에 모두 제거합시다. 크지는 않지만, 속도를 잡아먹는답니다 ^^;;

참고하면 좋은 파일들

config.inc.php파일을 열어보셨으면 아시겠지만, XE는 로딩 되기만 하면, class파일들을 많이 불러옵니다. 가능하면 이 파일 내용들을 알아서, 이 파일안에 있는 유용한 함수(메소드? 뭐라고 부르던)를 잘 쓰도록 합시다.
개인적으로 Context클래스와, Display 클래스, FileHandler 클래스를 많이 참조하게 되더군요.
또 기본적으로 불러오는 함수 파일에 ./config/func.inc.php 가 있습니다. 문자열 자르는 함수와 해킹 차단 관련 함수들이 모여있습니다. 여러 잡다구리한 함수도 많으니 관심 있으시면 한번 구경해보세요 ^^;; 호환성을 위한 함수들도 있는데, 이 부분은 잘 안쓰게 되더군요... ^^;;

그 외에 PHP 외부 자바스크립트나 CSS등에서는 jQuery를 이용하시고 x.js는 이용하지 않기를 바랍니다. x.js는 XE 초기에 jQuery를 도입하기 전 jQuery가 이렇게 자랄줄 몰랐을때(???) 도입된 스크립트 입니다. 차츰 비중을 줄이고 제거할 것으로 보입니다. 현재 호환성 차원에서 지원하고 있는 것으로 보이니 x.js는 이용하지 마시기 바랍니다.
CSS는 제가 적극적으로 이용하지 않아서 잘 모르겠군요 ^^;;