written: Sep 29 2006
[버전1.2.0 제안서] 여기서 기술한 내용은 확정된 용법이 아니라 다음 버전을 발표할 때까지 여러분의 의견 수렴을 통해 더 검토되어야 하는 제안서(proposal)로 문법적인 내용이 다소 변경될 수 있음을 미리 밝혀둡니다.
다음 버전부터는 필터 기능을 지원하지 않습니다. 필터기능은 다른 방법으로 단순화시켜 제공할 생각입니다.
필터 함수
필터함수에는 사용자정의 필터함수(user defined filter function)와 내장 필터함수(built-in filter function)로 구분할 수 있습니다. 내장 필터함수는 템플릿 문서를 작성하는데 도움이 될 만한 함수를 후키템플릿 클래스에 포함시켜 제공됩니다. 사용자정의 필터함수는 사용자가 직접 필요한 필터함수를 정의하여 사용할 수 있습니다.
필터함수 정의하기
모든 필터함수는 아래와 같은 형식으로 정의되어야 합니다.
function 필터함수명($contents, $config [, ......]) {
......
return $contents;
}
필터함수는 템플릿 문서 내용이 첫번째 인자 $contents를 통해 전달받는데 각 실행시간에 따라 $contents의 형식과 내용이 다소 다릅니다. 전달받는 $contents의 형식과 내용에 대하여는 각 실행시간별로 살펴보겠습니다.
두번째 인자로 지정된 변수 $config는 템플릿 객체생성할 때 설정된 컴파일옵션과 템플릿명이 아래와 같은 배열 형식으로 설정되어 있습니다.
[config] => (array)
(
[active_absolute_path] => (boolean) false 또는 true
[active_html_compress] => (boolean) false 또는 true
[active_html_header] => (boolean) false 또는 true
[active_html_parse] => (boolean) false 또는 true
[active_tag_lowercase] => (boolean) false 또는 true
[active_url_redirection] => (boolean) false 또는 true
[template_name] => (string) 필터함수가 정의된 템플릿 문서의 템플릿명
)
사용자가 지정하지 않더라도 첫번째와 두번째 인자는 자동으로 필터함수로 넘어옵니다. 만약 $contents와 $confilg 정보 외에 다른 정보를 필터함수로 전달하기 위해서는 아래의 템플릿 문서의 예와 같이 필요한 정보를 필터함수와 함께 기술해주면 됩니다.
{#FILE;;
=|user_filter("{_VERSION}", $global_var, "템플릿툴을 통한 홈페이지 제작 방안")
}./test.htm{/}
위의 템플릿 문서 예에서 지정한 사용자정의 필터함수 user_filter()에는 사용자에 의해 템플릿변수 {_VERSION}, 전역변수 $global_var, 문자열 "템플릿툴을 통한 홈페이지 제작 방안"이 추가적으로 전달되고 있습니다. 추가된 정보를 필터함수에서 전달받기 위해서는 필터함수를 아래와 같이 정의하여야 합니다.
function user_filter($contents, $config, $version, $gVar, $str) {
......
return $contents;
}
사용자가 필터함수에 추가적으로 기술한 정보들은 필터함수의 세번째 인자부터 차례로 전달됩니다.
각 실행시간별로 필터함수를 정의하는 예를 살펴보기 위하여 우선 아래의 예제와 같은 템플릿 문서에 작성된 파일 변수에 지정된 각각의 필터함수를 정의해 보겠습니다.
{#FILE;;
initialize {%
=|initialize_skin();
%}
premacro {%
=|premacro_skin();
%}
precompile {%
=|precompile_skin();
%}
postcompile {%
=|postcompile_skin();
%}
preassign {%
=|preassign_skin();
%}
postassign {%
=|postassign_skin();
%}
output {%
=|output_skin();
%}
}./test.htm{/}
필터함수 이름은 사용자가 임의로 명명하여도 되지만 php 내장함수를 포함한 현재 페이지에서 사용 중인 사용자 정의 전역함수 이름과 중복하여 명명할 수 없습니다.
initialize 실행시간 필터함수 정의하기
initialize 실행시간 필터함수는 내용형식(contents type)이 템플릿인 파일변수에서만 사용할 수 있으며, 아래와 같은 형식으로 정의합니다.
function initialize_skin($contents, $config [, ......]) {
......
return $contents;
}
initialize 실행시간 필터함수에 넘어오는 변수 $contents는 아무런 의미없는 빈문자열입니다. 리턴값 역시 별 의미가 없기 때문에 생략해도 됩니다만 향후 버전과의 호환성을 위하여 생략하지 말기 바랍니다.
premacro 실행시간 필터함수 정의하기
premacro 실행시간 필터함수는 내용형식(contents type)이 템플릿인 파일변수에서만 사용할 수 있고 템플릿 문서를 컴파일할 때만 실행하며, 아래와 같은 형식으로 정의합니다.
function premacro_skin($contents, $config [, ......]) {
......
return $contents;
}
premacro 실행시간 필터함수에 넘어오는 변수 $contents에는 파일변수에서 지정된 파일의 내용이 그대로 담겨있습니다.
템플릿 문서를 컴파일하려면 아래의 몇가지 예와 같이 각 버전별로 상이한 템플릿 변수 형식을 통일시키는 등의 문자열 치환 작업(매크로 작업)이 필요합니다.
① <!--{ 을 { 으로 치환
② }--> 을 } 으로 치환
③ <!-- BEGIN DYNAMIC BLOCK: 블록명 --> 을 {@ 블록명} 으로 치환
④ <!-- END DYNAMIC BLOCK: 블록명 --> 을 {/} 으로 치환
⑤ <!--#include file="파일명"--> 을 {#파일명} 으로 치환
⑥ 기타 등등
이러한 매크로 작업은 템플릿툴이 컴파일하기 전에 자동으로 처리하는데 premacro 실행시간 필터함수는 템플릿툴이 미리 지정된 매크로 작업을 하기 전에 사용자가 먼저 템플릿 문서 내용을 넘겨받아 처리해야 할 필요가 있을 때 작성하는 함수입니다.
precompile 실행시간 필터함수 정의하기
precompile 실행시간 필터함수는 템플릿 문서를 컴파일할 때만 실행하며, 아래와 같은 형식으로 정의합니다.
function precompile_skin($contents, $config [, ......]) {
......
return $contents;
}
precompile 실행시간 필터함수에 넘어오는 변수 $contents에는 여러가지 문자열 치환 작업(매크로 작업)을 한 직후의 템플릿 내용이 문자열 형식으로 담겨있습니다.
postcompile 실행시간 필터함수 정의하기
postcompile 실행시간 필터함수는 템플릿 문서를 컴파일할 때만 실행하며, 아래와 같은 형식으로 정의합니다.
function postcompile_skin($contents, $config [, ......]) {
......
return $contents;
}
postcompile 실행시간 필터함수에 넘어오는 변수 $contents에는 컴파일된 템플릿 문서 내용이 배열형식으로 들어있습니다. 컴파일된 템플릿 문서 형식은 각 버전별로 상이하며 향후 버전에서도 상황에 따라 수시도 변경될 수 있으니 사용자가 $contents의 내용을 임의로 수정해서는 안되며, 수정되지 않은 내용을 그대로 리턴값으로 넘겨주어야 합니다. 이 함수에서 리턴된 값은 바로 캐시에 저장됩니다.
preassign 실행시간 필터함수 정의하기
preassign 실행시간 필터함수는 아래와 같은 형식으로 정의합니다.
function preassign_skin($contents, $config [, ......]) {
......
return $contents;
}
preassign 실행시간 필터함수는 아래의 예에서 볼 때 assign() 함수를 수행하는 시작부분에서 템플릿에 존재하는 변수들을 할당(assign)하기 직전에 수행합니다.
[code php;gutter:false]
$tpl->assign('test','test');
[/code]
preassign 실행시간 필터함수에 넘어오는 변수 $contents에는 캐시에 저장되었던 템플릿 문서 내용이 담겨있습니다. 따라서 후키템플릿 고유의 배열형식으로 postcompile 실행시간 필터함수에서 설명한 것과 마찬가지로 사용자가 $contents의 내용을 임의로 수정해서는 안되며, 수정되지 않은 내용을 그대로 리턴값으로 넘겨주어야 합니다.
postassign 실행시간 필터함수 정의하기
postassign 실행시간 필터함수는 아래와 같은 형식으로 정의합니다.
function postassign_skin($contents, $config [, ......]) {
......
return $contents;
}
postassign 실행시간 필터함수는 assign() 함수를 수행하는 마지막부분에서 템플릿을 할당(assign)한 직후에 수행합니다.
postassign 실행시간 필터함수에 넘어오는 변수 $contents에는 템플릿 문서에 포함된 모든 템플릿 변수들이 처리된 문자열 형식의 순수 HTML 스크립트 문서가 담겨있습니다. 주의할 점이 원래 템플릿 파일에 있는 내용 중에서 BODY 태그 내에 있는 내용만 전달되며 BODY 태그 밖에 있는 HEAD 태그 내의 내용 등은 없습니다. BODY 태그 밖에 있는 내용을 처리하기 위해서는 output 실행시간 필터함수를 이용하여야 합니다.
output 실행시간 필터함수 정의하기
output 실행시간 필터함수는 아래와 같은 형식으로 정의합니다.
function output_skin($contents, $config [, ......]) {
......
return $contents;
}
output 실행시간 필터함수는 php 스크립트의 실행이 종료되기 직전 출력버퍼 내용으로 부터 HTML 스크립트 문서를 생성한 직후에 실행됩니다. 따라서 $contents에는 생성된 HTML 스크립트 문서의 내용이 담겨있으며 이 함수에 의해 리턴된 값이 브라우저로 전송됩니다.
각 템플릿 문서에 허용필터명령을 지정한 경우에 output 실행시간에 처리되는 필터함수는 모든 템플릿 문서에 적용된 허용필터명령의 조건을 모두 만족해야 합니다.
