-
Notifications
You must be signed in to change notification settings - Fork 55
PluginConfig
플러그인이 동작할 때, 사용자에 따라 서로 다른 옵션으로 동작하게 만들고 싶을 때가 있습니다. 텍스트큐브의 플러그인 구조는 플러그인이 사용자의 다양한 선택에 따라 다른 동작을 할 수 있도록 환경 설정 패널 및 환경 저장을 위한 API를 제공합니다.
텍스트큐브 플러그인에 환경 설정 기능을 더하는 방법은 크게 두 부분으로 나누어집니다.
- index.xml - 변수 종류 및 환경 변수의 유효성 확인을 위한 validation handler 지정
- index.php - 환경 변수의 유효성 확인을 위한 validation handler function 구현
텍스트큐브는 플러그인 제작자가 지정해준 xml을 해석하여 자동으로 환경설정 패널을 만들어 줍니다.
Hello world 플러그인의 'Hello World!' 문구를 다양하게 바꿀 수 있도록 플러그인을 바꾸어 보겠습니다.
- index.xml
<?xml version="1.0" encoding="utf-8"?>
<plugin version="1.0">
<title xml:lang="ko">안녕 세상아! (기본)</title>
<link>http://www.example.com/</link>
<version>1.0</version>
<description xml:lang="ko">여기저기에 Hello world!를 출력해보는 예제 플러그인입니다.</description>
<license>GPL</license>
<author xml:lang="ko" link="http://www.example.com">슈퍼맨</author>
<safety changeData="no" exposeData="no" accessLocal="no" accessRemote="no" accessRaw="no" />
<requirements>
<textcube>1.5</textcube>
</requirements>
<binding>
<tag name="HelloWorld" handler="Helloworld_Show" />
<config xml:lang="ko" dataValHandler="Helloworld_Validation">
<window width="500" height="350" />
<fieldset legend="Hello World 문구 수정하기">
<field title="문구" name="printStr" type="text" size ="25" titledirection="bk" value="Hello World!">
<caption>출력하고 싶은 문구를 넣어주세요.</caption>
</field>
</fieldset>
</config>
</binding>
</plugin>환경 설정 패널은 안에 config 넣어 만들 수 있습니다. 환경 설정 API는 설정값이 올바른지 판단하는 함수를 만들어 데이터 유효성 검사 핸들러인 dataValHandler로 연결해야 합니다.
-
<window width="_number''" height="''number_">: 환경 설정 패널의 크기를 결정합니다. 단위는 픽셀입니다. -
<fieldset>: 환경 설정 패널에 표시될 영역을 묶습니다. 같은 종류의 설정 패널을 구획으로 묶기 위하여 사용합니다. legend로 명기하는 설명의 경우 환경설정 패널에 자동으로 표시됩니다. -
<field>: 환경 설정값을 표기합니다.-
name: 환경 변수의 이름입니다. 이후 환경 변수의 키 이름이 됩니다. -
type: 변수의 종류입니다. type으로는 text, radio, select, textarea, checkbox를 지원합니다. -
size: 입력 필드의 크기입니다. -
titledirection: 설명이 앞 또는 뒤 중 어느쪽에 붙는지를 정합니다. -
value: 처음 플러그인이 활성화된 직후 환경설정을 열었을 때 보여질 기본값을 정합니다. -
<caption>: 환경 설정 항목에 대한 설명을 기술합니다.
-
-
index.php
<?php
function Helloworld_Show($target) {
requireComponent('Textcube.Function.Setting'); // 버전이 1.6 미만일 경우 requireComponent('Textcube.Function.misc');
$config misc::fetchConfigVal($data);
return $target.$config['printStr'];
}
function Helloworld_Validation($data) {
requireComponent('Textcube.Function.Setting'); // 버전이 1.6 미만일 경우 requireComponent('Textcube.Function.misc');
$config misc::fetchConfigVal($data);
if (empty($config['printStr'])) return "문자열이 없습니다";
return true;
}
?>Helloworld_Validation() 함수는 데이터 무결성을 체크하는 핸들러입니다. 첫번째 줄은 환경 변수를 읽어오기 위한 컴포넌트를 부르는 부분이고, 두번째 줄은 현재 플러그인의 환경변수를 xml형태의 $data에서 읽어와서 $config에 넣는 역할을 합니다. 이 함수에서 환경 설정 변수가 제대로 설정 되었는지, 타입, 값의 범위등을 체크합니다. 만약 모든 설정 값이 정상적이면 true를 돌리면 되고, 그렇지 않은 경우 에러 메세지를 출력하면 됩니다.
변수의 타입이나 값을 체크하기 위하여 텍스트큐브는 Validator class를 지원합니다. PHP의 명령이 부족하거나, 자체적으로 구현하는 부담을 덜기 위해서는 Validator class를 활용하기를 권장합니다.
Helloworld_Show() 함수는 이전의 예제들과 형태가 같습니다. 단, 출력하는 문자열을 환경 설정 값에서 읽어와서 출력한다는 점이 다릅니다.
- index.xml
<?xml version="1.0" encoding="utf-8"?>
<plugin version="1.0">
<title xml:lang="ko">텍스트큐브 생일 표시</title>
<link>http://needlworks.org/</link>
<version>1.0</version>
<description xml:lang="ko">텍스트큐브의 생일과 D-day를 블로그 페이지에 출력합니다. [##_TextcubeBirthday_##] 태그가 스킨에 있어야 합니다.</description>
<license>GPL</license>
<author xml:lang="ko" link="http://needlworks.org">Needlworks</author>
<safety changeData="no" exposeData="no" accessLocal="no" accessRemote="no" accessRaw="no" />
<requirements>
<textcube>1.5</textcube>
</requirements>
<binding>
<tag name="TextcubeBirthday" handler="TextcubeBirthday_TextcubeBirthday" />
<config xml:lang="ko" dataValHandler = "TextcubeBirthdayDataSet" >
<window width="500" height="525" />
<fieldset legend="기념일을 넣어주세요" >
<field title="월" name="month" type="select" titledirection="bk" >
<op value="1">1</op>
<op value="2" >2</op>
<op value="3" checked="checked">3</op>
...
<op value="11">11</op>
<op value="12">12</op>
</field>
<field title="일" name="day" type="text" size ="3" titledirection="bk" value="13">
<caption> 날짜는 숫자로만 넣어주세요.</caption>
</field>
</fieldset>
</config>
</binding>
</plugin>지금까지의 예들보다는 복잡해 보입니다만, 알고보면 크게 다르지는 않습니다. 이 플러그인은 [wiki:pluginTag tag] 이벤트를 통하여 동작하는 플러그인입니다.
- index.php
<?php
function TextcubeBirthday_TextcubeBirthday($target) {
global $configVal;
requireComponent('Textcube.Function.Setting');
$data = setting::fetchConfigVal($configVal);
$month = 3;
$day = 13;
if (!is_null($data)){
$month = $data['month'];
$day = $data['day'];
}
$dDay = intval((gmmktime(0, 0, 0, $month, $day) - time()) / 86400);
if ($dDay < 0)
$dDay = intval((gmmktime(0, 0, 0, $month, $day, gmdate('Y') + 1) - time()) / 86400);
if ($dDay == 0)
$message = '<span class="congratu">탄생을 축하합니다!</span>';
else
$message = "<span>앞으로 {$dDay}일 남음</span>";
ob_start();
?>
<div class="listbox">
<h3>텍스트큐브 생일</h3>
<div style="text-align:center"><?php echo $month;?>월 <?php echo $day;?>일: <?php echo $message;?></div>
</div>
<?php
$target = ob_get_contents();
ob_end_clean();
return $target;
}
function TextcubeBirthdayDataSet($DATA){
requireComponent('Textcube.Function.Setting');
$cfg = setting::fetchConfigVal( $DATA );
// if( $cfg['month'] != 날짜냐?) return "잘못된 날짜입니다.";
// 등등등등 여기서 원하는 검증을 하고 검증 실패시 사용자에게 보여줄 에러메세지를 리턴하면 됩니다.
// 성공하면 그냥 true
return true;
}
?>플러그인의 index.xml에서 환경 설정 패널의 값을 주지 않고 직접 플러그인 속성을 xml형태로 플러그인으로 넘겨줄 수 있습니다. 이 방법을 사용하여 플러그인의 index.xml 을 간단하게 줄일 수 있습니다. 또한 index.xml 의 환경 설정 패널 값으로는 접근하기 속성 값을 지정할 수 있습니다.
이를 사용하기 위해서는
<config manifestHandler="함수이름"/>의 형태로 manifest Handler를 지정하면 됩니다. manifest Handler 함수는 index.php 안에 작성하시면 됩니다. manifest handler의 리턴 값은 완전한 형태의 xml 형태입니다.
아래는 위에서 예로 든 플러그인을 변경해 본 예제입니다.
<?xml version="1.0" encoding="utf-8"?>
<plugin version="1.0">
<title xml:lang="ko">텍스트큐브 생일 표시</title>
<link>http://needlworks.org/</link>
<version>1.0</version>
<description xml:lang="ko">텍스트큐브의 생일과 D-day를 블로그 페이지에 출력합니다. [##_TextcubeBirthday_##] 태그가 스킨에 있어야 합니다.</description>
<license>GPL</license>
<author xml:lang="ko" link="http://needlworks.org">Needlworks</author>
<safety changeData="no" exposeData="no" accessLocal="no" accessRemote="no" accessRaw="no" />
<requirements>
<textcube>1.5</textcube>
</requirements>
<binding>
<tag name="TextcubeBirthday" handler="TextcubeBirthday_TextcubeBirthday" />
<config xml:lang="ko" dataValHandler="TextcubeBirthday_manifest" />
</binding>
</plugin>지금까지의 예들보다는 복잡해 보입니다만, 알고보면 크게 다르지는 않습니다. 이 플러그인은 [wiki:pluginTag tag] 이벤트를 통하여 동작하는 플러그인입니다.
- index.php 안의 manifest handler
function TextcubeBirthday_manifest($plugin) {
ob_start();
?>
<?xml version="1.0" encoding="utf-8"?>
<config>
<window width="500" height="525" />
<fieldset legend="기념일을 넣어주세요" >
<field title="월" name="month" type="select" titledirection="bk" >
<op value="1">1</op>
<op value="2" >2</op>
<op value="3" checked="checked">3</op>
...
<op value="11">11</op>
<op value="12">12</op>
</field>
<field title="일" name="day" type="text" size ="3" titledirection="bk" value="13">
<caption> 날짜는 숫자로만 넣어주세요.</caption>
</field>
</fieldset>
</config>
<?php
return ob_get_clean();위의 예제는 환경설정 패널로도 가능한 경우만을 예로 들었지만, manifest handler를 사용하면 php에서 파싱한다는 점을 이용하여 패널에 특정 변수 값 ($pluginURL, $pathURL등) 을 응용한 출력이나 설명 예제등을 넣는 것도 가능합니다.
텍스트큐브에서 기본적으로 제공하는 플러그인 설정 패널의 디자인 CSS가 마음에 들지 않는 경우, 플러그인 제작자가 직접 CSS를 만들어 사용할 수 있습니다. 플러그인 디렉토리와 같은 디렉토리 안에 plugin-config.css를 넣으면 환경 설정 패널을 여는 순간 텍스트큐브 플러그인 패널의 기본 CSS파일 대신 그 CSS 파일을 불러옵니다.
- Source | Wiki Front | Main | Notice