written: Oct 26 2006
[버전1.2.0 제안서] 여기서 기술한 내용은 확정된 용법이 아니라 다음 버전을 발표할 때까지 여러분의 의견 수렴을 통해 더 검토되어야 하는 제안서(proposal)로 문법적인 내용이 다소 변경될 수 있음을 미리 밝혀둡니다.
다음 버전부터는 필터 기능을 지원하지 않습니다. 필터기능은 다른 방법으로 단순화시켜 제공할 생각입니다.
필터명령 실행시간
필터명령의 실행시간은 아래와 같은 지시자에 의해 변경될 수 있으며, 또한 혼용되어 사용될 수 있습니다.
① initialize
② premacro
③ precompile
④ compile
⑤ postcompile
⑥ preassign
⑦ assign
⑧ postassign
⑨ output
블록변수를 포함한 모든 템플릿변수의 필터명령 실행시간을 정리하면 아래표와 같습니다.
< 필터명령 실행시간 >
| 실행시간 |
단순
변수 |
조건
변수 |
블록변수 |
파일변수 |
| tpl |
txt |
php |
tpl |
txt |
php |
| initialize |
x |
x |
x |
x |
x |
o |
x |
x |
| premacro |
x |
x |
x |
x |
x |
o |
x |
x |
| precompile |
x |
x |
o |
o |
o |
o |
o |
o |
| compile |
x |
x |
x |
x |
x |
x |
x |
x |
| postcompile |
x |
x |
o |
x |
x |
o |
x |
x |
| preassign |
x |
x |
o |
x |
x |
o |
x |
x |
| assign |
@ |
@ |
x |
x |
x |
x |
x |
x |
| postassign |
x |
x |
@ |
@ |
@ |
@ |
@ |
@ |
| output |
x |
x |
x |
x |
x |
o |
x |
x |
블록변수/파일변수에 필터명령 실행시간(execute time)을 지정하지 않으면(default 상태) 블록내용/파일내용을 assign한 직 후(postassign)에 필터링합니다. 반면 단순변수/조건변수는 assign할 때 필터링합니다. 이와 같이 각 템플릿 변수별로 실행시간 초기값이 지정되어 있습니다.
위 표의 기준과 다르게 예외적으로 compile 실행시간으로 처리되는 요소들은 아래와 같습니다.
① 필터상수(filter constants)
② 파일변수의 파일명(filename)
③ 내용형식(contents type) ctype이 php일 때에 php 문서에 포함된 템플릿 변수들
④ ctype이 template인 단순변수의 변수내용부분
compile 실행시간은 사용자가 지정할 수 없으며, 템플릿 툴이 내부적으로만 사용하는 실행시간입니다.
필터명령 실행시간을 제어하는 방법
템플릿변수의 필터명령은 각각 아래와 같이 지정합니다.
단순변수일 때 {&변수명;;필터명령}변수내용{/}
조건변수일 때 {?변수명;;필터명령}경우의수{/}
블록변수일 때 {@변수명;;필터명령}블록내용{/}
파일변수일 때 {#변수명;;필터명령}파일명{/}
실행시간에 대한 언급없이 단순히 필터명령만 지정하는 경우 위 표 <필터명령 실행시간> 의 default 실행시간으로 처리됩니다. 이러한 default 실행시간은 아래의 파일변수 예에서와 같이 다른 시간으로 강제 지정할 수 있습니다.
{#FILE;;
initialize {%
=*include_once('{::_PATH_TO_TPLS}/filter.php');
=|initialize_skin();
%}
premacro {%
=|prefilter_macro();
%}
precompile {%
={_SELF};
%}
postcompile {%
=|postfilter_compile();
%}
preassign {%
=|prefilter_assign();
%}
postassign {%
=|postfilter_assign();
%}
}./include.htm{/}
사용자정의 필터함수들은 각 실행시간에 해당 필터함수가 실행되기 전에 미리 정의되어 있어야 합니다.
강제 지정할 수 있는 실행시간은 각 변수별로 다릅니다. 각 변수별로 허용되지 않는 실행시간은 지정할 수 없으며, 지정했을 때 1.2.0 버전에서는 실행하지 않고 무시해버리나 향후 버전에서는 강제로 에러를 출력 후 프로그램을 중지시킬 수도 있으니 주의하기 바랍니다.
위의 예제에서 표기된 {_SELF}는 필터 처리할 때 사용되는 미리정의된 템플릿변수로 하위템플릿 파일인 include.htm의 내용을 가지고 있습니다. 이 템플릿 변수에 대한 자세한 정보는 "6.2.미리정의된 템플릿변수"를 참조바랍니다.
필터 FLOW
실행시간 중에 premacro, precompile, compile, postcompile으로 지정되는 필터명령들은 템플릿파일을 컴파일할 때만 수행되며, initialize으로 지정되는 필터명령은 컴파일 유무에 관계없이 define() 함수를 실행하는 초기에 수행되며, preassign, assign, postassign으로 지정되는 필터명령들은 assign() 함수를 실행할 때 수행됩니다.
output으로 지정된 필터명령들은 출력버퍼에 있는 문서를 가지고 최종 HTML 스크립트 문서를 생성할 때 수행됩니다.
< 필터 FLOW >
필터명령 구문 형식
지정할 수 있는 필터명령에는 필터상수, php명령, 전처리명령, 사용자정의 필터함수 및 내장 필터함수가 있습니다. 각각의 필터명령은 아래와 같은 표에 의해 지정됩니다.
< 필터명령 구문 형식 >
| 종 류 |
구문 형식 |
| 필터상수 |
{@변수명;;필터상수}내용{/} |
| php명령 |
{@변수명;;=php명령}내용{/} |
| 전처리명령 |
{@변수명;;=*전처리명령}내용{/} |
| 사용자정의 필터함수 |
{@변수명;;=|사용자정의 필터함수}내용{/} |
| 내장 필터함수 |
{@변수명;;=>내장필터함수}내용{/}*
{@변수명;;=)내장필터함수}내용{/} |
* [주의] - 2006.10.26
웹에디터에서 템플릿 문서를 작성할 때 내장 필터함수를 의미하는 "=>"가 제대로 입력되지 않는 문제가 발생하였습니다. 즉, 꺽은괄호(>)를 태그로 인식하여 ">"로 저장되어 필터처리가 원하는대로 되지 않습니다. 따라서 1.2.0의 패치버전(또는 다음버전)에서 꺽은괄호(>) 대신에 둥근괄호와 같은 다른 기호를 사용하려고 합니다. 예를들어 블록변수에서의 내장 필터함수의 구문형식을 현재와 수정안을 비교하여 살펴보면 아래와 같습니다.
현재 : {@변수명;;=>내장필터함수}내용{/}
수정(안) : {@변수명;;=)내장필터함수}내용{/}
허용필터명령 지정하기
허용필터명령을 지정할 수 있는 방법은 아래와 같이 세가지입니다.
① 생성자의 네번째 인자로 새롭게 추가된 필터옵션의 allow_filter 키를 통해서
② define() 함수의 세번째 인자인 옵션의 allow_filter 키를 통해서
③ 파일변수(인클루드문)의 변수옵션 allow_filter 키를 통해서
생성자에서 지정된 허용필터명령은 모든 템플릿문서에 적용됩니다.
[code php;gutter:false]
$tpl = new hTemplate(디렉토리정보, 캐시옵션, 컴파일옵션,
array(
'allow_filter' => 'func_a, func_c, func_d, func_e, ='
)
);
[/code]
'=' 문자를 지정하면 php명령과 전처리명령을 사용할 수 있습니다. '=' 문자를 제외한 func_a, func_c, func_d, func_e는 허용되는 사용자정의 필터함수를 의미합니다. 필터상수와 내장필터함수는 아무런 제한없이 모든 템플릿문서에서 사용할 수 있습니다.
특별히 허용필터명령을 지정하지 않으면 모든 필터명령(필터상수, php명령, 전처리명령, 사용자정의 필터함수 및 내장필터함수)을 사용할 수 있습니다.
define() 함수로 지정된 허용필터명령은 해당 define()에 지정된 템플릿 파일에만 적용됩니다. 또한 생성자에서 지정된 허용필터명령이 있을 때는 생성자에서 지정된 허용필터명령 중에서만 지정할 수 있습니다. 생성자에서 지정하지 않은 허용필터명령을 define() 함수에서 지정하더라도 무시됩니다.
[code php;gutter:false]
$tpl = new hTemplate(디렉토리정보, 캐시옵션, 컴파일옵션,
array(
'allow_filter' => 'func_a, func_c, func_d, func_e, ='
)
);
$tpl->define('main', 'filter.htm',
array(
'allow_filter' => 'func_a, func_b, func_e, func_f'
)
);
[/code]
템플릿 main(템플릿파일 filter.htm)에서는 사용자정의 필터함수 func_a, func_e만 허용되며 사용자정의 필터함수 func_b, func_f와 php명령, 전처리명령은 허용되지 않습니다. 필터상수와 내장필터함수는 역시 제한없이 사용할 수 있습니다.
마지막으로 파일변수(인클루드문)에서의 허용필터명령에 대하여 살펴보겠습니다.
파일변수에서 지정된 허용필터명령은 파일변수에서 지정된 파일에만 적용됩니다. 또한 현재 템플릿 문서가 생성자 또는 define() 함수로 허용필터명령이 지정된 경우에는 지정된 허용필터명령 중에서만 지정할 수 있습니다.
위 define() 함수로 지정된 허용필터명령의 예에 있는 php 스크립트에서 사용하는 템플릿 문서 filter.htm의 내용이 아래와 같은 경우를 살펴보겠습니다.
[code html;gutter:false]
<!-- template file : filter.htm -->{#SAMPLE;allow_filter=func_b, func_c, func_e, =;
=|func_a();
=|func_b();
=|func_c();
=|func_d();
=|func_e();
="[[["."{_SELF}"."]]]";
}./include.htm{/}
[/code]
파일변수 SAMPLE 내에서 허용되는 사용자정의 필터함수는 func_e뿐입니다. 왜냐하면 템플릿파일 filter.htm은 define() 함수에 의해 사용자정의 필터함수 func_a, func_e만 허용되었는데 파일변수 SAMPLE에서는 이 중에 func_e만 일치하고 나머지는 define() 함수에 의해 허용되지 않는 필터함수, php명령, 초기화명령이기 때문입니다. 따라서 파일변수 SAMPLE에서 지정한 많은 필터명령중에 다섯번째 필터명령인 =|func_e();만 정상적으로 수행하고 나머지는 무시해 버립니다.
파일변수 SAMPLE에서 지정된 템플릿파일 include.htm 내에서 또 다른 파일변수가 내포되어 있을 경우에 내포된 파일변수에서는 파일변수 SAMPLE에서 허용되는 func_e 함수만 필터명령으로 사용할 수 있습니다.
이와같이 파일변수가 중첩되었을 때는 허용필터명령이 하위 파일변수로 연속적으로 전달되어 허용필터명령을 제한하게 됩니다.
허용필터명령에 와일드카드 사용하기
허용필터명령을 지정할 때 아래와 같은 세가지 와일드카드 문자를 통하여 여러개의 필터명령을 한번에 지정할 수 있습니다.
① The asterisk(*) represents a whole word or a group of characters.
② The question mark(?) represents a single character.
③ The exclamation mark(!) is a character to deny filter functions.
* 문자는 해당 문자가 없거나 하나 이상의 문자(anything or nothing) 대신에 사용될 수 있습니다. 예를 들어 func_*는 func_a, func_b, func_aaa를 모두 나타내며 * 문자 위치에 아무 문자도 없는 func_으로도 나타낼 수 있습니다.
? 문자는 임의의 한 문자(any single character)를 대표해서 나타내며, ?는 a 또는 b 또는 6과도 일치합니다. 그러나 * 문자와는 달리 반드시 하나의 문자가 있어야 합니다. 예를 들어 func_?는 func_a, func_b와는 일치하지만 func_와는 일치하지 않습니다.
! 문자는 지정된 필터명령을 허용하지 않을 때 사용하는 논리적 부정의 의미를 가진 문자입니다. !가 없으면 허용필터명령(allow filter)이 되는 것이고, !가 앞에 있으면 불허필터명령(deny filter)이 되는 것입니다. 만약 func_*에 해당하는 필터명령들을 허용하지 않으려면 !func_*와 같이 맨 앞에 ! 문자를 덧붙이기만 하면 됩니다.
허용필터명령에 일치하지 않는 필터함수 처리
아래와 같이 허용필터명령을 지정하는 4가지 예에서 필터함수명이 일치하지않는 필터함수를 어떻게 처리하는지 살펴보겠습니다.
① {#FILE;allow_filter=func_a, func_b, func_c}./test.htm{/}
② {#FILE;allow_filter=!func_a, !func_b, !func_c}./test.htm{/}
③ {#FILE;allow_filter=func_a, !func_b, func_c}./test.htm{/}
④ {#FILE;allow_filter=func_a, func_b, !func_c}./test.htm{/}
첫번째 예에서는 지정된 func_a, func_b, func_c는 모두 허용필터함수들이며, 두번째 예에서 지정된 func_a, func_b, func_c는 모두 불허필터함수들이며, 세번째와 네번째는 허용필터함수와 불허필터함수가 혼재되어 있으며 차이점은 마지막으로 지정된 필터함수가 허용필터함수냐 불허필터함수냐는 것입니다.
지정된 필터명령과 일치하지 않는 func_d라는 함수가 있다면 각 경우에 func_d 함수는 어떻게 처리될까요? 결론부터 말씀드리자면 첫번째와 세번째 예에서는 실행되지 않고 두번째와 네번째 예에서는 실행됩니다.
실행하느냐 하지않느냐의 기준이 되는 것은 마지막으로 지정된 필터명령이 허용필터명령이냐 불허필터명령이냐 하는 것입니다. 마지막 필터명령이 허용필터명령이면 일치하지 않는 필터명령들은 불허필터명령이 되는 것이고 아니면 허용필터명령이 되는 것입니다.
세번째와 네번째 예는 아래와 같이 작성하여도 같은 결과를 얻을 수 있습니다.
③ {#FILE;allow_filter=func_a, func_c}./test.htm{/}
④ {#FILE;allow_filter=!func_c}./test.htm{/}
invalid-file
