====== Разработка шаблонов «Докувики» ======

:!: Страница нуждается в переработке. За точной информацией обращайтесь к [[devel:templates|английской версии страницы]]. :!:

Вы можете менять дизайн «[[..:dokuwiki|Докувики]]» по своему усмотрению, создав новый шаблон, который представляет собой несколько PHP- и CSS-файлов, сохранённых в каталоге и помещённых в ''<dokuwiki>/lib/tpl/'' (в действительности, шаблон написан на HTML, а PHP используется только для вставки контента).


===== Начало работы =====

Проще всего создать новый шаблон, взяв в качестве отправной точки уже существующий. Лучше всего подойдет шаблон «default», так как он содержит все необходимые части шаблона и следует стандартам составления шаблонов «Докувики». Название шаблона (каталога) следует писать в нижнем регистре без символов точки и подчеркивания.

  - Скопируйте стандартный шаблон ''lib/tpl/default'' в каталог, где будет хранится ваш шаблон, например ''lib/tpl/mytemplate'';
  - Выберите новый шаблон на странице «Управление»;
  - Ознакомьтесь с файлами шаблона (см. «[[templates#структура каталогов|Структуру каталогов]]»);
  - Посмотрите, как «Докувики» обрабатывает CSS с помощью [[..:devel:css|диспетчера CSS]];
  - Обработка конфигурационных параметров аналогична [[common_plugin_functions|плагинам]]. Используйте ''%%tpl_getConf(<setting>)%%'' для получения параметров шаблона.


===== Структура каталогов =====

Шаблоны должны иметь следующую структуру директорий (все пути указаны относительно каталога шаблона). Файлы CSS определены в ''[[CSS#style.ini]]'', но вам следует предоставить как минимум два файла: один основной, другой для вывода на печать.

  * ''<dokuwiki>/lib/tpl/<template>/''
    * ''<filename>.css''
    * ''[[.:templates:main.php]]'' ([[devel:templates:main.php|англ.]]) --- главный файл разметки шаблона «Докувики»
    * ''[[.:templates:detail.php]]'' ([[devel:templates:detail.php|англ.]]) --- страница подробного описания изображения
    * ''[[.:templates:mediamanager.php]]'' ([[devel:templates:mediamanager.php|англ.]]) --- медиаменеджер
    * ''images/'' --- все используемые в шаблоне изображения
    * ''conf/''
      * ''default.php'' --- [[.:configuration#настройки_по_умолчанию|стандартные настройки]] (см. ''[[#tpl_getConf]]'')
      * ''metadata.php'' --- [[.:configuration#метаданные_настроек|конфигурационные метаданные]] (см. ''[[#tpl_getConf()]]'')
    * ''lang/'' --- языковые файлы
      * ''<код языка>/lang.php'' --- локализованные строки, используемые в шаблоне
      * ''<код языка>/settings.php'' --- локализованные строки, используемые на странице настроек «Докувики»
    * ''style.ini'' --- см. [[.:css#style.ini]]


===== Функции =====

Список доступных функций вы можете найти здесь: [[xref>inc/template.php|API documentation]]. Самые важные приведены ниже.


==== tpl_content() ====

Эта функция выводит тело страницы, другими словами, всё содержимое страницы, включая [[..:toc|содержание]] (TOC). Вы можете отключить вывод содержания вызовом функции с параметром ''false'':

<code php>
tpl_content(false);
</code>

Такой приём может использоваться для размещения содержания в другой части экрана. См. функцию ''[[#tpl_toc()]]''.


==== tpl_toc() ====

По умолчанию, функция ''[[#tpl_content()]]'' сама позаботится о выводе [[..:TOC|содержания]], приводя его в актуальное состояние. Если ваш шаблон использует боковую колонку или более сложную компоновку, у вас может появится желание разместить содержание независимо от содержимого страницы. Это можно сделать функцией ''tpl_toc()''. При её использовании важно запретить автоматическое размещение содержания вызовом функции ''tpl_content()'' с аргументом ''false''.

**Пример:**

<code php>
<div id="content">
    <?php tpl_content(false)?>
</div>

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

Функция ''tpl_toc()'' формирует содержание на основе трёх различных источников: глобальной переменной [[..:devel:environment#$TOC]], [[..:metadata|метаданных]] страницы  или метода [[..:devel:admin plugins|административных плагинов]] ''getTOC()''. В случае, когда нет доступных [[..:metadata|метаданных]] старых ревизий или предварительных просмотров, ''tpl_toc()'' может использовать только глобальную переменную [[..:devel:environment#$TOC]]. Если же [[..:devel:environment#$TOC]] перезаписана формирователем страницы, то ''tpl_toc()'' будет работать только при условии её вызова **после** ''tpl_content()''. Если подобное невозможно разметке вашего шаблона, вы можете использовать буферизацию вывода для обхода этой проблемы.

**Пример:**

<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>


==== tpl_getConf() ====

Функция используется для доступа к [[..:devel:configuration|конфигурационным параметрам]] из шаблона.


===== Глобальные переменные и константы =====

Полный список глобальных переменных и констант вы можете найти на странице «[[..:devel:environment|Окружение]]».


===== Автоматизация служебных операций =====

Почти в самом конце страницы ''[[..:devel:templates:main.php]]'' стандартного шаблона вы можете увидеть вызов функции ''tpl_indexerWebBug()''. Данная функция генерирует HTML-тег ''<img>'', который является результатом запроса к скрипту ''[[..:indexer|lib/exe/taskrunner.php]]''. Эта необходимая составляющая часть «Докувики» выполняет важные служебные функции, обеспечивающие правильную работу системы. Все шаблоны должны включать в себя эту функцию, без неё работа вики может быть нарушена (к примеру, [[..:search|поисковые индексы]] перестанут создаваться)


===== Класс «dokuwiki» =====

Следует добавить класс ''dokuwiki'' к некоторым «окружающим контент» элементам (либо вокруг всего текста, либо по крайней мере, вокруг ''tpl_content()'') в каждом из шаблонов ''main.php'', ''detail.php'' и ''mediamanager.php''. Это необходимо для того, чтобы быть уверенным в том, что стили «Докувики» не пересекаются с другими стилями при интеграции с существующим сайтом, содержащим потенциально конфликтующие CSS. 


===== Включаемые блоки =====

Включаемые блоки --- простой путь добавления различного статического контента в вашу «Докувики» без создания собственного [[..:template|шаблона]]. Вы можете использовать их для добавления стандартного заголовка или логотипа компании на каждую страницу, либо же для размещения информации об отказе от ответственности внизу страницы.

Стандартный шаблон «Докувики» ищет файлы со специальными именами в каталоге ''lib/tpl/default/'' и просто включает их в определённые места при отображении страницы. Вы вольны добавить любой HTML-код в эти файлы. Конечно, работать это будет лишь при использовании //стандартного// шаблона.

**Совет** для PHP-разработчиков: вам, вероятно, будет приятно узнать, что в этих файлах можно использовать и PHP-скрипты.


==== Доступные блоки ====

Все файлы размещаются в каталоге ''lib/tpl/default/''

^ Имя файла           ^ Позиция включения     ^
| ''meta.html''       | Внутри HTML-тега %%<head>%%, используйте для подключения дополнительных таблиц стилей или метазаголовков |
| ''topheader.html''  | В самом верху страницы, сразу после тега %%<body>%% |
| ''header.html''     | Выше верхней синей панели, ниже названия страницы и заголовка вики |
| ''pageheader.html'' | Ниже полоски посещенных страниц, выше основного содержания страницы |
| ''pagefooter.html'' | Выше нижней голубой панели, ниже отметки о последнем изменении |
| ''footer.html''     | В самом низу страницы, перед тегом %%</body>%% |

«Докувики» поставляется с образцом файла ''footer.html'', содержащим кнопки лицензии «Creative Commons RDF».