Различия

Показаны различия между двумя версиями страницы.

--- ru:devel:templates [2009-08-07 14:02] – 195.78.91.218
+++ ru:devel:templates [2022-10-20 18:02] (текущий) – Klap-in
@@ Строка 1: / Строка 1: @@
-====== Разработка шаблонов DokuWiki ======
+====== Разработка шаблонов «Докувики» ======
+:!: Страница нуждается в переработке. За точной информацией обращайтесь к [[devel:templates|английской версии страницы]]. :!:
+Вы можете менять дизайн «[[..:dokuwiki|Докувики]]» по своему усмотрению, создав новый шаблон, который представляет собой несколько PHP- и CSS-файлов, сохранённых в каталоге и помещённых в ''<dokuwiki>/lib/tpl/'' (в действительности, шаблон написан на HTML, а PHP используется только для вставки контента).
-Вы можете менять дизайн [[:DokuWiki]] по своему усмотрению, создав новый шаблон, который представляет собой несколько PHP и CSS файлов, сохраненных в каталоге и помещенных в ''<dokuwiki>/lib/tpl/'' (в действительности, шаблон написан на HTML, а PHP используется только для вставки контента).
 ===== Начало работы =====
-Проще всего создать новый шаблон, взяв в качестве отправной точки уже существующий. Лучше всего подойдет шаблон default, так как он содержит все необходимые части шаблона и следует стандартам составления шаблонов DokuWiki. Имена шаблонов (директорой) следует писать в нижнем регистре без символов точки и подчеркивания.
+Проще всего создать новый шаблон, взяв в качестве отправной точки уже существующий. Лучше всего подойдет шаблон «default», так как он содержит все необходимые части шаблона и следует стандартам составления шаблонов «Докувики». Название шаблона (каталога) следует писать в нижнем регистре без символов точки и подчеркивания.
+  - Скопируйте стандартный шаблон ''lib/tpl/default'' в каталог, где будет хранится ваш шаблон, например ''lib/tpl/mytemplate'';
+  - Выберите новый шаблон на странице «Управление»;
+  - Ознакомьтесь с файлами шаблона (см. «[[templates#структура каталогов|Структуру каталогов]]»);
+  - Посмотрите, как «Докувики» обрабатывает CSS с помощью [[..:devel:css|диспетчера CSS]];
+  - Обработка конфигурационных параметров аналогична [[common_plugin_functions|плагинам]]. Используйте ''%%tpl_getConf(<setting>)%%'' для получения параметров шаблона.
-  - Скопируйте стандартный шаблон lib/tpl/default в директорию, где будет хранится Ваш шаблон, например lib/tpl/mytemplate
-  - Выберите новый шаблон на странице "Управление"
-  - Ознакомьтесь с файлами шаблона (см. [[ru:devel:templates#структура каталогов|Структура каталогов]])
-  - Посмотрите как [[:DokuWiki]] обрабатывает CSS с помощью [[devel:css|диспетчера CSS]]
-  - Обработка конфигурационных параметров аналогична [[devel:common_plugin_functions|плагинам]]. Используйте ''%%tpl_getConf(<setting>)%%'' для получения параметров шаблона.
 ===== Структура каталогов =====
-Шаблоны должны иметь следующую структуру директорий (все пути указаны относительно каталога шаблона). Файлы CSS определены в ''[[devel:CSS#style.ini]]'', но вам следует предоставить как минимум два файла: один основной, другой для вывода на печать.
+Шаблоны должны иметь следующую структуру директорий (все пути указаны относительно каталога шаблона). Файлы CSS определены в ''[[CSS#style.ini]]'', но вам следует предоставить как минимум два файла: один основной, другой для вывода на печать.
   * ''<dokuwiki>/lib/tpl/<template>/''
     * ''<filename>.css''
-    * ''[[devel:templates:main.php]]'' -- главный файл разметки шаблона DokuWiki
+    * ''[[.:templates:main.php]]'' ([[devel:templates:main.php|англ.]]) --- главный файл разметки шаблона «Докувики»
-    * ''[[devel:templates:detail.php]]'' -- страница подробного описания изображения
+    * ''[[.:templates:detail.php]]'' ([[devel:templates:detail.php|англ.]]) --- страница подробного описания изображения
-    * ''[[devel:templates:mediamanager.php]]'' -- мультимедия загрузчик
+    * ''[[.:templates:mediamanager.php]]'' ([[devel:templates:mediamanager.php|англ.]]) --- медиаменеджер
-    * ''images/'' -- все используемые в шаблоне изображения
+    * ''images/'' --- все используемые в шаблоне изображения
     * ''conf/''
-      * ''default.php'' -- [[devel:configuration#default settings|стандартные настройки]] (см. ''[[#tpl_getConf]]'')
+      * ''default.php'' --- [[.:configuration#настройки_по_умолчанию|стандартные настройки]] (см. ''[[#tpl_getConf]]'')
-      * ''metadata.php'' -- [[devel:configuration#configuration metadata|конфигурационные метаданные]] (см. ''[[#tpl_getConf()]]'')
+      * ''metadata.php'' --- [[.:configuration#метаданные_настроек|конфигурационные метаданные]] (см. ''[[#tpl_getConf()]]'')
-    * ''lang/'' -- языковые файлы
+    * ''lang/'' --- языковые файлы
-      * ''<код языка>/lang.php'' -- локализованные строки, используемые в шаблоне
+      * ''<код языка>/lang.php'' --- локализованные строки, используемые в шаблоне
-      * ''<код языка>/settings.php'' -- локализованные строки, используемые на странице настроек DokuWiki
+      * ''<код языка>/settings.php'' --- локализованные строки, используемые на странице настроек «Докувики»
-    * ''style.ini'' -- см. [[devel:CSS#Style.ini]]
+    * ''style.ini'' --- см. [[.:css#style.ini]]
 ===== Функции =====
-Список доступных функций вы можете найти здесь: [[http://dev.splitbrain.org/reference/dokuwiki/nav.html?inc/template.php.html|API documentation]]. Самые важные приведены ниже.
+Список доступных функций вы можете найти здесь: [[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».