====== DokuWiki 템플릿 개발 ======

새로운 템플릿을 만들어 [[:DokuWiki]]의 디자인을 커스트마이징할 수 있다. 템플릿은 PHP와 CSS 파일들로 ''<dokuwiki>/lib/tpl/'' 디렉토리에 저장된다.(실제로 템플릿은 HTML로 만들어지며, 그 내용 안에 PHP가 사용된다.)

===== 시작 =====

출발점으로 새로운 템플릿을 만드는 가장 쉬운 방법은 이미 만들어진 템플릿을 가져오는 것이다. 스타트 템플릿(starter template)은 안전하고 Dokuwiki의 템플릿 표준을 따르므로 이것을 사용하는 것은 좋은 아이디어이다.

  - 스타트 템플릿(starter template)을 설치한다.
  - ''lib/tpl/starter'' 디렉토리를 ''lib/tpl/yourname'' 으로 변경한다.
  - 설정관리자(configuration manager)에서 새로운 템플릿을 선택한다.
  - 그 다음 템플릿 파일을 살펴본다. ([[#디렉토리 구조]] 참조)
  - 도쿠위키가 [[devel:css|CSS dispatcher]]를 이용하여 어떻게 [[CSS]]를 처리하는지 살펴본다.
  - 설정을 구성하는 방법은 플러그인과 유사하다. 사용자정의 템플릿의 설정을 얻을려면 tpl_getConf(<setting>)을 사용한다.

템플릿이 안정화되면 도쿠위키 템플릿 페이지에 등록할 수 있다.

===템플릿 이름 규칙===

A 유효한 템플릿 이름 (디렉토리):
  * a-z and 0-9 문자만 사용해야 한다.
  * 마침표 ''.'', 줄표 ''-''와 밑줄 ''_'' 은 사용할 수 **없다** :
    * 도쿠위키의 인프라스트럭처는 그것을 어디에서도 지원하지 않는다.
    * 밑줄 ''_''의 사용은 역시 0의 인기평가를 준다.
  * 만약 동일한 이름이 서로 다른 두 템플릿에 의해 사용되면 
    * 그것들은 상호 배타적이고 호환되지 않으며
    * 나아가 그들 중 하나만 dokuwiki.org의 템플릿 홈페이지를 가질 수 있다.

** [[devel:template_info|template.info.txt]]에 고유한 필드 값(즉, 템플릿 이름)이나 또는 이름을 덮어 쓸 수 있는 기존의 템플릿으로 하는 것이 중요하다.**
===== 디렉토리 구조 =====
템플릿은 아래의 디렉토리 구조(모든 경로는 템플릿 디렉토리를 기준으로)를 따라야 한다. 

모든 CSS파일은 ''[[CSS#style.ini]]''에 명시되지만 적어도 화면 프리젠테이션과 인쇄용으로 각각 하나의 CSS파일이 필요하다.

  * ''<dokuwiki>/lib/tpl/<template>/''
    * ''<filename>.css'' -- 템플릿의 스타일시트(몇 이상이 있는 경우, /css 서브디렉토리에 그룹화 하는 것이 합리적)
    * ''script.js'' -- 선택사항, 템플릿에 자바스크립트가 필요한 경우 적용
    * ''[[devel:templates:main.php]]'' -- 도쿠위키의 전체적인 레이아웃
    * ''[[devel:templates:detail.php]]'' -- 이미지 상세 페이지
    * ''[[devel:templates:mediamanager.php]]'' -- 미디어 선택 팝업
    * ''images/'' -- 템플릿에서 사용되는 모든 이미지
    * ''conf/'' -- 설정파일들 (선택사항, 설정이 사용된다면)
      * ''default.php'' -- 템플릿 설정을 위한 디폴트 설정
      * [[devel:configuration#template settings]]을 위한 [[configuration#default settings]] (''tpl_getConf()''를 통해 접근 가능, 로컬셋팅은 DokuWiki의 전역 ''<dokuwiki>/conf/local.php''에 저장된다)
      * ''metadata.php'' -- [[configuration#configuration metadata]]는 환경설정관리자에서 사용될 설정의 속성들을 기술 
    * ''lang/'' -- 언어 파일
      * ''<lang code>/lang.php'' -- 템플릿의 [[[[devel:localization#template_localization|현지화 문자]]에 사용 (선택사항, 필요할 경우 사용)
      * ''<lang code>/settings.php'' -- 현지화 문localization strings used in the configuration manager (만약 설정이 사용된다면)
    * ''style.ini'' -- see [[devel:style.ini]]
    * ''favicon.ico'' -- 미디어 디렉토리에 없다면 사용된다 ([[xref>tpl_favicon()|tpl_favicon()]] 참조)
    * ''template.info.txt'' -- [[devel:template info|템플릿 정보]]가 있는 텍스트 파일 **필수사항!**
===== 함수=====

[[xref>inc/template.php|API documentation]]에서 사용 가능한 함수를 확인할 수 있다. 여기는 특이한 몇가지 예이다.

  * **''[[xref>tpl_content()]]''** \\ 이 함수는 페이지 본문, 즉 [[:TOC]]을 포함한 위키페이지의 내용을 출력한다. 이 함수가 호출될 때 인자로 false를 전달하면 TOC가 출력되지 않도록 할 수 있다.: <code php>
tpl_content(false);
</code> 이것은 TOC를 컨텐츠로부터 분리하여 화면의 어딘가 다른 곳에 두고 싶을 때 사용할 수 있다. 보다 자세한 사항은 아래의 ''tpl_toc()''를 살펴보라.

  * **''[[xref>tpl_toc()]]''** \\ 디폴트로 ''tpl_content()'' 함수는 실제 페이지 컨텐츠에 덧붙여 자신의 [[:TOC|Table of Contents]] 표시를 처리한다. 만약 템플릿이 사이드바를 사용하거나 좀더 복잡한 레이아웃이라면 TOC를 페이지 컨텐츠로 부터 독립적으로 위치시키기를 원할 수 있다. 이것은 ''tpl_toc()'' 함수로 가능하다. 이것을 사용할 때는 ''tpl_content()'' 함수의 인수를 ''false''로하여 TOC 자동 배포를 비활성화 하는 것이 중요하다.\\ \\ **예제:** \\ <code php>
<div id="content">
    <?php tpl_content(false)?>
</div>

<div id="sidebar">
    <?php tpl_toc()?>
</div>
</code> ''tpl_toc()'' 함수는 세 가지 다른 소스에서 TOC를 생성한다 : [[environment#$TOC]] 전역변수, 해당 페이지의 [[metadata]] 또는 [[admin plugins]]의 ''getTOC()'' 메소드이다. 이전 버전이나 ''tpl_toc()'' 미리보기에서는 metadata가 없기 때문에 이런 경우 [[environment#$TOC]] 전역변수만 사용할 수 있다. [[environment#$TOC]] 변수는 페이지 렌더러에 의해 채워지기 때문에 이것은 오직 ''tpl_content()'' 이후에 ''tpl_toc()'' 이 호출될 경우에 작동된다. 만약 이런사항이 템플릿의 레이아웃상 불가능하다면 이러한 문제해결을 위해 출력버퍼링을 사용할 수 있다. \\ \\ **예제:**\\ <code php>
<?php
    // 나중에 사용하기 위해 버퍼에 컨텐츠 렌더링
    ob_start();
    tpl_content(false);
    $buffer = ob_get_clean();
?>

<div id="sidebar">
    <?php tpl_toc()?>
</div>

<div id="content">
    <?php echo $buffer?>
</div>
</code>

  * **''[[xref>tpl_getConf()|tpl_getConf('key')]]''** \\ 이 함수는 템플릿의 [[configuration|configuration settings]]에 접근하기 위해 사용된다.

  * **''[[xref>tpl_getLang()|tpl_getLang('key')]]''** \\ 이 함수는 템플릿의 현지화된 문장에 접근하기 위해 사용된다. 자세한 사항은 [[devel:localization]] 개발 문서를 살펴보라.

  * 또한 다른 많은 유용한 템플릿 함수들를 사용할 수 있다. [[xref>inc/template.php|API 문서]]를 살펴보기 바란다.
===== 전역 변수와 상수 =====
유용한 전역 변수와 상수의 전체 목록은 [[environment]] 페이지를 참조하라.
===== 자동 유지관리 =====

디폴트 템플릿의 [[devel:templates:main.php]] 파일 거의 맨아래에는 ''[[xref>tpl_indexerWebBug()]]'' 함수가 있다. 이 함수는 ''[[:indexer|lib/exe/taskrunner.php]]''에 대한 요청이 이루어질 수 있도록  HTML ''%%<img>%%'' 태그를 생성한다. 이 **필수적인** 도쿠위키 일부분은 위키가 원활한 작동이 유지되도록 중요한 유지관리작업을 제공한다. 모든 템플릿은 이 함수를 포함해야하고, 그렇지 않으면 위키는 제대로 작동하지 않을 수 있다 (예를 들어 [[:search|search index]]가 만들어지지 않는 등).

===== 'dokuwiki' class =====

dokuwiki 값을 가진 class 속성은 각각의 템플릿의 [[devel:templates:main.php]], [[devel:templates:detail.php]]와 [[devel:templates:mediamanager.php]]에서 HTML 엘리먼트로 둘러싸인 몇 컨텐츠에서 (전체 또는 적어도 tpl_contents() 주변) 추가되어야 한다. 이것은 만약 잠재적으로 상충되는 CSS를 가진 기존의 사이트와 통합된 경우 도쿠위키의 스타일이 다른 스타일과 충돌하지 않도록 한다. 
===== 삽입 후크 =====

삽입 후크는 별도의 [[:Template]]을 만들지 않고 자신의 [[:DokuWiki]]에 정적인 컨텐츠를 추가할 수 있는 간편한 방법이다.  이것을 이용하여 각 페이지 아래에 표준 머리글이나 회사로고 또는 법적고지사항을 추가 할 수 있다.

도쿠위키 디폴트 템플릿은 템플릿의 디렉토리 내부에 특별한 이름을 가진 파일을 찾아서 페이지가 표시될 때 정확한 위치에 삽입한다. 이 파일들에 원하는 어떤 HTML이든 추가할 수 있다. 물런 디폴트 템플릿이나 또는 삽입 후크를 지원하는 템플릿(starter 템플릿 처럼)을 사용할 경우에만 해당된다.

PHP도 이 파일들 안에 포함할 수 있다.
==== 사용가능한 Hooks ====

모든 여기 파일들은 템플릿 디렉토리 즉 ''lib/tpl/dokuwiki/''에서 검색된다.

^ 파일명        ^ 삽입되는 HTML의 위치                                               ^
| ''meta.html''       | HTML <head>에 들어갈 내용, meta 요소를 추가하기 위해 사용 (e.g. Google Analytics code) |
| ''header.html''     | the header 위(로고, 위키 이름 등) |
| ''sidebarheader.html''  | 사이드바 내용 바로 전 (그러나 사이드바에 포함) |
| ''sidebarfooter.html''  | 사이드바 내용 바루 후 (그러나 사이드바에 포함) |
| ''pageheader.html'' | 위키페이지 컨텐츠 상단 (그러나 컨텐츠 섹션에 포함) |
| ''pagefooter.html'' | 위키페이지 컨텐츠 하단 (그러나 컨텐츠 섹션에 포함) |
| ''footer.html''     | 페이지 끝 |

사용자 설명을 위한 [[:include hooks]] 또한 살펴보라.

===== dokuwiki.org에 템플릿 등록 =====

템플릿을 만들었다면, 커뮤니티에 공유하길 바란다. 단지 [[:template]] 네임스페이스에 템플릿의 이름을 딴 페이지를 만들어라. 예를 들면 템플릿의 이름이 ''sample''이면 이 위키 안에 ''template:sample''의 페이지를 만들어라.

At the top of the template page a few metadata fields have to be filled in. A description of each field can be found on the [[plugin:repository#template_entry|Repository Plugin]] page.

From version Ponder Stibbons on an automated update signalling is possible. For the update process to work properly it is necessary that the date “Last updated on” on the template's wiki page equals the date in the file [[devel:template_info|template.info.txt]] in the source tarball/zip file. If this is not the case the update will not take place or the “Update” signal persists.

Uploads are not allowed on dokuwiki.org, so you need to host your template files somewhere else. We recommend to manage your source with a Revision Control System like [[git]]. If you do, it's easiest to use a public repository host like [[http://github.com|GitHub]] which offers also a bug tracker for your repository.