| |
| devel:templates [2023/09/02 17:37] – создано vladpolskiy | devel:templates [Дата неизвестна] (текущий) – удалено - внешнее изменение (Дата неизвестна) 127.0.0.1 |
|---|
| ====== Разработка шаблонов «Докувики» ====== | |
| |
| :!: Страница нуждается в переработке. За точной информацией обращайтесь к [[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». | |
| https://www.dokuwiki.org/ru:devel:templates | |
