worldwide open-source software - wiki:devel

action_modes

anonymous@undisclosed.example.com (Anonymous) — Sat, 02 Sep 2023 14:36:23 +0000

Режимы действий, они же режимы do

Список возможных режимов действий (возможно еще не полный) с их описанием. Эти действия обычно определяются параметром ?do=, переданным диспетчеру doku.php. Знание текущего режима может быть полезно для создания более динамических шаблонов или написания плагинов действий. Текущий режим может быть доступен через глобальную переменную $ACT.

Действия со статьями

Процесс редактирования

show — действие по умолчанию, если никакое действие не указано, используется это. Это действие просто вызывает отображение текущей статьи.
edit — загружает текущую статью в окно редактора вместо отображения.
source — просмотр исходного текста страницы (часто используется при недостатке прав на редактирование).
preview — тоже самое, что и предыдущее, но кроме того показывает предварительное изображение статьи под окном редактора.
save — используется для сохранения текущей статьи, после сохранения осуществляется перенаправление в режим show. Вы никогда не должны использовать этот режим в своих шаблонах
conflict — внутренний режим. Сообщает о возникновении конфликта при сохранении статьи.
cancel — используется для возвращения отредактированного текста в исходное состояние при возникновении конфликта (ошибки) - после этого текущая статья отображается вновь.
denied — внутренний режим. Используется для загрузки сообщения об отказе в доступе.
locked — внутренний режим. Используется для отображения сообщения о блокировке статьи.
wordblock — внутренний режим. Отображает сообщение о блокировании спама.

Действия с черновиком

draft — отображает черновик текущей статьи.
draftdel — удаляет черновик текущей статьи, после чего активирует режим отображения текущей статьи (show mode).
recover — восстанавливает текст вики из черновика текущей статьи и загружает его в редактор.

Различные представления содержимого статьи

export_raw — экспорт (например в текстовый файл) в виде разметки вики.
export_xhtml — экспорт в виде XHTML.
export_xhtmlbody — экспорт только тела XHTML.

Другие функции

subscribe — добавляет текущего пользователя в список email-рассылки об изменениях текущей статьи.
backlink — показывает список статей, в которых есть ссылки на текущую статью.
revisions — показывает изменения и их авторов текущей статьи.
revert — откатывает страницу, в режиме show - на прошлую ревизию, в режиме diff - на раннюю из выбранных.
diff — генерирует отображение diff для удобного сравнения двух ревизий статьи.

Действия с сайтом

Основные функции

index — показывает автоматически составленный индекс статей и пространств имён.
sitemap — отдаёт (возвращает) карту сайта поисковому движку в зависимости от значения параметра «sitemap» (не применимо к шаблонам).
recent — отображает список с последними измененными статьями и позволяет показать diff.
search — функциональность поиска.
media — менеджер файлов (Media Manager)

Связанные с ACL (списком контроля доступа)

register — регистрация нового пользователя.
login — вход пользователя в систему.
logout — выход пользователя из системы.
profile — работа с профилем пользователя.
resendpwd — отправляет электронное письмо с паролем пользователя на указанный им ранее адрес.
admin — отображает меню администратора со всеми инсталлированными плагинами администрирования; доступен для залогиненных суперпользователей или менеджеров.

Другие функции

check — снимает дамп с информацией о правах пользователя и установке «ДокуВики».
debug — снимает дамп с отладочной информацией (доступна только при включённой опции «allowdebug»).

action_plugins

anonymous@undisclosed.example.com (Anonymous) — Wed, 14 Aug 2024 22:53:02 +0000

Action Plugins

Action Plugins предназначены, чтобы работать с событиями Dokuwiki и иметь возможность добавить свой расширеный функционал в любой части Dokuwiki.

Описание

Action plugins загружаются до того, как вики делает что-либо значительное. Сразу же после загрузки, вики вызывает метод register() каждого плагина для того чтобы дать ему возможность зарегистрировать свои обработчики событий. Когда происходит некоторое событие, все зарегистрированные на него обработчики вызываются по очереди (в произвольном порядке) и им передается по ссылке объект события. Обработчик получает возможность выполнить какое-либо действие на основании данных, хранящихся в этом объекте, модифицировать эти данные или повлиять на дальнейшую обработку события. На странице events можно узнать больше о том, как устроена система событий, а также просмотреть их полный список.

Техническое описание

Action plugins используют такой же основной формат и правила наименоваения, как и другие типы плагинов для Dokuwiki.

каждый плагин должен располагаться в собственной директории внутри каталога lib/plugins
скрипт плагина должен называться action.php, или должен располагаться в подкаталоге action, и тогда называться как угодно, смотрите файловую структуру.
плагин должен содержать один класс action_plugin_<plugin name> как расширение базового классаDokuWiki_Action_Plugin, который можно найти в lib/plugins/action.php. Если файл плагина располагается в подкаталоге action, тогда класс необходимо назвать action_plugin_<plugin name>_<action plugin filename> (где action_plugin_filename не должно содержать расширение '.php').
плагин поддерживает стандартные introspection, локализации и конфигурации через базовый класс DokuWiki_Plugin, который располагается в файле inc/plugin.php, смотрите Встроенные функции плагина.
плагин должен иметь два метода, getInfo() и register().
внешние библиотеки могут быть загружены в тот момент, когда это необходимо плагину или в конструкторе, но не в самом начале файла

getInfo()

!!! Теперь вместо неё прилагается отдельный файл plugin.info.txt !!!

обязательный

    function getInfo(){
      return array(
        'author' => '<имя автора плагина>',
        'email'  => '<контактный e-mail автора плагина>',
        'date'   => '<дата версии плагина>',
        'name'   => '<название плагина>',
        'desc'   => '<описание плагина (поддерживается многострочие)',
        'url'    => '<домашная страничка плагина: ссылка, где можно найти информацию по плагину>',
      );
    }

register()

обязательный

    /**
     * plugin should use this method to register its handlers with the dokuwiki's event controller
     *
     * @param    $controller   Dokuwiki's event controller object. Also available as global $EVENT_HANDLER
     *
     * @return   not required
     */
    function register(Doku_Event_Handler $controller) {
      $controller->register_hook(<EVENT NAME>, <EVENT ADVISE>, $this, <event handler function>, <parameters to be passed to event handler>);
    }

<event handler>()

необязательный их может быть любое количество; может быть назван любым именем, которое не используется этим плагином или его предками

    /**
     * custom event handler
     *
     * @param    $param   (mixed)   the parameters passed to register_hook when this handler was registered
     * @param    $event   (object)  event object by reference
     *
     * @return   not required
     */
    function <event_handler>(&$event, $param) {
      // custom script statements ...
    }

Examples

Action plugins are a way to modify many aspects of how DokuWiki behaves in certain cases independent of a page's syntax. To be able to modify a DokuWiki internal behavior it needs to trigger an event. Your action plugin can register as a handler for such an event and then work with the given event data.

To learn more about events, read the following pages:

Sample action plugin 1

Insert a javascript script link in all pages.

Register the TPL_METAHEADER_OUTPUT event, with a before EVENT_ADVISE.
Add javascript information to «script» meta headers as array type.

action.php

<?php
/**
 * Example Action Plugin:   Example Component.
 * 
 * @author     Samuele Tognini <samuele@cli.di.unipi.it>
 */
 
if(!defined('DOKU_INC')) die();
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'action.php');
 
class action_plugin_example extends DokuWiki_Action_Plugin {
 
  /**
   * return some info
   */
  function getInfo(){
    return array(
		 'author' => 'Me name',
		 'email'  => 'myname@example.org',
		 'date'   => '2006-12-17',
		 'name'   => 'Example (action plugin component)',
		 'desc'   => 'Example action functions.',
		 'url'    => 'http://www.example.org',
		 );
  }
 
  /**
   * Register its handlers with the dokuwiki's event controller
   */
  function register(Doku_Event_Handler $controller) {
    $controller->register_hook('TPL_METAHEADER_OUTPUT', 'BEFORE',  $this, '_hookjs');
  }
 
  /**
   * Hook js script into page headers.
   *
   * @author Samuele Tognini <samuele@cli.di.unipi.it>
   */
  function _hookjs(&$event, $param) {
	$event->data["script"][] = array ("type" => "text/javascript",
                                          "charset" => "utf-8",
					  "_data" => "",
					  "src" => DOKU_BASE."lib/plugins/example/example.js"
				          );
  }
}

Sample Action Plugin 2

Inserts a button into the editor toolbar:

registers as handler for the TOOLBAR_DEFINE event with an AFTER advise
adds a button definition to the event's data

action.php

<?php
/**
 * Example Action Plugin: Inserts a button into the toolbar
 *
 * @author Gina Haeussge <osd@foosel.net>
 */
 
if (!defined('DOKU_INC')) die();
if (!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN', DOKU_INC . 'lib/plugins/');
require_once (DOKU_PLUGIN . 'action.php');
 
class action_plugin_actionexample extends DokuWiki_Action_Plugin {
 
    /**
     * Return some info
     */
    function getInfo() {
        return array (
            'author' => 'Some name',
            'email' => 'foo@bar.org',
            'date' => '2007-04-05',
            'name' => 'Toolbar Action Plugin',
            'desc' => 'Inserts a button into the toolbar',
            'url' => 'http://www.example.com/plugin/toolbar',
        );
    }
 
    /**
     * Register the eventhandlers
     */
    function register(Doku_Event_Handler $controller) {
        $controller->register_hook('TOOLBAR_DEFINE', 'AFTER', $this, 'insert_button', array ());
    }
 
    /**
     * Inserts the toolbar button
     */
    function insert_button(& $event, $param) {
        global $lang;
        global $conf;
        include_once (dirname(__FILE__) . '/lang/en/lang.php');
        @ include_once (dirname(__FILE__) . '/lang/' . $conf['lang'] . '/lang.php');
 
        $event->data[] = array (
            'type' => 'format',
            'title' => $lang['qb_abutton'],
            'icon' => '../../plugins/actionexample/abutton.png',
            'open' => '<abutton>',
            'close' => '</abutton>',
        );
    }
 
}

https://www.dokuwiki.org/wiki:devel:action_plugins

caching

anonymous@undisclosed.example.com (Anonymous) — Sun, 16 Feb 2025 19:02:58 +0000

Кэширование

«ДокуВики» ускоряет просмотр статей с помощью кэширования разобранных файлов¹⁾. Если существует актуальная скэшированная версия документа, то будет доставлена именно эта скэшированная копия вместо того, чтобы разбирать все данные заново. При редактировании и предпросмотре никакого кэширования не применяется.

Очистка кэша

Для принудительной очистки кэша отдельной статьи добавьте к её URL параметр purge. Например:

http://www.example.com/namespace/page?purge=true

Для принудительной очистки кэша всех статей, включая страницы инструкций, примените команду touch к локальному файлу конфигурации conf/local.php²⁾.

Для принудительной очистки кэша только xhtml-страниц, примените touch к inc/parser/xhtml.php.

Двухстадийное кэширование

«ДокуВики» использует два файла кэша для каждой статьи. Для того, чтобы понять это, вы должны знать, что статья до того, как быть отображенной в XHTML, сначала разбирается в промежуточный формат инструкций. «ДокуВики» сохраняет в кэше оба представления — и инструкции и подготовленный XHTML.

Кэш инструкций
Файл кэша инструкций подвергается обновлению только при изменений статьи, конфигурационных файлов³⁾, некоторых php-файлов «ДокуВики»⁴⁾ или при добавлении/удалении/включении/выключении плагина с помощью менеджера плагинов.
Кэш XHTML
На кэш XHTML кроме перечисленного выше влияет опция максимального возраста кэша (cachetime), собственные метаданные, некоторые другие php-файлы ⁵⁾, то существует или не существует цель внутренней ссылки, и то, что рассылка RSS требует обновления.

Размещение

Кэши XHTML и инструкций располагаются в директориях data/cache/*⁶⁾. Файлы завершаются суффиксами .xhtml, .i. В директории кэша также хранятся и другие файлы:

.feed — различные рассылки RSS, сгенерированные для вики;
.code — порции статей между тэгами <code> ... </code> после применения синтаксической подсветки.

Плагины

Плагины теперь могут влиять на кэш через событие PARSER_CACHE_USE. Это позволяет плагинам, которые вносят дополнительные зависимости в определённые статьи, проверить эти зависимости и принудить «ДокуВики» обновить статью, если эти зависимости нарушены.

Замечание разработчику

До сих пор единственную возможность, которую имел разработчик для отключения кэширования, — это отключить его полностью. Это было необходимо для таких плагинов как «Discussion» и «Include».

Для того, чтобы использовать новую функциональность, синтаксические плагины должны:

сохранять информацию, относящуюся к статьям, затрагиваемым ими, и зависимостям, специфичным для каждой из этих статей. Метаданные статьи являются удобным местом для этого. Доступ к метаданным может быть получен с помощью массива $INFO['metadata'] и функций p_get_metadata() и p_set_metadata(). Если вы используете метаданные, пожалуйста, обратитесь к Dublin Core Metadata standards.
добавить компонент плагина действий для работы с событием PARSER_CACHE_USE.

Сам кэш управляется с помощью кэширующего объекта⁷⁾. Основными частями этого объекта интересными для плагина являются:

массив depends — «ДокуВики» заполняет его всеми известными зависимостями статьи и затем использует стандартные процедуры для работы с ним. Плагины могут добавлять и изменять эти зависимости до того, как они обработаны. Различными видами зависимостей являются:
- purge — очистить кэш;
- age — очистить кэш, если он старее, чем назначенный возраст (зависящий от значения метаданных 'date valid');
- files — очистить кэш, если он старее любого файла, указанного в этом массиве. Могут быть добавлены только локальные файлы. Загляните в inc/cache.php за списком таких файлов. Возможно наиболее интересно, что скэшированный xhtml зависит от метаданных статьи.
имя кэша, cache — уникальный идентификатор, под которым храниться кэш. Обычно зависит от имени статьи, HTTP_HOST и номера порта сервера. Плагины могут составлять более сложные идентификаторы, например, «Include» составляет идентификатор, используя имена включаемых статей и имеет или не имеет текущий пользователь права на чтение данных статей.

Индивидуальной очистка кэша отдельной статьи

Как описано выше, «ДокуВики» проверяет валидность кэша, а не активно сбрасывает кэш. Однако, xhtml-представление статьи зависит от метаданных. То есть, если файл метаданных более свежий, чем кэш, «ДокуВики» определит, что кэш невалиден, и перерендерит (пересоздаст) статью. Таким образом, мы можем обновить метаданные для того, чтобы сбросить кэш.

/* code to expire the cached xhtml of page ns:page
 * $id = 'ns:page';
 * $data = array('cache' => 'expire');  // the metadata being added
 * $render = false;                     // no need to re-render metadata now
 * $persistent = false;                 // this change doesn't need to persist passed the next metadata render.
 */
p_set_metadata($id, $data, $render, $persistent);

¹⁾

По поводу кэширования изображений см. статью «Работа с изображениями и медиафайлами».

²⁾

Не-UNIX-овые пользователи могут просто открыть этот файл и сохранить его заново — смысл состоит в том, чтобы изменить метку времени изменения файла.

³⁾

conf/dokuwiki.php и conf/local.php.

⁴⁾

inc/parser/parser.php и inc/parser/handler.php/

⁵⁾

inc/parser/xhtml & inc/parser/metadata

⁶⁾

где * — односимвольное название директории, а data — настраивается в опции «savedir»

⁷⁾

inc/cache.php

callgraph

anonymous@undisclosed.example.com (Anonymous) — Thu, 17 Aug 2023 10:06:46 +0000

Callgraph

Следующее изображение (щелкните, чтобы увеличить) должно дать вам первое, очень грубое представление о том, как страница отображается в «ДокуВики». Образ был создан из вывода xdebug, обработанного с помощью kcachegrind. Отображаются только вызовы с использованием не менее 1% времени всего процесса.

common_plugin_functions

anonymous@undisclosed.example.com (Anonymous) — Thu, 09 Jan 2025 19:41:29 +0000

Основные функции плагинов

Каждый из реализованных в настоящие время классов плагинов DokuWiki: синтаксические, администрирования, действий, вспомонгательные и рендеров предоставляет общий набор методов и свойств, осуществляющих стандартные возможности по настройке, самоанализу, локализации и выводу. Эти функции выдают результаты, принимая во внимание локальную конфигурацию и специфичные для DokuWiki требования.

Эти функции объявлены в фундаментальном классе плагинов, DokuWiki_Plugin, определенном в файле inc/plugin.php.

Краткое описание этих функций и свойств приведен ниже. Наиболее полное и свежее описание можно найти в файле base.php из API Reference, а также сами исходники можно найти в Source Repository

Настройки

$conf — Массив содержащий конфигурационный настройки, в виде setting ⇒ value. Пуст пока не будет наполнен функцией loadConfig().
$configloaded — логическая переменная, выставляется в true функцией loadConfig() после того, как она установит текущие настройки.
getConf($setting) — возвращает значение настройки $setting, при необходимости вызовет loadConfig().
loadConfig() — сливает локальные настройки и дефолтные настройки плагина и заполняет массив $this→conf.
readDefaultSettings() — читает файл настроек по умолчанию, lib/plugins/<plugin_name>/conf/default.php.

Настройки конфигурации конкретного плагина хранятся в файле локальных настроек local.php и в файле специфичном для данного плагина default.php (см. структура файлов плагина).

Если плагин работает со своими настройками с помощью этих функций, то администратор wiki сможет интерактивно управлять настройками с помощью Менеджера конфигурации. О том как сказать Менеджеру конфигурации, что делать с вашими настройками, смотри Configuration Metadata.

Самоанализ

getPluginType() — возвращает тип плагина, т.е. syntax, admin or action.
getPluginName() — возвращает имя плагина.
getPluginComponent() — возвращает имя компонента плагина.

Локализация

О том, где хранятся локализованные строки и файлы, см. плагин plugin_file_structure.

$lang — Массив содержащий локализованные строки плагина, в виде id ⇒ localised string, может содержать английские строки, в случае, если локализованной версии не существует. Пуст пока не будет заполнен функцией setupLocale().
$localised — логическая переменная, выставляется в true функцией setupLocale() после того, как она заполнит массив $this→lang.
getLang($id) — возвращает локализованную строку соответствующую $id, или английскую строку если локализованная версия отсутствует. При необходимости вызовет функцию setupLocale().
locale_xhtml($id) — использует движок рендеринга DokuWiki, для того чтобы возвратить xhtml, созданный из локализованного файла $id, содержащий разметку DokuWiki.
setupLocale() — заполняет массив $this→lang в соответствии с настройками локализации.

Вывод

email() — выводит ссылку на адрес почты в соответствии с текущими настройками «шифрации».
external_link() — выводит внешнюю ссылку в соответствии с текущими настройками target.
render() — применяет парсер для того, чтобы разобрать и вывести строку содержащую разметку wiki.

См.также https://www.dokuwiki.org/ru:devel:common_plugin_functions?do=edit

configuration

anonymous@undisclosed.example.com (Anonymous) — Fri, 03 Jan 2025 13:55:03 +0000

Конфигурация

DokuWiki позволяет создавать очень гибкие плагины и шаблоны делая их легко настраиваемыми..

Default Settings

Чтобы сделать плагин или шаблон настраиваемым, необходимо предоставить lib/plugins/<plugin>/conf/default.php который будет содержать настройки по умолчанию, и lib/plugins/<plugin>/conf/metadata.php который содержит описывающие метаданные конфигурации используемые диспетчером конфигурации для обработки/отображения параметров ¹⁾.

$conf[<setting>] = <value>;

Конфигурационные метаданные

Для каждого параметра lib/plugins/<your plugin>/conf/default.php должно быть $meta[<setting>] значение, определенное в lib/plugins/<your plugin>/conf/metadata.php²⁾:

$meta[<setting>] = array(<setting class>, <param name> => <param value>);

Если для класса настроек не требуется никаких параметров (см. ниже), то это просто:

$meta[<setting>] = array(<setting class>);

Примеры:

$meta['_basic']     = array('fieldset');
$meta['title']      = array('string');
$meta['lang']       = array('dirchoice','_dir' => DOKU_INC.'inc/lang/');
$meta['dmode']      = array('numeric','_pattern' => '/0[0-7]{3,4}/'); // only accept octal representation
$meta['allowdebug'] = array('onoff');
$meta['passcrypt']  = array('multichoice','_choices' => array('smd5','md5','sha1','ssha','crypt','mysql','my411'));

Классы

`''`	DКласс по умолчанию («настройка»), текстовая область, минимальная проверка входных данных, вывод настроек в кавычках.
`'string'`	Ввод текста в одну строку, минимальная проверка ввода, вывод в кавычках.
`'numeric'`	Ввод текста, принимает числа и арифметические операторы, установка вывода без кавычек. Если заданы параметры `_min` и `_max` используются для проверки.
`'numericopt'`	То же, что и выше, но принимает пустые значения.
`'onoff'`	Входные данные флажка, выходные данные настройки `0` или `1` (обратите внимание, что значения по умолчанию должны быть одним из этих целых чисел, а не логическим значением)..
`'multichoice'`	Выберите входные данные (единственный выбор), установите выходные данные в кавычках, обязательный `_choices` параметр.
`'email'`	Ввод текста, ввод должен соответствовать формату адреса электронной почты, вывод должен быть заключен в кавычки.
`'password'`	Ввод пароля, минимальная проверка ввода, настройка вывода обычного текста в кавычках. После установки пароль больше не отображается в менеджере конфигурации. Может быть запутан в конфигурации через `_code` параметр.
`'dirchoice'`	Как `multichoice`, варианты выбора основаны на папках, найденных в месте, указанном в `_dir` параметре (обязательно).
`'multicheckbox'`	Флажок для каждого варианта плюс строковый ввод «другое», настройка файла конфигурации представляет собой список отмеченных вариантов, разделенных запятыми.
`'fieldset'`	Используется для группировки настроек конфигурации, но сам по себе не является настройкой. Чтобы это было понятно в языковых файлах, ключи для этого типа должны начинаться с `_`.
`'authtype'`	Создает выборку доступных методов аутентификации на основе имен классов, `inc/auth` соответствующих шаблону `authtype.class.php`.
`'array'`	простой (одномерный) массив строковых значений, отображаемый в виде списка, разделенного запятыми, в диспетчере конфигурации, но сохраняемый как PHP array(). Значения не могут содержать запятые. `_patter` nподдерживается сопоставление значений массива.
`'regex'`	Строка регулярного выражения, обычно без разделителей; как и для `string`, дополнительно протестировано, чтобы увидеть, будет ли компилироваться и запускаться как регулярное выражение. В дополнение к `_pattern`, также принимает `_delimiter` (default `/`) и `_pregflags` (default `ui`).

Параметры

`'_pattern'`	Строка, регулярное выражение. Ввод проверяется на соответствие этому шаблону перед принятием. Необязательно для всех классов, кроме `onoff`, `multichoice` и `dirchoice` которые его игнорируют.
`'_choices'`	Массив вариантов выбора. Используется для заполнения поля выбора. Выбор будет заменен локализованной языковой строкой, индексированной по `<setting name>_o_<choice>`, если она существует. Требуется для `multichoice` & `multicheckbox` классов, игнорируется другими.
`'_dir'`	Расположение каталога, который будет использоваться для заполнения списка выбора. Требуется `dirchoice` классом, игнорируется другими классами.
`'_code'`	Устанавливает опцию запутывания для полей пароля. Может быть `plain`, `base64` или `uuencode`. При использовании последних двух вам необходимо использовать conf_decodeString() для доступа к простому значению..
`'_combine'`	Дополнительные выходные значения настроек, которые можно объединить в один дисплей `checkbox.` Необязательно для `multicheckbox`, игнорируется другими классами.
`'_code'`	Метод кодирования, допустимые значения: `base64`, `uuencode`, `plain`. По умолчанию — обычный.
`'_min'`	Минимальное числовое значение. Необязательно для `numeric` и `numericopt`, игнорируется другими.
`'_max'`	Максимальное числовое значение. Необязательно для `numeric` и `numericopt`, игнорируется другими.
`'_delimiter'`	Строка, по умолчанию `/` — один символ, используемый в качестве разделителя для проверки входных значений регулярного выражения.
`'_pregflags'`	Строка, по умолчанию `ui`, допустимые модификаторы шаблона preg, используемые при тестировании входных значений регулярных выражений, для получения дополнительной информации см. http://uk1.php.net/manual/en/reference.pcre.pattern.modifiers.php.
`'_multiple'`	Bool, разрешить несколько значений email, разделенных запятыми. Необязательно для `email`, игнорируется другими.
`'_other'`	Как обрабатывать другие значения (не перечисленные в `_choices`). Принятые значения: `always`, `exists`, `never`. Значение по умолчанию `always`. `exists` показывает поле ввода «другое», только если настройка содержит значение(я), не перечисленное в вариантах (например, из-за ручного редактирования или обновления, изменяющегоg `_choices`). Это безопаснее, чем `never` так как не отбрасывает неизвестные/другие значения. Необязательно для `multicheckbox`, игнорируется другими.

Примеры

''multicheckbox'' с ''_other''

Предположим, изначально плагин использует следующий синтаксис:x:

$meta['multi'] = array('multicheckbox', '_choices' => array('a','b','c','d'));

это означает, что в поле с несколькими флажками будут отображаться четыре варианта выбора и строковое поле ввода.

Предположим также, что пользователь вставляет одно или несколько дополнительных значений, отсутствующих в _choices.

В следующем выпуске плагина авторский плагин решает использовать multicheckbox без дополнительной строки, но, в целях обратной совместимости, принимает:

$meta['multi'] = array('multicheckbox', '_other' => 'exists', '_choices' => array('a','b','c','d'));

что означает:

если пользователь ввел значения, разделенные запятыми, они будут напечатаны в дополнительной строке;
в противном случае дополнительная строка не будет отображаться.

Обратите внимание также, что если пользователь вставляет разделенные запятыми значения, которые уже существуют (или некоторые из них), в _choices:

они уже отмечены, то лишняя строка будет удалена и ничего больше;
если они еще не отмечены, то лишняя строка будет удалена и отмечено относительное значение.

Доступ к настройкам

Основные настройки

Внутри init.php настройки конфигурации считываются в глобальный массив $conf[]. Если настройки не заданы, они считываются из файла настроек по умолчанию. Вы можете получить доступ к основным настройкам в любом месте, используя $conf[] массив.

$startpage = $conf['start'];

Настройки плагина

Вы можете получить доступ к настройкам плагина используя $this-> getConf('<setting>') метод. В классе вашего плагина используете:

$keyvalue = $this->getConf('key');

Настройки шаблона

В шаблонах можно использовать tpl_getConf('<setting>').

$nicetoknow = tpl_getConf('special');

Метки в диспетчере конфигураций

Для каждого параметра в lib/plugins/<your plugin>/conf/default.php может быть $lang[<setting>] определено значение в lib/plugins/<your plugin>/lang/en/settings.php. Это значение будет отображаться как метка параметра в диспетчере конфигурации. Если файл метки пропущен или не содержит значения для параметра, диспетчер конфигурации отобразит «plugin <plugin name> <setting>» в качестве метки..

Вы также можете создать settings.php файл для других языков.

Опять же, это относится и к шаблонам (более подробную информацию см. в Локализация).

¹⁾

шаблоны аналогичны lib/tpl/<template>/conf/default.php и т.д.

²⁾

Для шаблонов все полностью аналогично: lib/tpl/<your template>/conf/default.phpи lib/tpl/<your template>/conf/metadata.php.

counter

anonymous@undisclosed.example.com (Anonymous) — Sat, 18 Jan 2025 22:19:48 +0000

Счетчик посещений сайта Dokuwiki

Простейший счетчик для сайта (подсчет посещения любой страницы) без базы данных. Существует масса способов реализации счетчика просмотров страницы на PHP и в основном они работают с базой данных. Но если вам нужно прикрутить по-быстрому к одной странице счетчик посещений, то этот скрипт будет вам полезен. БД он не использует, а создает текстовый файл, в котором и хранит информацию о количестве просмотров. И, как обычно, предлагаю посмотреть как это выглядит на фото или в низу станицы.

Код счетчика

PHP

<?php 
$file = file("count.txt");
$count = implode("", $file);
$count++;
$myfile = fopen("count.txt","w");
fputs($myfile,$count);
fclose($myfile);
?>
<span>Просмотров: <?=$count ?></span> // вывод счетчика

Править будем файл tpl_footer расположенный Dokuwiki\lib\tpl\dokuwiki с добавление стиля:

CSS

.container {
    position: absolute;
    font-family: Georgia, 'Times New Roman', Times, serif;
}
.text-block {
    position: absolute;
    bottom: 0px;
    right: 4px;
    color: black;
}

в файле tpl_footer добавляем в блок <div class="buttons"> нижеприведенный код PHP

PHP

        <a>
            <?php 
                $file = file("count.txt");
                $count = implode("", $file);
                $count++;
                $myfile = fopen("count.txt","w");
                fputs($myfile,$count);
                fclose($myfile);
            ?>
        <style>
            .container {
            position: absolute;
            font-family: Georgia, 'Times New Roman', Times, serif;
            }
            .text-block {
            position: absolute;
            bottom: 0px;
            right: 4px;
            color: black;
            }
        </style>
            <a class="container">
                <span><img src="<?php echo tpl_basedir(); ?>images/button-yandex.png" width="85" height="15" alt="yandex" / >
                    <div class="text-block"><?=$count ?></div>
                </span>
            </a>
        </a>

В папку с картинками загружаем нашу иконку с размером 80px x 12px. и в строке кода <img src="<?php echo tpl_basedir(); ?>images/button-yandex.png" width="85" height="15" alt="yandex" / > прописываем путь к картинке. В моем случае это папка с шаблонами/картинки/.

Я не стал стили (необходимы для наложения текста на картинку) выносить пока в отдельный файл, чтобы было все для примера в одном месте.
Тут добавлен блок-контейнер (<a class="container">) для позиционирования в основном блоке (<div class="buttons">) шаблона и добавления шрифта и цвета текста. $file = file("count.txt"); создает файл в корне Dokuwiki с записями о посещении страниц, при желании можете изменить ее расположение.

PHP

<?php
/**
 * Template footer, included in the main and detail files
 */
 
// must be run from within DokuWiki
if (!defined('DOKU_INC')) die();
?>
 
<!-- ********** FOOTER ********** -->
<footer id="dokuwiki__footer"><div class="pad">
    <div class="license">Если не указано иное, содержимое этой вики предоставляется на&nbsp;условиях следующей лицензии: <bdi><a href="doku.php?id=public_domain_mark" rel="license" class="urlextern">Public Domain</a></bdi></div>
 
    <div class="buttons">
        <a href="https://php.net" title="Powered by PHP" <?php echo $target?>><img
            src="<?php echo tpl_basedir(); ?>images/button-php.gif" width="80" height="15" alt="Powered by PHP" /></a>
        <a href="//validator.w3.org/check/referer" title="Valid HTML5" <?php echo $target?>><img
            src="<?php echo tpl_basedir(); ?>images/button-html5.png" width="80" height="15" alt="Valid HTML5" /></a>
        <a href="//jigsaw.w3.org/css-validator/check/referer?profile=css3" title="Valid CSS" <?php echo $target?>><img
            src="<?php echo tpl_basedir(); ?>images/button-css.png" width="80" height="15" alt="Valid CSS" /></a>
        <a href="https://dokuwiki.org/" title="Driven by DokuWiki" <?php echo $target?>><img
            src="<?php echo tpl_basedir(); ?>images/button-dw.png" width="80" height="15"
            alt="Driven by DokuWiki" /></a>
        <a>
            <?php 
                $file = file("count.txt");
                $count = implode("", $file);
                $count++;
                $myfile = fopen("count.txt","w");
                fputs($myfile,$count);
                fclose($myfile);
				$filename = file("stat.txt");
            ?>
        <style>
            .container {
            position: absolute;
            font-family: Georgia, 'Times New Roman', Times, serif;
            }
            .text-block {
            position: absolute;
            bottom: 0px;
            right: 4px;
            color: black;
            }
        </style>
            <a class="container">
                <span><img src="<?php echo tpl_basedir(); ?>images/button-yandex.png" width="85" height="15" alt="yandex" / >
                    <div class="text-block"><?=$count ?></div>
                </span>
            </a>
        </a>
    </div>
    <?php tpl_includeFile('footer.html'); ?>
	<?php
	    $client  = @$_SERVER['HTTP_CLIENT_IP'];
        $forward = @$_SERVER['HTTP_X_FORWARDED_FOR'];
        $remote  = @$_SERVER['REMOTE_ADDR']; // Определяем IP посетителя
        $bravo   = @$_SERVER["HTTP_USER_AGENT"];//Определяем браузер
            if(filter_var($client, FILTER_VALIDATE_IP)) $ip_address = $client;
            elseif(filter_var($forward, FILTER_VALIDATE_IP)) $ip_address = $forward;
            else $ip_address = $remote;
        $file2 = $_SERVER['DOCUMENT_ROOT'] . '/lib/tpl/dokuwiki/debug.txt';
        file_put_contents($file2, date("F d  H:i:s."). ('    ') . $ip_address . ('    ') . $bravo .  PHP_EOL, FILE_APPEND | LOCK_EX);
	?>
</div></footer><!-- /footer -->

или скачать файл ''tpl_footer'' целиком и поместить в папку Dokuwiki\lib\tpl\dokuwiki.
и нажав на картинку иконки сохранить как button-yandex.png в папке Dokuwiki\lib\tpl\dokuwiki\images.
У кого текст убегает, ловим его в стиле:

CSS

.container {
    position: absolute;
    font-family: Georgia, 'Times New Roman', Times, serif; //шрифт
}
.text-block {
    position: absolute;
    bottom: 0px;  //устанавливает положение нижнего края
    right: 4px;   //расстояние от правого края родительского элемента
    color: black; //цвет текста
}

Ну и все…Наслаждаемся.

Ссылка на источник кода

debugging

anonymous@undisclosed.example.com (Anonymous) — Thu, 31 Aug 2023 16:09:08 +0000

Инструменты отладки

В «ДокуВики» есть инструменты отладки. Некоторые необходимо настроить.

Включить отладку

Если опция конфигурацииa allowdebug включена , вы можете:

Добавляем ?do=debug или &do=debug к URL-адресу , чтобы «ДокуВики» выводила огромный список строк отладки.
(Вплоть до версии Hogfather 2020 : посмотрите выходные данные dbglog() в data/cache/debug.log)
Получать дополнительные сообщения об ошибках, например, от некоторых серверов аутентификации.
Добавление ?httpdebug или &httpdebug к URL-адресу для включения вывода отладки в HTTPClient DokuWiki
Вернуть несколько сообщений, если таблицы стилей отсутствуют
Получайте дополнительные комментарии в выводе средства визуализации xhtml.
Получите несколько резервных попыток в скомпилированном файле JavaScript с помощью js.php
Получите отладку в некоторых других местах, а также в плагинах или шаблонах, см. поиск кода для использования разрешенного дебага.

Включение ведения журнала

С момента выпуска Игоря 2022 года ::

«ДокуВики» имеет функцию ведения журналов. Какая информация не регистрируется, можно установить с помощью dontlog настройки конфигурации.

По умолчанию регистрируются только сообщения об ошибках и устаревшие сообщения, а журнал отладки отключен.
Вы также можете включить журнал отладки для получения дополнительных результатов отладки.
Через интерфейс администратора вы можете использовать LogViewer. Если доступ к LogViewer невозможен, вы можете найти файлы журналов в вашей файловой системе, например, в формате [wiki_folder]/data/log/error/<date>.log.

Получить информацию о странице и пользователе

Добавление ?do=check или &do=check к URL запускает проверку режима действия, которая предоставляет некоторую информацию о разрешениях пользователей и настройке «ДокуВики».

Отладка TaskRunner

См. информацию об отладке на странице запуска задач.

Функции отладки

dbg($msg)
Вставьте блок кода на вики-страницу, заполненный $msg в виде обычного текста.

Добавление дополнительного аргумента dbg($msg, $hidden=true) вернет $msg в виде комментария html.

dbglog($msg)
Записывает $msg в журнал отладки, отображаемый в LogViewer, который сохраняется [wiki_folder]/data/log/debug/<date>.log когда debug этот флажок снят в dontlog настройке.
(Вплоть до версии Hogfather 2020: он записывался в журнал в каталоге кеша data/cache/debug.log когда опция allowdebug включена.) Имейте в виду, что журнал не очищается автоматически.

Используйте dbglog($msg, 'Header above log message') для включения заголовка над $msg.

dbg_deprecated($alternative = '')
Функция для обозначения устаревших функций. Каждый вызов записывается в устаревший журнал, отображаемый в LogViewer, если deprecated это флажок не установлен в dontlog настройке. В сообщении журнала упоминается: имя устаревшей функции, использующая ее функция, ее файл и строка, а также время $alternative предоставления.

dbg_backtrace()
Напечатайте перевернутую, красиво напечатанную обратную трассировку.

debug_guard($data)
Когда вы пишете собственную функцию отладки, используйте эту функцию для удаления всех данных из массива, ключ которого указывает на конфиденциальные данные.

Плагин «Страж»

Плаген Sentry Plugin позволяет регистрировать обширную информацию в Sentry сервисе. Это особенно полезно при запуске бета-тестирования в реальной среде.

Смотрите также

Конфигурацию опции allowdebug
Конфигурацию опции dontlog и LogViewer для включения журналов
Кэширование
У меня пустая страница или ошибка 500 (внутренняя ошибка сервера)

environment

anonymous@undisclosed.example.com (Anonymous) — Wed, 14 Aug 2024 22:53:02 +0000

Переменные окружения

Эта статья предоставит вам краткий обзор доступных переменных и констант, которые вы можете использовать при разработке плагинов или шаблонов.

Глобальные переменные

$ACT

Содержит текущее действие, см. режимы действий. (reference)

$auth

Глобально доступный объект $auth, представляет используемый бэкенд аутентификации. (reference)

$conf

Глобально доступный массив $conf содержит все настройки «ДокуВики». В основном, он соответствует следующей структуре:

$conf[<setting_name>] — настройки «ДокуВики» (см. config)
$conf[<setting_group>][<setting_name>] — некоторые настройки «ДокуВики» используют этот формат, т.е. настройки ftp, proxy и target.
$conf['tpl'][<template_name>][<setting_name>] — настройки конфигурации шаблона, см. документацию по шаблону.
$conf['plugin'][<plugin_name>][<setting_name>] — настройки конфигурации плагина, см. документацию по плагину.
$conf['auth'][<auth_name>][<setting_name>] — настройки конфигурации бэкенда аутентификации, см. документацию по бэкенду аутентификации.

Обычно вам нет необходимости непосредственно обращаться к этому массиву. И плагины, и шаблоны имеют собственные методы для доступа к их настройкам конфигурации.

(reference)

$ID

Содержит имя «рендеримой» в настоящий момент статьи. Обычно это просматриваемая в настоящий момент, но не обязательно - см. ниже $INFO['id']. (reference)

$INFO

Это ассоциативные массив, заполненный информацией предоставленной функцией pageinfo() из inc/common.php.

В настоящий момент элементами массива является:

id — имя основной статьи просматриваемой в настоящий момент. Обычно совпадает с $ID, но иногда может быть другой. См. подробности в 1320.
rev — номер версии основной статьи, просматриваемой в настоящий момент, обычно совпадает с $REV.
userinfo — установлен только для зарегистрированных пользователей, ассоциативный массив:
- pass — пароль, зашифрованный
- name — полное имя
- mail — адрес email
- grps — группы, к которым относится пользователь (массив [Array ])
- buid — специальный id, сконструированный из браузера и IP адреса пользователя
perm — права пользователя, относящиеся к текущей статье ($ID)
subscribed — true, если пользователь подписан на эту статью, иначе false
namespace — пространство имен, к которой относится текущая статья ($ID)
locked — true, если статья заблокирована, иначе false
filepath — путь в файловой системе к сырым данным wiki текущей статьи ($ID+$REV)
exists — true, если сырые данные wiki текущей статьи существуют ($ID+$REV), иначе false
rev — id версии для текущей статьи ($ID), пустая статья, если просматривается текущая версия
writable — true, если для текущей статьи ($ID+$REV) комбинация наличия файла, разрешений файла и разрешений ACL пользователя позволяет редактировать существующий файл или создать еще не существующий файл. Иначе false.
editable — true, если текущая статья ($ID+$REV) доступна для записи и не заблокирована.
lastmod — временная метка последней модификации текущей статьи ($ID+$REV)
meta — метаданные текущей статьи ($ID)
ip — ip адрес последнего редактировавшего текущую статью ($ID+$REV) пользователя
user — username последнего редактировавшего текущую статью ($ID+$REV) пользователя
sum — краткая анотация изменений текущей статьи ($ID+$REV)
editor — имя пользователя (или ip адрес, если имя неизвестно) последним редактировавшего текущую статью ($ID+$REV)
isadmin — true, если зарегистрированный пользователь является суперпользователем
ismanager — true, если зарегистрированный пользователь является менеджером
draft — содержит название файла черновика для текущего пользователя и статьи.
ismobile — true, если статья просматривается с мобильного устройства или телефона.
client — имя пользователя, зарегистрированного в настоящий момент

$lang

Ассоциативный массив, содержащий все строки перевода интерфейса, плагинов и шаблонов. (reference)

$REV

Содержит штамп времени версии отображаемой в настоящий момент статьи. false, если рассматривается самая свежая версия статьи. (reference)

$_SERVER['REMOTE_USER']

Эта переменная явно прописывается механизмом аутентификации «ДокуВики», когда юзер зарегистрировался, и содержит имя пользователя.

$TEXT

В режимах save и preview эта глобальная переменная содержит текст предоставленный в форме редактирования. (reference)

$TOC

Эта переменная будет использована (если заполнена) функцией tpl_toc() для построения "содержания" статьи. Обычно, эта переменная пуста и tpl_toc() строит «содержание» из метаданных статьи. (reference)

$USERINFO

Глобально доступный ассоциативный массив, который содержит информацию об авторизованном пользователе.

pass - хэш пользовательского пароля
name - полное имя пользователя
mail - e-mail адрес пользователя
grps - массив групп, к которым относится пользователь

(reference)

$JSINFO

Этот массив содержит данные, передаваемые JavaScript в качестве глобальной переменной (смотри jsinfo).

Константы

Ниже приведен список наиболее важных констант.

AUTH_<*>

Тип констант AUTH_<*> представляет уровни доступа (в виде целых чисел) используемые в системе списков доступа «ДокуВики». Они могут для того, чтобы проверка списков доступа к данной статье /пространству имен выглядела более понятной.

if (auth_quickaclcheck($ID) >= AUTH_READ) {
    // do sth.
}

AUTH_NONE

Тип: Целое
Значение: 0
reference

AUTH_READ

Тип: Целое
Значение: 1
reference

AUTH_EDIT

Тип: Целое
Значение: 2
reference

AUTH_CREATE

Тип: Целое
Значение: 4
reference

AUTH_UPLOAD

Тип: Целое
Значение: 8
reference

AUTH_DELETE

Тип: Целое
Значение: 16
reference

AUTH_ADMIN

Тип: Целое
Значение: 255
reference

DOKU_<*>

Тип констант DOKU_<*> содержит различные системные значения для внутреннего использования «ДокуВики».

DOKU_BASE

Базовый URL инсталляции «ДокуВики». (reference)

/dokuwiki/

DOKU_CONF

Путь к директории конфигурации инсталляции DokuWiki на сервере. (reference)

/var/www/dokuwiki/conf/

DOKU_REL

Базовый URL к инсталляции «ДокуВики» (reference)

DOKU_URL

Абсолютный URL к инсталляции DokuWiki (reference)

DOKU_INC

Путь к директории включаемых файлов инсталляции DokuWiki на сервере. (reference)

/var/www/dokuwiki/

DOKU_TPL

Путь к директории используемого шаблона на сервере. (reference)

/dokuwiki/lib/tpl/<template>/

DOKU_TPLINC

Путь к директории включаемых файлов используемого шаблона на сервере. (reference)

lib/tpl/<template>/

Или если установлен параметр canonical:

http//domain.org/lib/tpl/<template>/

https://www.dokuwiki.org/wiki:devel:environment

farm

anonymous@undisclosed.example.com (Anonymous) — Fri, 03 Jan 2025 12:29:39 +0000

Фермы

ВНИМАНИЕ: Эта страница в основном предназначена для сбора идей по настройке/администрированию/внедрению фермы.

Включение/отключение плагинов

Определять (inc/preload.php):
- DOKU_FARM
  - 0 ⇒ Animal
  - 1 ⇒ Farmer

Конфигурация (inc/preload.php)
- установить значение для глобального $config_cascade
  - загружать настройки фермы по умолчанию после настроек dokuwiki по умолчанию
  - загрузка защищенных настроек фермы после локальных настроек

События:
Ранее упоминалось, PLUGIN_NAME_ISDISABLED, PLUGIN_NAME_DISABLE, PLUGIN_NAME_ENABLE не будет работать из-за проблемы курицы и яйца. К тому времени, как плагин сможет управлять другими плагинами, будет уже слишком поздно. Проблема решена путем внедрения сменного «контроллера плагинов», см. ниже.
PLUGIN_PLUGINMANAGER_PLUGINLIST, PLUGIN_CONFIG_PLUGINLIST (реализовано)

Контроллер плагинов (preload.php)
- заменить контроллер плагинов DokuWiki по умолчанию (inc/plugin_controller.class.php)
  - переопределить метод is Disabled для управления тем, какие плагины использует животное
  - извлечь настройки включения/выключения плагина из конфигурации фермы/животного (см. менеджер плагинов ниже)

Менеджер плагинов:
1. отключить загрузку/установку для животных
2. включить/выключить для животных
3. отключение для фермера на каждое животное и на всю ферму
Плагин администрирования фермы:
Фермер должен иметь возможность взять на себя управление животными

Администрация фермы

автоматическое создание животного
способность обездвижить животное
способность взять под контроль животное
возможность установки конфигурации по умолчанию для эмбриональных животных
возможность установки пользователя(ей) по умолчанию, как минимум администратора
возможность устанавливать/редактировать «защищенные» значения конфигурации — значения, которые животные не могут изменить
Изменения в управлении плагинами:
загружать/удалять плагины (не разрешая животным загружать/удалять их)
включить/отключить плагины на всей ферме
механизм записи данных администраторов животных
механизм уведомления (отправки писем) администраторам животных

javascript

anonymous@undisclosed.example.com (Anonymous) — Mon, 28 Aug 2023 10:52:42 +0000

JavaScript

DokuWiki makes uses of JavaScript to enhance the user experience. Like for stylesheets all JavaScript files are delivered through a single dispatcher to minimize HTTP requests, for caching and compression.

This page gives you an overview how JavaScript is loaded from DokuWiki core, plugins and templates. It also gives some info about event handling and coding style when writing JavaScript for use in DokuWiki.

JavaScript Loading

All JavaScript code is collected from all found files and concatenated as one block of code. It is then whitespace compressed (if compress is enabled) and delivered as one file. As a live example you can view the JavaScript file that is in effect on this website lib/exe/js.php. This file will be cached in the DokuWiki cache at /dokuwiki/data/cache and DokuWiki also instructs browsers to cache this file. So when you are developing new JavaScript, make sure to refresh those caches (hitting Shift-F5, Shift+CTRL+R or similar), whenever your script was updated.

DokuWiki will load JavaScript from the following places:

autogenerated JavaScript (language strings, config settings, toolbar)
lib/scripts/*.js
lib/plugins/*/script.js
lib/tpl/<currenttemplate>/script.js
conf/userscript.js

As you can see you can provide JavaScript with your templates and plugins (through a script.js file) and can define your own scripts in conf/userscript.js (just create this file if it does not yet exist).

Deferred Loading

All JavaScript is loaded with the defer attribute. Here's more information about deferred loading.

If you load JavaScript through other means than the recommended methods below and that JavaScript has dependencies on any DokuWiki provided code, you need to ensure it is deferred as well. This also means that you cannot use document.write that relies on DokuWiki-loaded scripts.

From the 2020 Hogfather version onwards, all javascript must be load in a deferred way. To update your existing templates javascript to work in this version, you can add the defer attribute to the <script> tag.

Temporary, the feature flag defer js is available, which allows disabling.

Include Syntax

DokuWiki's JavaScript dispatcher allows you to use special JavaScript comments to include other script files. This is useful for cases where usually only a single JavaScript file would be parsed, e.g. in templates or plugins.

Included files are not checked for updates by the cache logic. You need to touch the master file for updating the cache.

Includes are not supported inside included files to avoid any circular references.

Includepath may only consist of letter,digit, underscore, «/» and «.».

include

/* DOKUWIKI:include somefile.js */

This syntax will include the given file where the comment is placed. The filename is relative to the file containing the include markup unless it starts with a slash which indicates an absolute URL path.

include_once

/* DOKUWIKI:include_once common_library.js */

The file will only be included if not a file of the same base name was previously loaded through the include_once statement. This name is shared over all script files (from all plugins), so you should use a meaningful file name.

Using this statement makes sense if you write multiple independent plugins all using the same JavaScript library. Including it with include_once using the same basename will make sure the library is loaded only once even if multiple of your plugins are installed.

Coding Guidelines

When writing JavaScript for the use within DokuWiki you should follow a few rules. Because of the nature of JavaScript, failing to do so might result in not only breaking your script but all scripts in DokuWiki.

Validate your Code

As mentioned above, DokuWiki will shrink the JavaScript code when the compress option is enabled (which it is by default). To do this without introducing syntax errors, the JavaScript has to be checked more strictly than it might be when run uncompressed.

To check your code you should use the JSLint online service.

debug your code with compress disabled but
verify your code still works with compress enabled

Use unobtrusive JavaScript

Do not assume people have JavaScript enabled, when writing new DokuWiki functionality. Instead use JavaScript as enhancement of the user interface only, when JavaScript is not available your code should fallback to normal page reload based behavior.

jQuery makes this very easy.

Avoid Inappropriate Mixing

The old way of doing things is to embed JavaScript directly in the HTML. However, JavaScript and (X)HTML shouldn't be mixed, and indeed with DokuWiki there are many cases where they cannot be mixed. Here are some examples of INAPPROPRIATE MIXING¹⁾:

<body onload="refreshPage()">
 
<p>some HTML</p>
 
<script language="JavaScript">
  doSomethingHere();
</script>
 
<p>more <a href="http://example.com" onclick="doSomethingElse()">HTML</a></p>
 
</body>

This isn't just a matter of philosophical purity: some of the JavaScript may not work. In the above example, it turns out that both DokuWiki and the <body> tag are trying to assign the page's onload handler to different JavaScript functions. Browsers cannot handle this conflict and the results are unpredictable.

Strictly speaking, it is possible to embed JavaScript in your HTML, but only if you know that the JavaScript has no conflict with DokuWiki. Because this requires knowledge of DokuWiki's implementation, and because DokuWiki's implementation can change, this is still not a good idea. It's wiser to be philosophically pure.

Using IDs

To modify a DOM object the JavaScript must be able to locate the object. The easiest way to locate the object is to give the associated HTML tag an ID. This ID must be unique among all IDs on the page so that referencing this ID produces exactly the right DOM object.

When you are producing your own HTML (e.g. from a template or plugin) that should be accessed from JavaScript later, be sure that the ID does not conflict with an existing ID. In particular, be sure that it won't conflict with the IDs automatically assigned to section headers. The easiest way to ensure this is to use two adjacent underscores (__) in your ID. Because section IDs are always valid pagenames, they will never contain adjacent underscores.

Inline scripts

As said before you should avoid mixing JavaScript and XHTML. However if you need to use inline JavaScript, you should wrap it like this:

<script type="text/javascript">/*<![CDATA[*/
...
/*!]]>*/</script>

If you need to add inline JavaScript to the <head> section you should write an action_plugin and handle the TPL_METAHEADER_OUTPUT event. When you define only some variables see the JSINFO variable below.

jQuery

Since the October 2011 release «Angua», DokuWiki ships with the jQuery and jQuery UI libraries.

Please follow these coding conventions when working with jQuery in DokuWiki. Please also refer to our JQuery FAQ for Plugin Developers.

No $()

jQuery is only used in compatibility mode. There is no $() method²⁾. Use the jQuery() method instead.

Do not map $() to jQuery(), not even within your own (anonymous) functions.

Prefix jQuery object variables

To make it clear that a variable contains an instance of the jQuery object all these variables should be prefixed by a $ character:

var $obj = jQuery('#some__id');

DokuWiki JavaScript Environment

Predefined Global Variables

DokuWiki defines certain JavaScript variables for the use in your script:

DOKU_BASE – the full webserver path to the DokuWiki installation
DOKU_TPL – the full webserver path to the used Template
DOKU_COOKIE_PARAM – parameters required to set similar cookies as in PHP
- path – cookie path
- secure – whether secure cookie
LANG – an array of languagestrings
JSINFO – an array of useful page info (see the section below)
NS – $INFO['namespace'] passed through the function tpl_metaheaders()

JSINFO

DokuWiki passes the global $JSINFO to JavaScript (see mailinglist discussion). This variable is an associative array usually containing the keys:

id – the current page's ID
namespace – the current namespace.

And after 2018-04-05:

ACT – the current mode
useHeadingNavigation – whether to use the first title for Navigation links (the former global constant DOKU_UHN has been deprecated)
useHeadingContent – whether to use the first title for Content links (the former global constant DOKU_UHC has been deprecated)

Other keys can easily be added from within PHP code. The usual way is using an action plugin like this:

function register(Doku_Event_Handler $controller) {
    $controller->register_hook('DOKUWIKI_STARTED', 'AFTER',  $this, '_adduser');
}
function _adduser(&$event, $param) {
    global $JSINFO;
    $JSINFO['user'] = $_SERVER['REMOTE_USER'];
}

If you want to make sure that your plugin's data don't interfere with other plugins or DokuWiki itself consider using plugin_<pluginName> as prefix/top-level key.

The contents of the $JSINFO php variable are sent to the browser in the tpl_metaheaders() function which is called from within the used template.

If you need JSINFO in the pop-up media manager or in the media detail page you have to use respectively MEDIAMANAGER_STARTED or DETAIL_STARTED in stead of DOKUWIKI_STARTED.

¹⁾

Please note as well that there is no language attribute of the script tag! Instead use type=«text/javascript» to be standards compliant.

²⁾

it might be defined but will not do what you expect

logging

anonymous@undisclosed.example.com (Anonymous) — Mon, 19 Jan 2026 18:13:22 +0000

Ведение журнала

Вводная запись в блоге.

Лесозаготовительные объекты

Системы логирования классифицируют зарегистрированные сообщения об ошибках. Они соответствуют каталогам в директории data/log/ Плагины могут использовать свои собственные системы..

В DokuWiki по умолчанию определены три средства ведения журналов:

error – всё, что не должно произойти и является результатом проблемы с кодом, средой, конфигурацией или взаимодействием с пользователем.
deprecated – регистрирует использование устаревшего кода. Трассировка стека должна помочь определить код, который необходимо обновить.
debug – сообщения, которые помогают в процессе разработки или настройки, но обычно не требуются.

Какие именно объекты следует регистрировать, можно настроить с помощью опции dontlog.

Если вам нужно только записывать сообщения об ошибках, без устаревших команд, и отлаживать код, то используйте следующую строку в файле.

conf/dokuwiki.php

Должно выглядеть вот так.

$conf['dontlog'] = 'deprecated,debug';

Автоматическая регистрация ошибок

DokuWiki регистрирует обработчики ошибок, которые автоматически пытаются перехватить все возникающие исключения, ошибки и фатальные события. При этом отображается информационное сообщение для конечного пользователя, а ошибка регистрируется в error соответствующей системе.

Формат журнала

Пользовательское ведение журнала

menus

anonymous@undisclosed.example.com (Anonymous) — Sun, 03 Sep 2023 02:10:14 +0000

Меню — важная часть шаблона. Они обеспечивают доступ к функциям вики, т.е. действия. Например, они могут предоставить кнопку или ссылку для редактирования текущей страницы, доступа к последним изменениям или предложить экспортировать PDF-файл.

DokuWiki группирует эти действия в разные меню, которые можно вставлять в шаблон в разных местах.

Также доступен вводный пост в блоге.

Доступные меню

вид	Источник	Описание
`site`	SiteMenu	определяет все действия на уровне вики, например действия, не относящиеся к одной странице. Примеры: недавние изменения, карта сайта)
`user`	UserMenu	определяет действия, относящиеся к текущему пользователю. Примеры: Логин, Администратор.
`page`	PageMenu	определяет действие, связанное с текущей страницей. Примеры: «Редактировать», «Показать старые версии».
`detail`	DetailMenu	аналогично меню страницы, но связано с изображением при отображении в подробном представлении
	MobileMenu	объединяет все элементы из меню «Сайт», «Пользователь» и «Страница», когда им разрешено отображение в мобильном контексте. Полезно для создания единого гамбургер-меню.

Плагины могут расширять и изменять вышеуказанные меню, используя событие MENU_ITEMS_ASSEMBLY.

Пункты меню

Меню состоят из пунктов меню — объектов, наследуемых от AbstractItem.php. Пункт меню настраивает несколько свойств, которые шаблон может использовать для отображения этого элемента. Сюда входят триггерное действие, метка, значок SVG и многое другое. Пожалуйста, обратитесь к источнику чтобы узнать, какие свойства доступны..

Плагины могут создавать свои собственные элементы и добавлять их в доступные меню с помощью события MENU_ITEMS_ASSEMBLY.

Иконки

Значок, возвращаемый методом getSVG() и заданный в $svg свойстве, должен соответствовать следующим ограничениям:

Он должен быть в формате SVG.
Размер файла должен быть меньше 2 КБ.
Он должен содержать только один объект пути.

Цвет заливки пути будет установлен CSS шаблона при его использовании.

Чтобы соответствовать стилю других значков, рекомендуется либо выбрать значок из огромного бесплатного выбора на https://materialdesignicons.com/, либо придерживаться рекомендаций по дизайну материалов при разработке собственного значка..

Добавление меню в шаблоны

Меню, упомянутые выше, создают их экземпляры и либо используют один из удобных методов, либо просто вызывают getItems() и перебирают объекты элементов.

Пример: чтобы интегрировать UserMenu в виде списка ссылок, используйте это:

echo (new \dokuwiki\Menu\UserMenu())->getListItems();

Выпадающее меню для мобильных устройств можно добавить следующим образом:

echo (new \dokuwiki\Menu\MobileMenu())->getDropdown();

Пожалуйста, обратитесь к источнику, чтобы узнать, что еще доступно.

Если вам нужен конкретный HTML-код для пунктов меню, вам нужно перебрать элементы меню и создать HTML самостоятельно. Например, этот цикл создаст значки в шаблоне записи, что немного сложнее:

$items = (new \dokuwiki\Menu\PageMenu())->getItems();
foreach($items as $item) {
  echo '<li>'
      .'<a href="'.$item->getLink().'" title="'.$item->getTitle().'">'
      .'<span class="icon">'.inlineSVG($item->getSvg()).'</span>'
      . '<span class="a11y">'.$item->getLabel().'</span>'
      . '</a></li>';
}

Устаревшая поддержка

С появлением системы меню следующие функции стали устаревшими. Авторам шаблонов и плагинов следует обязательно заменить их в ближайшее время:

tpl_button()
tpl_actionlink()
tpl_get_action()
tpl_actiondropdown()
tpl_toolsevent()

overview

anonymous@undisclosed.example.com (Anonymous) — Fri, 03 Jan 2025 12:10:12 +0000

Обзор ядра

Это обзор исходного кода во время запроса на /doku.php?id=start&do=show объяснение основ DokuWiki. Вам необходимо иметь полный исходный код, чтобы полностью насладиться этим путешествием, когда вы читаете это. Используйте ссылки XRef чтобы получить просматриваемую версию исходного кода. Также доступна более подробная страница callgraph включая процесс рендеринга. Многие детали опущены в этом описании, чтобы сделать его более простым.

Filename	Code snippet	Description
doku.php	`if(!defined('DOKU_INC'))`	Все начинается здесь с определения базового каталога кода.
	`$ACT = $_REQUEST['do']`	Далее мы определяем, какое действие запрашивается, то есть режимы do
	`require_once('init.php')`	перейти к init.php, инициализировать ядро
init.php	`include('preload.php')`	предварительная загрузка preload позволяет переопределять каталоги и каскад конфигураций
	`if(!defined('DOKU_CONF')`	создать среду environment определяющую местоположение кода
	`include(DOKU_INC. 'inc/config_cascade.php')`	подготовить и загрузить глобальный файл(ы) конфигурации configuration
	`global $lang;`	загрузите и подготовьте language файлы, используя английский язык для всех отсутствующих записей
	`if(!defined('DOKU_REL')`	создать все определения среды environment которые еще не определены, что может зависеть от настроек конфигурации config
	`if(!headers_sent() && ..`	инициализация сеанса и установка cookie
	`require_once (DOKU_INC.'inc/load.php')`	autoload всех библиотек
	`… auth_setup() …`	инициализирует контроллер плагина, event handling систему обработки событий , аутентификацию и выход после настройки почты
doku.php	`$ID = getID()`	вернуться из init.php, очистить и превратить запрос в глобальные переменные global variables
	`$INFO = pageinfo()`	добавить метаданные страницы metadata в глобальную переменную global variable, это включает вызов auth_quickaclcheck() и p_get_metadata(). Последний вызывает рендеринг метаданных страницы, если они не кэшированы.
	`if(!$INFO['exists'] …`	отправьте 404 для отсутствующих страниц
	`trigger_event(DOKUWIKI_STARTED)`	плагины вызова действий action plugins, подписывающиеся на событие DOKUWIKI_STARTED
actions.php	`act_dispatch($ACT)`	выполнять работу в зависимости от действия action
	`if ($evt->advise_before()) ...`	разрешить плагинам переопределять поведение по умолчанию с помощью события ACTION_ACT_PREPROCESS
	`$ACT = act_clean($ACT)`	дезинфицировать и перенаправлять отключенные disabled actions действия `do=show`
	`… $ACT = act_permcheck($ACT) …`	вызовите код обработки для запрошенного действия(й) при проверке необходимых разрешений ACL . $ACT может измениться во время act_dispatch().
	`global $INFO global $conf`	сделать глобальные переменные доступными для кода шаблона
	`trigger_event(ACTION_HEADERS_SEND)`	плагины действий action plugins вызова , подписывающиеся на событие ACTION_HEADERS_SEND
	`include(template('main.php'))`	к выбранному шаблону основного скрипта
lib/tpl/dokuwiki/main.php	`… tpl_metaheaders() …`	Основной скрипт шаблона template состоит из элементов дизайна HTML , вызывающих методы PHP для такого контента, как метазаголовки, кнопки, элементы навигации и т. д. Все они доступны в файле inc/template.php
lib/tpl/dokuwiki/main.php	`tpl_content()`	здесь создается настоящая вики-страница
inc/template.php	`tpl_content()`	здесь создается настоящая вики-страница
	`trigger_event(TPL_ACT_RENDER)`	вызов tpl_content_core() с использованием события TPL_ACT_RENDER
	`switch($ACT)`	выбор контента на основе действия, основные `do=show` вызовы html_show()
inc/html.php	`$html = p_wiki_xhtml(…)`	который использует cached XHTML кэшированную версию страницы ИЛИ запускает renderer для отображения кэшированных инструкций в виде XHTML ИЛИ использует parser для предварительного преобразования текста вики в инструкции.
inc/template.php	`trigger_event(TPL_CONTENT_DISPLAY)`	у плагинов действия есть последний шанс отредактировать необработанный HTML перед выводом с помощью события TPL_CONTENT_DISPLAY event
doku.php	`trigger_event(DOKUWIKI_DONE)`	завершить вызовом action plugins подписавшихся на событие DOKUWIKI_DONE когда основной скрипт шаблона завершен

parser

anonymous@undisclosed.example.com (Anonymous) — Fri, 17 Jan 2025 10:53:47 +0000

Парсер «Докувики»

В этом документе излагаются детали функционирования парсера «Докувики», которые могут понадобиться разработчикам для модификации поведения парсера или получения контроля над выходным документом, возможно, изменив сгенерированный HTML или реализовав другие форматы вывода.

Обзор

Парсер разбивает процесс трансформации исходного документа «Докувики» в финальный выходной документ (обычно XHTML) на дискретные стадии. Каждая стадия представлена одним или несколькими PHP-классами.

В общем рассмотрении этими элементами являются;

Lexer¹⁾ (лексический анализатор): сканирует²⁾ исходный документ «Докувики» и выводит последовательность «вхождений» (токенов³⁾), соответствующих синтаксической структуре документа.
Handler⁴⁾ (обработчик): получает вхождения от анализатора и преобразует их в последовательность «инструкций»⁵⁾. Он описывает, как должет быть сформирован выходной документ, от начала до конца.
Parser⁶⁾ (парсер): «связывает» лексический анализатор с обработчиком, предоставляя синтаксические правила «Докувики», а также точку доступа к системе (метод Parser::parse())
Renderer⁷⁾ (преобразователь): принимает инструкции от обработчика и «отрисовывает» готовый к выводу документ (например, в виде XHTML).

Механизма для соединения Handler (обработчика) с Renderer (логическим преобразователем) не предусмотрено — для этого требуется кодирование для каждого конкретного случая использования.

Схематическая диаграмма связей между компонентами;

    ┌────────────┐           ┌────────────┐
    │            │   Ввод    │ Клиентский │
    │   Парсер   ◄───────────┤ код        │
    │            │  Строка   │            │
    └─────┬──────┘           └─────▲──────┘
  Режимы  │                        │
    +     │        Инструкции      │
  Строка  │        преобразователя │
  ввода   │                        │
    ┌─────▼──────┐           ┌─────┴──────┐
    │            │           │            │
    │ Анализатор ├───────────► Обработчик │
    │            │ Вхождения │            │
    └─────┬──────┘           └────────────┘
          │
          │
     ┌────┴───┐
     │ Режимы ├─┐
     └─┬──────┘ ├─┐
       └─┬──────┘ │
         └────────┘

«Клиентский код» (код, использующий парсер) вызывает парсер, передавая ему входную строку. В ответ ему возвращается перечень «инструкций» преобразователя, построенных обработчиком. Они могут быть использованы неким объектом, реализующим преобразователь.

Примечание: критическим моментом здесь является намерение позволить преобразователю быть настолько «тупым», насколько это возможно. От него не требуется осуществлять дальнейшую интерпретацию или модификацию переданных инструкций, но полностью сконцентрироваться на формировании выходных данных (например, XHTML) — в особенности, преобразователю не следует отслеживать состояния. Соблюдение этого принципа и, кроме того, составление преобразователя достаточно простым для реализации (сосредоточенной исключтельно на том, что следует выводить), также сделает возможным преобразователю быть взаимозаменяемым (например, вывод PDF в качестве альтернативы XHTML). В то же самое время, выходные инструкции обработчика направляются для преобразования в XHTML и не всегда могут быть пригодынми для всех выходных форматов.

Лексический анализатор

Определяется в inc/Parsing/Lexer/Lexer.php

В самом общем смысле, он реализует инструмент для управления комплексными регулярными выражениями, где важным является состояние. Анализатор появился из Simple Test , но содержит три модификации (читай: «хака»):

поддержка шаблонов просмотра назад и просмотра вперед⁸⁾;
поддержка изменения модификаторов шаблона в пределах шаблона;
уведомление обработчика о начальном индексе байта в необработанном тексте, где был сопоставлен токен.

Короче говоря, лексер Simple Test действует как инструмент, упрощающий управление регулярными выражениями — вместо гигантских регулярных выражений вы пишете много маленьких/простых. Лексер заботится об их эффективном объединении, а затем предоставляет вам API обратного вызова в стиле SAX , чтобы вы могли писать код для ответа на соответствующие «события».

В целом Lexer состоит из трех основных классов;

inc/Parsing/Lexer/ParallelRegex: позволяет строить регулярные выражения из нескольких отдельных шаблонов, каждый шаблон связан с идентифицирующей «меткой», класс объединяет их в одно регулярное выражение с помощью подшаблонов. При использовании Lexer вам не нужно беспокоиться об этом классе.
inc/Parsing/Lexer/StateStack: предоставляет простой конечный автомат, чтобы лексирование могло быть «контекстно-зависимым». При использовании Lexer вам не нужно беспокоиться об этом классе.
inc/Parsing/Lexer/Lexer: предоставляет точку доступа для клиентского кода с помощью Lexer. Управляет несколькими экземплярами ParallelRegex, используя StateStack для применения правильного экземпляра ParallelRegex в зависимости от «контекста». При обнаружении «интересного текста» вызывает функции для предоставленного пользователем объекта (Handler).

Необходимость в состояниях

Синтаксис вики, используемый в «Докувики», содержит разметку, «внутри» которой применяются только определённые синтаксические правила. Самый очевидный пример — тэг <code/> , внутри которого синтаксис вики не будет распознаваться анализатором. Для других синтаксических конструкций, таких как списки или таблицы, следует позволять использовать некоторую разметку, но не всю, например, в списка можно использовать ссылки, но не таблицы.

Анализатор обеспечивает «осведомлённость о состояниях», позволяющую применять корректные синтаксические правила в зависимости от текущий позиции (контекста) в сканируемом тексте. Если он видит открывающий тэг <code>, он переключается в другое состояние, в пределах которого другие синтаксические правила не применяются (т. е. что-либо, что выглядит как синтаксис вики должно восприниматься как «простой» текст), до тех пор, пока не найдёт закрывающий тэг </code>.

Режимы анализатора

Термин режим обозначает особенное состояние лексического анализа ⁹⁾. Код, использующий анализатор, регистрирует один или более шаблон регулярного выражения с особенным наименованием режима. Затем анализатор, сравнивая эти паттерны со сканируемым текстом, вызывает функции обработчика с тем же самым наименованием режима (если метод mapHandler не был использован для создания псевдонимов — см. ниже).

API анализатора

Краткое введение в лексический анализатор можно найти в Simple Test Lexer Notes. Здесь предлагается более подробное описание.

Ключевыми методами анализатора являются:

Конструктор

Принимает ссылку на объект Handler, имя начального режима, в котором должен запускаться Lexer, и (необязательно) логический флаг, указывающий, должно ли сопоставление с образцом учитывать регистр.

Пример:

$handler  =  new MyHandler ( ) ; 
$lexer  =  new dokuwiki\Lexer\Lexer ( $handler ,  'base' ,  true ) ;

Здесь указан начальный режим 'base'.

addEntryPattern / addExitPattern

addEntryPattern() в Lexer.php

Lexer.php

    public function addEntryPattern($pattern, $mode, $new_mode)
    {
        if (! isset($this->regexes[$mode])) {
            $this->regexes[$mode] = new ParallelRegex($this->case);
        }
        $this->regexes[$mode]->addPattern($pattern, $new_mode);
    }

addExitPattern() в Lexer.php

Lexer.php

    public function addExitPattern($pattern, $mode)
    {
        if (! isset($this->regexes[$mode])) {
            $this->regexes[$mode] = new ParallelRegex($this->case);
        }
        $this->regexes[$mode]->addPattern($pattern, "__exit");
    }

addEntryPattern() и addExitPattern() используются для регистрации шаблона для входа и выхода из определенного режима анализа. Например;

// arg0: регулярное выражение для сопоставления — обратите внимание, что нет необходимости добавлять разделители начального/конечного шаблона 
// arg1: имя режима, в котором может использоваться этот шаблон записи 
// arg2: имя режима для ввода 
$lexer -> addEntryPattern ( '<file>' , 'base' , 'file' ) ;
 
// arg0: регулярное выражение для сопоставления 
// arg1: имя режима для выхода 
$lexer -> addExitPattern ( '</file>' , 'file' ) ;

Код, приведённый выше, позволяет тэгу <file/> быть использованный при входе из базового в новый режим (file). Если в дальнейшем следует применить режимы, пока анализатор находится в режиме file, они должны быть зарегистрированы с режимом file.

Замечание: в паттернах не требуется использование ограничителей (разделителей начала и конца шаблона).

addPattern

addEntryPattern() в Lexer.php

Lexer.php

    public function addPattern($pattern, $mode = "accept")
    {
        if (! isset($this->regexes[$mode])) {
            $this->regexes[$mode] = new ParallelRegex($this->case);
        }
        $this->regexes[$mode]->addPattern($pattern);
    }

addEntryPattern() в ParallelRegex.php

ParallelRegex.php

    public function addPattern($pattern, $label = true)
    {
        $count = count($this->patterns);
        $this->patterns[$count] = $pattern;
        $this->labels[$count] = $label;
        $this->regex = null;
    }

addEntryPattern() используется, чтобы реагировать на дополнительные «вхождения» внутри существующего режима (без переходов). Он принимает паттерн и наименование режима, внутри которого должен использоваться.

Это наиболее наглядно видно из разбора парсером синтаксиса списков. Синтаксис списков выглядит в «Докувики» следующим образом;

До списка
  * Ненумерованный элемент списка
  * Ненумерованный элемент списка
  * Ненумерованный элемент списка
После списка

Использование addPattern() делает возможным сравнивать полный список, одновременно корректно захватывая каждый элемент списка;

// Сопоставляем открывающий элемент списка и меняем режим 
$lexer -> addEntryPattern ( '\n {2,}[\*]' , 'base' , 'list' ) ;
 
// Сопоставить новые элементы списка, но остаться в режиме списка 
$lexer -> addPattern ( '\n {2,}[\*]' , 'list' ) ;
 
// Если это перевод строки, который не соответствует указанному выше правилу addPattern, выходим из режима 
$lexer -> addExitPattern ( '\n' , 'list' ) ;

addSpecialPattern

addSpecialPattern() в Lexer.php

Lexer.php

    public function addSpecialPattern($pattern, $mode, $special)
    {
        if (! isset($this->regexes[$mode])) {
            $this->regexes[$mode] = new ParallelRegex($this->case);
        }
        $this->regexes[$mode]->addPattern($pattern, "_$special");
    }

addSpecialPattern() используется для входа в новый режим только для совпадения, а затем сразу возвращается в «родительский» режим. Принимает шаблон, имя режима, в котором он может быть применен, и имя «временного» режима для входа для совпадения. Обычно это используется, если вы хотите заменить разметку wiki чем-то другим. Например, чтобы сопоставить смайлик, например :-), у вас может быть:

$lexer -> addSpecialPattern ( ':-)' , 'base' , 'smiley' ) ;

mapHandler

mapHandler() в Lexer.php

Lexer.php

    public function mapHandler($mode, $handler)
    {
        $this->mode_handlers[$mode] = $handler;
    }

mapHandler() позволяет сопоставить определенный именованный режим с методом с другим именем в Handler. Это может быть полезно, когда разный синтаксис должен обрабатываться одинаково, например, синтаксис DokuWiki для отключения другого синтаксиса внутри определенного текстового блока;

$lexer -> addEntryPattern ( '<nowiki>' , 'base' ,  'unformatted' ) ; 
$lexer -> addEntryPattern ( '%%' , 'base' ,  'unformattedalt' ) ; 
$lexer -> addExitPattern ( '</nowiki>' ,  'unformatted' ) ; 
$lexer -> addExitPattern ( '%%' ,  'unformattedalt' ) ;
 
// Оба синтаксиса должны обрабатываться одинаково... 
$lexer -> mapHandler ( 'unformattedalt' ,  'unformatted' ) ;

Подшаблоны не допускаются

Поскольку Lexer (анализатор) сам использует подшаблоны (внутри класса ParallelRegex), код, использующий анализатор, этого не может. Иногда это может пригодиться, но, по общему правилу, метод addPattern() может быть применён для решения проблем, когда обычно применяются подшаблоны. Его преимущество в том, что он делает регулярные выражения более простыми и, следовательно, более простыми в управлении.

Замечание: если вы используете в шаблоне круглые скобки, они будут автоматически пропущены анализатором.

Синтаксические ошибки и состояния

Для предотвращение «плохо форматируемой» (особенно при пропуске закрывающих тэгов) разметки, приводящей к тому, что Lexer (анализатор) входит в состояние (режим), который он никогда не покинет, может быть полезным использование паттерна просмотра вперёд для проверки наличия закрывающей разметки¹⁰⁾. Например:

// Использование просмотра вперёд во входном шаблоне...
// Использовать предпросмотр в шаблоне записи... 
$lexer -> addEntryPattern ( '<file>(?=.*</file>)' , 'base' , 'file' ) ; 
$lexer -> addExitPattern ( '</file>' , 'file' ) ;

Шаблон входа проверяет, может ли он найти закрывающий </file> тег, прежде чем войти в состояние.

Handler (Обработчик)

Определено в inc/parser/handler.php и папке inc/Parsing/Handler


	Handler
	Handler
			AbstractRewriter.php
			AbstractRewriter.php
			Block.php
			Block.php
			CallWriter.php
			CallWriter.php
			Nest.php
			Nest.php
			Lists.php
			Lists.php
			CallWriterInterface.php
			CallWriterInterface.php
			Preformatted.php
			Preformatted.php
			Quote.php
			Quote.php
			ReWriterInterface.php
			ReWriterInterface.php
			Table.php
			Table.php

Handler — это класс, предоставляющий методы, которые вызывает Lexer, когда он сопоставляет токены. Затем он «тонко настраивает» токены в последовательность инструкций, готовых для Renderer.

Обработчик в целом содержит следующие классы:

Doku_Handler: все вызовы из Lexer производятся в этот класс. Для каждого режима, зарегистрированного в Lexer, будет соответствующий метод в Handler

Doku_Handler в /dokuwiki/inc/Extension/SyntaxPlugin.php

SyntaxPlugin.php

 6  use Doku_Handler;
57  * @see Doku_Handler_Block
75  * @param Doku_Handler $handler The Doku_Handler object
77  * @param   Doku_Handler $handler The Doku_Handler object
80  abstract public function handle($match, $state, $pos, Doku_Handler $handler);

Doku_Handler в /dokuwiki/inc/Parsing/Parser.php

Parser.php

6 use Doku_Handler;
17  /** @var Doku_Handler */
32  * @param Doku_Handler $handler
34  public function __construct(Doku_Handler $handler)

Doku_Handler в /dokuwiki/inc/parser/handler.php

handler.php

16   * Class Doku_Handler
18   class Doku_Handler {
40   * Doku_Handler constructor.
795  $link[1] = Doku_Handler_Parse_Media($link[1]);
878  $p = Doku_Handler_Parse_Media($match);
1023 function Doku_Handler_Parse_Media($match) {

CallWriter: обеспечивает слой между массивом инструкций (массив Doku_Handler::$calls) и методами Handler, записывающими эти инструкции. Пока идёт лексический анализ, он будет временно перемещён другими объектами, вроде dokuwiki\Parsing\Handler\List.
List: отвечает за преобразование токенов списка в инструкции, пока выполняется лексический анализ
Quote: отвечает за преобразование токенов blockquote (текст, начинающийся с одного или нескольких >) в инструкции, пока выполняется лексический анализ
Table: отвечает за преобразование токенов таблицы в инструкции, пока выполняется лексический анализ
Block: отвечает за вставку инструкций «p_open» и «p_close», при этом отслеживая инструкции «уровня блока», после завершения всего лексического анализа (т.е. выполняет цикл один раз по всему списку инструкций и вставляет больше инструкций)
AbstractRewriter: расширено Preformattedи Nest…
Nest: …
Preformatted: отвечает за преобразование предварительно отформатированных токенов (отступ в тексте dokuwiki) в инструкции, пока лексический анализ еще выполняется

Методы токенов обработчиков

Обработчик должен предоставлять методы, названные в соответствии с режимами, зарегистрированными в лексическом анализаторе (имея в виду mapHandler() метод лексического анализатора — см. выше).

Например, если вы зарегистрировали режим файла с помощью Lexer, например:

$lexer->addEntryPattern('<file>(?=.*</file>)','base','file');
$lexer->addExitPattern('</file>','file');

Обработчику понадобится такой метод:

class Doku_Handler {
 
    /**
    * @param string match содержит совпавший текст
    * @param int state - тип найденного соответствия (см. ниже)
    * @param int pos - индекс байта, где было найдено совпадение
    */
    public function file($match, $state, $pos) {
        return true;
    }
}

Примечание: метод Handler должен возвращать true, иначе Lexer немедленно остановится. Такое поведение может быть полезным при работе с другими типами проблем синтаксического анализа, но для парсера DokuWiki все методы Handler всегда будут возвращать true.

Аргументы, реализумые методом обработчика;

$match: текст, который был обнаружен;
$state: содержит константу, которая описывает как именно было найдено совпадение:
1. DOKU_LEXER_ENTER: найден входной паттерн (см. Lexer::addEntryPattern);
2. DOKU_LEXER_MATCHED: найден паттерн (см. Lexer::addPattern);
3. DOKU_LEXER_UNMATCHED: внутри режима не было совпадений;
4. DOKU_LEXER_EXIT: найден выходной паттерн (см. Lexer::addExitPattern);
5. DOKU_LEXER_SPECIAL: найден специальный паттерн (см. Lexer::addSpecialPattern);
$pos: это индекс байта (длина строки от начала), где было найдено начало вхождения. $pos + strlen($match) даёт индекс байта конца совпадения.

В качестве более сложного примера, для поиска списков в парсере определено следующее;

    function connectTo($mode) {
        $this->Lexer->addEntryPattern('\n {2,}[\-\*]',$mode,'listblock');
        $this->Lexer->addEntryPattern('\n\t{1,}[\-\*]',$mode,'listblock');
 
        $this->Lexer->addPattern('\n {2,}[\-\*]','listblock');
        $this->Lexer->addPattern('\n\t{1,}[\-\*]','listblock');
 
    }
 
    function postConnect() {
        $this->Lexer->addExitPattern('\n','listblock');
    }

Метод listblock в обработчике (вызов просто list приводит к ошибке обработчика PHP, поскольку list зарезервировано в PHP) выглядит как:

    function listblock($match, $state, $pos) {
 
        switch ( $state ) {
 
            // Начало списка...
            case DOKU_LEXER_ENTER:
                // Создать List rewrite, пропуская текущий CallWriter
                $ReWriter = & new Doku_Handler_List($this->CallWriter);
 
                // Заменить текущий CallWriter на List rewriter
                // все поступающие вхождения (даже, если они не являются вхождениями list)
                // теперь направляются в list
                $this->CallWriter = & $ReWriter;
 
                $this->__addCall('list_open', array($match), $pos);
            break;
 
            // Для конца списка
            case DOKU_LEXER_EXIT:
                $this->__addCall('list_close', array(), $pos);
 
                // Дать указание List rewriter об очистке
                $this->CallWriter->process();
 
                // Восстановить прежний CallWriter
                $ReWriter = & $this->CallWriter;
                $this->CallWriter = & $ReWriter->CallWriter;
 
            break;
 
            case DOKU_LEXER_MATCHED:
                $this->__addCall('list_item', array($match), $pos);
            break;
 
            case DOKU_LEXER_UNMATCHED:
                $this->__addCall('cdata', array($match), $pos);
            break;
        }
        return TRUE;
    }

Конвертирование вхождений

«Тонкая обработка» задействует вставку символа дроби «/», переименование или удаление вхождений, переданных анализатором.

Например, список вроде:

This is not a list
  * This is the opening list item
  * This is the second list item
  * This is the last list item
This is also not a list

в результате превратиться в последовательность вхождений вроде;

base: «This is not a list", DOKU_LEXER_UNMATCHED
listblock: «\n *", DOKU_LEXER_ENTER
listblock: « This is the opening list item", DOKU_LEXER_UNMATCHED
listblock: «\n *", DOKU_LEXER_MATCHED
listblock: « This is the second list item", DOKU_LEXER_UNMATCHED
listblock: «\n *", DOKU_LEXER_MATCHED
listblock: « This is the last list item", DOKU_LEXER_UNMATCHED
listblock: «\n", DOKU_LEXER_EXIT
base: «This is also not a list", DOKU_LEXER_UNMATCHED

Но чтобы быть использованными преобразователем, это может быть конвертировано в следующие инструкции:

p_open:
cdata: «This is not a list"
p_close:
listu_open:
listitem_open:
cdata: « This is the opening list item"
listitem_close:
listitem_open:
cdata: « This is the second list item"
listitem_close:
listitem_open:
cdata: « This is the last list item"
listitem_close:
list_close:
p_open:
cdata: «This is also not a list"
p_close:

В случае со списками, это требует помощи класса Doku_Handler_List, который принимает вхождения, заменяя их на корректные инструкции для Преобразователя.

Parser (Парсер)

Определено в /dokuwiki/inc/Parsing/Parser.php и /dokuwiki/inc/parser/parser.php.

dokuwiki \Parsing\Parser действует как интерфейс для внешнего кода и настраивает Lexer с помощью шаблонов и режимов, описывающих синтаксис DokuWiki.

Использование парсера обычно выглядит так:

// Создаем обработчик Handler
$handler = new Doku_Handler();
 
// Создаем парсер с обработчиком 
$parser = new dokuwiki\Parsing\Parser($handler);
 
// Добавить требуемые режимы синтаксиса в парсер 
$parser->addMode('footnote', new dokuwiki\Parsing\ParserMode\Footnote());
$parser->addMode('hr', new dokuwiki\Parsing\ParserMode\Hr());
$parser->addMode('unformatted', new dokuwiki\Parsing\ParserMode\Unformatted());
# etc.

$doc = file_get_contents('wikipage.txt.');
$instructions = $parser->parse($doc);

Более подробные примеры приведены ниже.

В целом Parser также содержит классы, представляющие каждый доступный режим синтаксиса, базовым классом для всех них является dokuwiki\Parsing\ParserMode\AbstractMode. Поведение этих режимов лучше всего понять, рассмотрев примеры добавления синтаксиса далее в этом документе.

Причина представления режимов с помощью классов заключается в том, чтобы избежать повторных вызовов методов Lexer. Без них пришлось бы жестко кодировать каждое правило шаблона для каждого режима, в котором может быть сопоставлен шаблон, например, регистрация одного правила шаблона для синтаксиса ссылок CamelCase потребовала бы чего-то вроде:

$lexer->addSpecialPattern('\b[A-Z]+[a-z]+[A-Z][A-Za-z]*\b', 'base', 'camelcaselink');
$lexer->addSpecialPattern('\b[A-Z]+[a-z]+[A-Z][A-Za-z]*\b', 'footnote', 'camelcaselink');
$lexer->addSpecialPattern('\b[A-Z]+[a-z]+[A-Z][A-Za-z]*\b', 'table', 'camelcaselink');
$lexer->addSpecialPattern('\b[A-Z]+[a-z]+[A-Z][A-Za-z]*\b', 'listblock', 'camelcaselink');
$lexer->addSpecialPattern('\b[A-Z]+[a-z]+[A-Z][A-Za-z]*\b', 'strong', 'camelcaselink');
$lexer->addSpecialPattern('\b[A-Z]+[a-z]+[A-Z][A-Za-z]*\b', 'underline', 'camelcaselink');
// и т.д.

Каждый режим, которому разрешено содержать ссылки CamelCase, должен быть явно назван.

Вместо того, чтобы жестко кодировать это, вместо этого это реализовано с использованием одного класса, например:

namespace dokuwiki\Parsing\ParserMode;
 
class CamelCaseLink extends AbstractMode {
 
    public function connectTo($mode) {
        $this->Lexer->addSpecialPattern(
            '\b[A-Z]+[a-z]+[A-Z][A-Za-z]*\b', $mode, 'camelcaselink'
        );
    }
}

При настройке лексического анализатора парсер вызывает connectTo() метод объекта dokuwiki\Parsing\ParserMode\CamelCaseLink для каждого другого режима, который принимает синтаксис CamelCase (некоторым такой <code /> синтаксис не нравится).

За счет усложнения понимания настройки лексического анализатора это позволяет сделать код более гибким при добавлении нового синтаксиса.

Формат данных инструкций

Плагин Parserarray — это экспортный рендерер, который показывает инструкции для текущей страницы. Он может помочь вам понять формат данных. Ниже показан пример сырого текста вики и соответствующий вывод парсера;

Исходный текст (содержит таблицу):

abc
| Row 0 Col 1    | Row 0 Col 2     | Row 0 Col 3        |
| Row 1 Col 1    | Row 1 Col 2     | Row 1 Col 3        |
def

После обработки будет возвращён следующий массив PHP (описан ниже):

Array(
    [0] => Array(
            [0] => document_start
            [1] => Array()
            [2] => 0
        )
    [1] => Array(
            [0] => p_open
            [1] => Array()
            [2] => 0
        )
    [2] => Array(
            [0] => cdata
            [1] => Array(
                    [0] => 

abc
                )
            [2] => 0
        )
    [3] => Array(
            [0] => p_close
            [1] => Array()
            [2] => 5
        )
    [4] => Array(
            [0] => table_open
            [1] => Array(
                    [0] => 3
                    [1] => 2
                )
            [2] => 5
        )
    [5] => Array(
            [0] => tablerow_open
            [1] => Array()
            [2] => 5
        )
    [6] => Array(
            [0] => tablecell_open
            [1] => Array(
                    [0] => 1
                    [1] => left
                )
            [2] => 5
        )
    [7] => Array(
            [0] => cdata
            [1] => Array(
                    [0] =>  Row 0 Col 1
                )
            [2] => 7
        )
    [8] => Array(
            [0] => cdata
            [1] => Array(
                    [0] =>     
                )
            [2] => 19
        )
    [9] => Array(
            [0] => tablecell_close
            [1] => Array()
            [2] => 23
        )
    [10] => Array(
            [0] => tablecell_open
            [1] => Array(
                    [0] => 1
                    [1] => left
                )
            [2] => 23
        )
    [11] => Array(
            [0] => cdata
            [1] => Array(
                    [0] =>  Row 0 Col 2
                )
            [2] => 24
        )
    [12] => Array(
            [0] => cdata
            [1] => Array(
                    [0] =>      
                )
            [2] => 36
        )
    [13] => Array(
            [0] => tablecell_close
            [1] => Array()
            [2] => 41
        )
    [14] => Array(
            [0] => tablecell_open
            [1] => Array(
                    [0] => 1
                    [1] => left
                )
            [2] => 41
        )
    [15] => Array(
            [0] => cdata
            [1] => Array(
                    [0] =>  Row 0 Col 3
                )
            [2] => 42
        )
    [16] => Array(
            [0] => cdata
            [1] => Array(
                    [0] =>         
                )
            [2] => 54
        )
    [17] => Array(
            [0] => tablecell_close
            [1] => Array()
            [2] => 62
        )
    [18] => Array(
            [0] => tablerow_close
            [1] => Array()
            [2] => 63
        )
    [19] => Array(
            [0] => tablerow_open
            [1] => Array()
            [2] => 63
        )
    [20] => Array(
            [0] => tablecell_open
            [1] => Array(
                    [0] => 1
                    [1] => left
                )
            [2] => 63
        )
    [21] => Array(
            [0] => cdata
            [1] => Array(
                    [0] =>  Row 1 Col 1
                )
            [2] => 65
        )
    [22] => Array(
            [0] => cdata
            [1] => Array(
                    [0] =>     
                )
            [2] => 77
        )
    [23] => Array(
            [0] => tablecell_close
            [1] => Array()
            [2] => 81
        )
    [24] => Array(
            [0] => tablecell_open
            [1] => Array(
                    [0] => 1
                    [1] => left
                )
            [2] => 81
        )
    [25] => Array(
            [0] => cdata
            [1] => Array(
                    [0] =>  Row 1 Col 2
                )
            [2] => 82
        )
    [26] => Array(
            [0] => cdata
            [1] => Array(
                    [0] =>      
                )
            [2] => 94
        )
    [27] => Array(
            [0] => tablecell_close
            [1] => Array()
            [2] => 99
        )
    [28] => Array(
            [0] => tablecell_open
            [1] => Array(
                    [0] => 1
                    [1] => left
                )
            [2] => 99
        )
    [29] => Array(
            [0] => cdata
            [1] => Array(
                    [0] =>  Row 1 Col 3
                )
            [2] => 100
        )
    [30] => Array(
            [0] => cdata
            [1] => Array(
                    [0] =>         
                )
            [2] => 112
        )
    [31] => Array(
            [0] => tablecell_close
            [1] => Array()
            [2] => 120
        )
    [32] => Array(
            [0] => tablerow_close
            [1] => Array()
            [2] => 121
        )
    [33] => Array(
            [0] => table_close
            [1] => Array()
            [2] => 121
        )
    [34] => Array(
            [0] => p_open
            [1] => Array()
            [2] => 121
        )
    [35] => Array(
            [0] => cdata
            [1] => Array(
                    [0] => def

                )
            [2] => 122
        )
    [36] => Array(
            [0] => p_close
            [1] => Array()
            [2] => 122
        )
    [37] => Array(
            [0] => document_end
            [1] => Array()
            [2] => 122
        )
)

Верхний уровень массива — это просто список. Каждый из его дочерних элементов описывает возвратную функцию, которая будет запущена под преобразователем (см. описание Renderer ниже), также как и индекс байта исходного текста, где был найден особенный «элемент» синтаксиса вики.

Единственная инструкция

Рассмотрим единственный элемент, который представляет единственную инструкцию, из списка инструкций, приведённого выше:

    [35] => Array
        (
            [0] => cdata
            [1] => Array
                (
                    [0] => def

                )
            [2] => 122
        )

Первый элемент (индекс 0) — это имя метода или функции в Renderer, которую необходимо выполнить.

Второй элемент (индекс 1) сам по себе является массивом, каждый из элементов которого является аргументом для метода Renderer, который будет вызван.

В этом случае имеется один аргумент со значением "def\n", поэтому вызов метода будет выглядеть так:

$Render->cdata("def\n");

Третий элемент (индекс 2) — это индекс байта первого символа, который «запустил» эту инструкцию в необработанном текстовом документе. Он должен быть таким же, как значение, возвращаемое функцией PHP strpos. Это можно использовать для извлечения разделов необработанного текста вики на основе позиций сгенерированных из него инструкций (пример ниже).

Примечание: Метод парсера parse дополняет необработанный текст вики предшествующим и последующим символом перевода строки, чтобы гарантировать корректный выход определенных состояний лексера, поэтому вам может потребоваться вычесть 1 из индекса байта, чтобы получить правильное местоположение в исходном необработанном тексте вики. Парсер также нормализует переводы строк в соответствии со стилем Unix (т. е. все \r\n становятся \n), поэтому документ, который видит лексер, может быть меньше того, который вы ему фактически дали.

Пример массив инструкций страницы с описанием синтаксиса можно найти здесь.

Renderer (преобразователь)

Renderer (преобразователь) — это класс (или коллекция функций), определяемый вами. Его интерфейс описан в файле inc/parser/renderer.php и выглядит так:

<?php
class Doku_Renderer {
 
    // вырезка
 
    public function header($text, $level) {}
 
    public function section_open($level) {}
 
    public function section_close() {}
 
    public function cdata($text) {}
 
    public function p_open() {}
 
    public function p_close() {}
 
    public function linebreak() {}
 
    public function hr() {}
 
    // вырезка
}

Он используется для документирования Renderer, хотя его также можно расширить, если вы хотите написать Renderer, который захватывает только определенные вызовы.

Основной принцип того, как инструкции, возвращаемые парсером, используются против Renderer, аналогичен понятию SAX XML API - инструкции представляют собой список имен функций/методов и их аргументов. Проходя по списку инструкций, каждая инструкция может быть вызвана против Renderer (т. е. методы, предоставляемые Renderer, являются callbacks). Unlike the SAX API, where only a few, fairly general, callbacks are available (e.g. tag_start, tag_end, cdata etc.). В отличие от SAX API , где доступно только несколько, довольно общих, обратных вызовов (например, tag_start, tag_end, cdata и т. д.), Renderer определяет более явный API , где методы обычно соответствуют один к одному акту генерации вывода. В разделе Renderer, показанном выше, методы p_open и p_close будут использоваться для вывода тегов <p> и </p> в XHTML, соответственно, в то время как header функция принимает два аргумента — некоторый текст для отображения и «уровень» заголовка, поэтому вызов типа header('Some Title', 1) будет выведен в XHTML типа <h1>Some Title</h1>.

Вызов рендерера с инструкциями

Клиентскому коду, использующему Parser, остается выполнить список инструкций для Renderer. Обычно это делается с помощью функции PHP call_user_func_array() function. Например;

// Получить список инструкций от парсера 
$instructions = $parser->parse($rawDoc);
 
// Создаем рендерер 
$renderer = new Doku_Renderer_xhtml();
 
// Проходим по инструкциям 
foreach ($instructions as $instruction) {
    // Выполняем обратный вызов для Renderer 
    call_user_func_array([$renderer, $instruction[0]], $instruction[1]);
}

Методы связи с рендерером

Ключевые методы Renderer для обработки различных типов ссылок:

function camelcaselink($link) {} // $link like "SomePage"
- Вероятно, это можно проигнорировать для проверки на спам — никто не должен иметь возможности ссылаться на сторонние сайты с таким синтаксисом.
function internallink($link, $title = null) {} // $link like "[[syntax]]"
- Хотя $link сам по себе является внутренним, $title может быть изображением, которое находится вне сайта, поэтому необходимо проверить
function externallink($link, $title = null) {}
- Оба изображения $link и $title (изображения) нуждаются в проверке
function interwikilink($link, $title = null, $wikiName, $wikiUri) {}
- Необходимость $title проверки изображений
function filelink($link, $title = null) {}
- Технически должны совпадать только действительные file:// URL-адреса, но, вероятно, лучше все равно проверить, плюс $title может быть стороннее изображение
function windowssharelink($link, $title = null) {}
- Должен соответствовать только допустимым URL-адресам общих ресурсов Windows, но в любом случае проверять наличие $title изображений
function emaillink($address, $title = null) {}
- $title может быть изображение. Проверить почту тоже?$titleможет быть изображение. Проверить почту тоже?
function internalmedialink($src, $title = null, $align = null, $width = null, $height = null, $cache = null) {}
- Это не требует проверки — должно ссылаться только на локальные изображения. $title само по себе не может быть изображением
function externalmedialink($src, $title = null, $align = null, $width = null, $height = null, $cache = null) {}
- $src нуждается в проверке

Особого внимания требуют методы, которые принимаютe $title аргумент, представляющий видимый текст ссылки, например;

<a href="https://www.example.com">This is the title</a>

Аргумент $title может иметь три возможных типа значений;

null: в вики-документе заголовок не указан.
string: в качестве заголовка использовалась простая текстовая строка
array (hash): в качестве заголовка использовано изображение.

Если это $title массив, он будет содержать ассоциативные значения, описывающие изображение;

$title = [
    // Может быть 'internalmedia' (локальное изображение) или 'externalmedia' (внешнее изображение) 
    'type' => 'internalmedia',
 
    // URL-адрес изображения (может быть URL-адресом wiki или https://static.example.com/img.png) 
    'src' => 'wiki:php-powered.png',
 
    // Для атрибута alt - строка или null 
    'title' => 'Powered by PHP',
 
    // 'left', 'right', 'center' или null
    'align' => 'right',
 
    // Ширина в пикселях или null 
    'width' => 50,
 
    // Высота в пикселях или null 
    'height' => 75,
 
    // Кэшировать ли изображение (для внешних изображений)
    'cache' => false,
];

Примеры

Следующие примеры показывают общие задачи, которые будут решаться с помощью парсера.

Основной вызов

Чтобы вызвать парсер со всеми режимами, и обработать синтаксис документа «Докувики»:

require_once DOKU_INC . 'parser/parser.php';
 
// Создать парсер
$Parser = & new Doku_Parser();
 
// Добавить обработчик
$Parser->Handler = & new Doku_Handler();
 
// Загрузить все режимы
$Parser->addMode('listblock',new Doku_Parser_Mode_ListBlock());
$Parser->addMode('preformatted',new Doku_Parser_Mode_Preformatted()); 
$Parser->addMode('notoc',new Doku_Parser_Mode_NoToc());
$Parser->addMode('header',new Doku_Parser_Mode_Header());
$Parser->addMode('table',new Doku_Parser_Mode_Table());
 
$formats = array (
    'strong', 'emphasis', 'underline', 'monospace',
    'subscript', 'superscript', 'deleted',
);
foreach ( $formats as $format ) {
    $Parser->addMode($format,new Doku_Parser_Mode_Formatting($format));
}
 
$Parser->addMode('linebreak',new Doku_Parser_Mode_Linebreak());
$Parser->addMode('footnote',new Doku_Parser_Mode_Footnote());
$Parser->addMode('hr',new Doku_Parser_Mode_HR());
 
$Parser->addMode('unformatted',new Doku_Parser_Mode_Unformatted());
$Parser->addMode('php',new Doku_Parser_Mode_PHP());
$Parser->addMode('html',new Doku_Parser_Mode_HTML());
$Parser->addMode('code',new Doku_Parser_Mode_Code());
$Parser->addMode('file',new Doku_Parser_Mode_File());
$Parser->addMode('quote',new Doku_Parser_Mode_Quote());
 
// Здесь требуются данные. Функции ''get*''остаются на ваше усмотрение
$Parser->addMode('acronym',new Doku_Parser_Mode_Acronym(array_keys(getAcronyms())));
$Parser->addMode('wordblock',new Doku_Parser_Mode_Wordblock(array_keys(getBadWords())));
$Parser->addMode('smiley',new Doku_Parser_Mode_Smiley(array_keys(getSmileys())));
$Parser->addMode('entity',new Doku_Parser_Mode_Entity(array_keys(getEntities())));
 
$Parser->addMode('multiplyentity',new Doku_Parser_Mode_MultiplyEntity());
$Parser->addMode('quotes',new Doku_Parser_Mode_Quotes());
 
$Parser->addMode('camelcaselink',new Doku_Parser_Mode_CamelCaseLink());
$Parser->addMode('internallink',new Doku_Parser_Mode_InternalLink());
$Parser->addMode('media',new Doku_Parser_Mode_Media());
$Parser->addMode('externallink',new Doku_Parser_Mode_ExternalLink());
$Parser->addMode('email',new Doku_Parser_Mode_Email());
$Parser->addMode('windowssharelink',new Doku_Parser_Mode_WindowsShareLink());
$Parser->addMode('filelink',new Doku_Parser_Mode_FileLink());
$Parser->addMode('eol',new Doku_Parser_Mode_Eol());
 
// Загрузить исходный документ вики
$doc = file_get_contents(DOKU_DATA . 'wiki/syntax.txt');
 
// Получить список инструкций
$instructions = $Parser->parse($doc);
 
// Создать преобразователь
require_once DOKU_INC . 'parser/xhtml.php';
$Renderer = & new Doku_Renderer_XHTML();
 
# Здесь загрузите в преобразователь данные (например, типа смайлов)

// Проходимся по всем инструкциям
foreach ( $instructions as $instruction ) {
 
    // Выполняем обратный вызов через преобразователь
    call_user_func_array(array(&$Renderer, $instruction[0]),$instruction[1]);
}
 
// Отображаем выходные данные
echo $Renderer->doc;

Выбор текста (для фрагментов)

Следующий код показывает, как выбрать фрагмент исходного текста, используя инструкции, полученные из парсера;

// Создаём парсер
$Parser = & new Doku_Parser();
 
// Добавляем обработчик
$Parser->Handler = & new Doku_Handler();
 
// Загружаем режим header для поиска заголовков
$Parser->addMode('header',new Doku_Parser_Mode_Header());
 
// Загружаем режимы, которые могут содержать разметку,
// которая может быть принята за заголовок
$Parser->addMode('listblock',new Doku_Parser_Mode_ListBlock());
$Parser->addMode('preformatted',new Doku_Parser_Mode_Preformatted()); 
$Parser->addMode('table',new Doku_Parser_Mode_Table());
$Parser->addMode('unformatted',new Doku_Parser_Mode_Unformatted());
$Parser->addMode('php',new Doku_Parser_Mode_PHP());
$Parser->addMode('html',new Doku_Parser_Mode_HTML());
$Parser->addMode('code',new Doku_Parser_Mode_Code());
$Parser->addMode('file',new Doku_Parser_Mode_File());
$Parser->addMode('quote',new Doku_Parser_Mode_Quote());
$Parser->addMode('footnote',new Doku_Parser_Mode_Footnote());
$Parser->addMode('internallink',new Doku_Parser_Mode_InternalLink());
$Parser->addMode('media',new Doku_Parser_Mode_Media());
$Parser->addMode('externallink',new Doku_Parser_Mode_ExternalLink());
$Parser->addMode('email',new Doku_Parser_Mode_Email());
$Parser->addMode('windowssharelink',new Doku_Parser_Mode_WindowsShareLink());
$Parser->addMode('filelink',new Doku_Parser_Mode_FileLink());
 
// Загружаем исходный документ вики
$doc = file_get_contents(DOKU_DATA . 'wiki/syntax.txt');
 
// Получаем перечень инструкций
$instructions = $Parser->parse($doc);
 
// Используем эти переменные, чтобы узнать,
// находимся ли мы внутри необходимого фрагмента
$inSection = FALSE;
$startPos = 0;
$endPos = 0;
 
// Проходимся по всем инструкциям
foreach ( $instructions as $instruction ) {
 
    if ( !$inSection ) {
 
        // Ищем заголовки в списках
        if ( $instruction[0] == 'header' &&
                trim($instruction[1][0]) == 'Lists' ) {
 
            $startPos = $instruction[2];
            $inSection = TRUE;
        }
    } else {
 
        // Ищем конец фрагмента
        if ( $instruction[0] == 'section_close' ) {
            $endPos = $instruction[2];
            break;
        }
    }
}
 
// Нормализуем и разбиваем документ
$doc = "\n".str_replace("\r\n","\n",$doc)."\n";
 
// Получаем текст, идущий перед фрагментом, который нам необходим
$before = substr($doc, 0, $startPos);
$section = substr($doc, $startPos, ($endPos-$startPos));
$after = substr($doc, $endPos);

Управление входными файлами с данными в шаблонах

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

Каждый подходящий режим принимает простой список элементов, который он собирает в список шаблонов для регистрации в анализаторе.

Например:

// Простой список вхождений смайлов...
$smileys = array(
    ':-)',
    ':-(',
    ';-)',
    // и т. д.
    );
 
// Создать режим
$SmileyMode = & new Doku_Parser_Mode_Smiley($smileys);
 
// Добавить режим в парсер
$Parser->addMode($SmileyMode);

Для парсера не имеет значения выходной формат смайлов.

Другие режимы, где применяется подобный подход, определяются классами;

Doku_Parser_Mode_Acronym — для сокращений;
Doku_Parser_Mode_Wordblock — для блоков специфических слов (например, ненормативной лексики);
Doku_Parser_Mode_Entity — для типографических символов.

Конструктор каждого класса принимает в качестве параметра список указанных элементов.

На практике возникает необходимость в функциях для извлечения данных из конфигурационных файлов и размещение ассоциативных массивов в статической переменной, например:

function getSmileys() {
 
    static $smileys = NULL;
 
    if ( !$smileys ) {
 
        $smileys = array();
 
        $lines = file( DOKU_CONF . 'smileys.conf');
 
        foreach($lines as $line){
 
            // игнорировать комментарии
            $line = preg_replace('/#.*$/','',$line);
 
            $line = trim($line);
 
            if(empty($line)) continue;
 
            $smiley = preg_split('/\s+/',$line,2);
 
            // Собрать ассоциативный массив
            $smileys[$smiley[0]] = $smiley[1];
        }
    }
 
    return $smileys;
}

Эта функция может быть использована следующим образом:

// Загрузить шаблоны смайлов в режим
$SmileyMode = & new Doku_Parser_Mode_Smiley(array_keys(getSmileys()));

// Загрузить ассоциативный массив в Преобразователь
$Renderer->smileys = getSmileys();

Замечание: проверка ссылок, которые необходимо блокировать, обрабатывается другим способом, описанным ниже.

Проверка ссылок на спам

В идеале ссылки требуется проверять на спам до размещения документа (после редактирования).

Этот пример следует использовать осторожно. Он создаёт полезные точки связывания, но по результатам тестирования является очень медленным — возможно проще использовать функцию, которая «закрывает глаза» на синтаксис, но ищет во всем документе ссылки, сверяя их с «чёрным списком». Между тем, этот пример может быть полезным как основа для построения «карты вики» или поиска «требуемых страниц» посредством проверки внутренних ссылок.

Это можно сделать, создав специальный преобразователь, который проверяет только относящиеся к ссылкам обратные вызовы и сверяет ULR с «чёрным списком».

Требуется функция для загрузки файла spam.conf и связывания его с единственным регулярным выражением:

Недавно протестировал этот подход (единственное регулярное выражение) с использованием последней версии «чёрного списка» с blacklist.chongqed.org и получил ошибки о том, что окончательное регулярное выражение слишком велико. Возможно, следует разбить регулярное выражение на маленькие кусочки и возвращать их как массив.

function getSpamPattern() {
    static $spamPattern = NULL;
 
    if ( is_null($spamPattern) ) {
 
        $lines = @file(DOKU_CONF . 'spam.conf');
 
        if ( !$lines ) {
 
            $spamPattern = '';
 
        } else {
 
            $spamPattern = '#';
            $sep = '';
 
            foreach($lines as $line){
 
                $line = preg_replace('/#.*$/','',$line);
 
                // Игнорировать пустые строки
                $line = trim($line);
                if(empty($line)) continue;
 
                $spamPattern.= $sep.$line;
 
                $sep = '|';
            }
 
            $spamPattern .= '#si';
        }
    }
 
    return $spamPattern;
}

Теперь нам нужно расширить основной преобразователь ещё одним, который проверяет только ссылки:

require_once DOKU_INC . 'parser/renderer.php';
 
class Doku_Renderer_SpamCheck extends Doku_Renderer {
 
    // Здесь должен быть код, выполняющий инструкции
    var $currentCall;
 
    // Массив инструкций, которые содержат спам
    var $spamFound = array();
 
    // PCRE-шаблон для нахождения спама
    var $spamPattern = '#^$#';
 
    function internallink($link, $title = NULL) {
        $this->__checkTitle($title);
    }
 
    function externallink($link, $title = NULL) {
        $this->__checkLinkForSpam($link);
        $this->__checkTitle($title);
    }
 
    function interwikilink($link, $title = NULL) {
        $this->__checkTitle($title);
    }
 
    function filelink($link, $title = NULL) {
        $this->__checkLinkForSpam($link);
        $this->__checkTitle($title);
    }
 
    function windowssharelink($link, $title = NULL) {
        $this->__checkLinkForSpam($link);
        $this->__checkTitle($title);
    }
 
    function email($address, $title = NULL) {
        $this->__checkLinkForSpam($address);
        $this->__checkTitle($title);
    }
 
    function internalmedialink ($src) {
        $this->__checkLinkForSpam($src);
    }
 
    function externalmedialink($src) {
        $this->__checkLinkForSpam($src);
    }
 
    function __checkTitle($title) {
        if ( is_array($title) && isset($title['src'])) {
            $this->__checkLinkForSpam($title['src']);
        }
    }
 
    // Поиск по шаблону осуществляется здесь
    function __checkLinkForSpam($link) {
        if( preg_match($this->spamPattern,$link) ) {
            $spam = $this->currentCall;
            $spam[3] = $link;
            $this->spamFound[] = $spam;
        }
    }
}

Обратите внимание на строку $spam[3] = $link; в методе __checkLinkForSpam. Она вставляет дополнительный элемент в список найденных спамовых инструкций, позволяя легко определить, какие URL были «плохими».

Наконец мы можем использовать преобразователь с проверкой на спам:

// Создать парсер
$Parser = & new Doku_Parser();
 
// Добавить обработчик
$Parser->Handler = & new Doku_Handler();
 
// Добавить режимы, которые могут содержать разметку,
// которая ошибочно будет принята за ссылку
$Parser->addMode('preformatted',new Doku_Parser_Mode_Preformatted()); 
$Parser->addMode('unformatted',new Doku_Parser_Mode_Unformatted());
$Parser->addMode('php',new Doku_Parser_Mode_PHP());
$Parser->addMode('html',new Doku_Parser_Mode_HTML());
$Parser->addMode('code',new Doku_Parser_Mode_Code());
$Parser->addMode('file',new Doku_Parser_Mode_File());
$Parser->addMode('quote',new Doku_Parser_Mode_Quote());
 
// Загружаем режим link...
$Parser->addMode('internallink',new Doku_Parser_Mode_InternalLink());
$Parser->addMode('media',new Doku_Parser_Mode_Media());
$Parser->addMode('externallink',new Doku_Parser_Mode_ExternalLink());
$Parser->addMode('email',new Doku_Parser_Mode_Email());
$Parser->addMode('windowssharelink',new Doku_Parser_Mode_WindowsShareLink());
$Parser->addMode('filelink',new Doku_Parser_Mode_FileLink());
 
// Загружаем исходный документ вики
$doc = file_get_contents(DOKU_DATA . 'wiki/spam.txt');
 
// Получить список инструкций
$instructions = $Parser->parse($doc);
 
// Создать преобразователь
require_once DOKU_INC . 'parser/spamcheck.php';
$Renderer = & new Doku_Renderer_SpamCheck();
 
// Загрузить шаблон спама
$Renderer->spamPattern = getSpamPattern();
 
// Пройтись по всем инструкциям
foreach ( $instructions as $instruction ) {
 
    // Сохранить текущую инструкцию
    $Renderer->currentCall = $instruction;
 
    call_user_func_array(array(&$Renderer, $instruction[0]),$instruction[1]);
}
 
// Что за спам был найден?
echo '<pre>';
print_r($Renderer->spamFound);
echo '</pre>';

Поскольку нам не нужны все режимы синтаксиса, проверка спама таким способом будет быстрее, чем обычный парсинг документа.

Добавление синтаксической конструкции

Предупреждение: приведённый ниже код ещё не испытан — это только пример.

Простая задача по модификации парсера: этот пример будет добавлять тэг-«закладку», который может быть использован для создания якоря в документе для создания ссылки на него.

Синтаксис для тэга будет таким:

BM{Моя закладка}

Строка «Моя закладка» является наименование закладки, а BM {} идентифицируется как сама закладка. В HTML эта конструкция будет соответствовать:

<a name="Моя закладка"></a>

Добавление этой синтаксической конструкции требует следующих шагов:

создать синтаксический режим парсера, для регистрации в лексическом анализаторе;
обновить код функции Doku_Parser_Substition, находящейся в конце файла parser.php и которая используется для быстрого получения списка режимов (используется в классах вродеDoku_Parser_Mode_Table);
обновить код обработчика, дополнив его методом, «ловящим» вхождения закладок;
обновление абстрактного класса преобразователя и какого-нибудь конкретного преобразователя.

Создание режима парсера подразумевает расширение класса Doku_Parser_Mode и перегрузкой метода connectTo:

class Doku_Parser_Mode_Bookmark extends Doku_Parser_Mode {
 
    function connectTo($mode) {
        // Разрешаются слова и пробелы
        $this->Lexer->addSpecialPattern('BM\{[\w ]+\}',$mode,'bookmark');
    }
 
}

Будет осуществляться поиск целой закладки с использованием единственного шаблона (извлечение имени закладки из остального синтаксиса будет осущевляться обработчиком). Используется метод addSpecialPattern анализатора, так что закладка присутствует в своём собственном состоянии.

Замечание: анализатор не требует ограничителей шаблона — он заботиться об этом за вас.

Поскольку ничто внутри закладки не должно рассматриваться как годная разметка вики, связывание с другими режимами, которые может принимать этот, отсутствует.

Следующая функция Doku_Parser_Substition в файле inc/parser/parser.php требует обновления, чтобы она возвращала в списке новый режим с наименованием bookmark;

function Doku_Parser_Substition() {
    $modes = array(
        'acronym','smiley','wordblock','entity','camelcaselink',
        'internallink','media','externallink','linebreak','email',
        'windowssharelink','filelink','notoc','multiplyentity',
        'quotes','bookmark',
 
    );
    return $modes;
}

Эта функция лишь помогает в регистрации режима с другими режимами, которые получают его (например, списки могут содержать этот режим — ваша ссылка может быть внутри списка).

Замечание: существует похожая функция, вроде Doku_Parser_Protected и Doku_Parser_Formatting, которые возвращают разные группы режимов. Группировка различных типов синтаксиса не является полностью совершенной, но всё равно остаётся полезной для экономии кода.

Описав синтаксис, мы должны добавить в обработчик новый метод, который сравнивает наименование режима (т. е.bookmark).

class Doku_Handler {
 
    // ...
 
    // $match - строка, которая сравнивается анализатором
    //          с регулярным выражением для закладок
    // $state идентифицирует тип совпадения (см. выше)
    // $pos - индекс байта первого символа совпадения в исходном документе
    function bookmark($match, $state, $pos) {
 
        // Технически не следует беспокоится о состоянии:
        // оно всегда будет DOKU_LEXER_SPECIAL, если
        // нет серьёзных багов
        switch ( $state ) {
 
            case DOKU_LEXER_SPECIAL:
 
                // Попытка извлечения наименования закладки
                if ( preg_match('/^BM\{(\w{1,})\}$/', $match, $nameMatch) ) {
 
                    $name = $nameMatch[1];
 
                    // arg0: наименование вызываемого метода преобразователя
                    // arg1: массив аргументов для метода преобразователя
                    // arg2: индекс байта
                    $this->__addCall('bookmark', array($name), $pos);
 
                // Если у закладки нет годного имени,
                //  пропускаем не меняя как cdata
                } else {
 
                    $this->__addCall('cdata', array($match), $pos);
 
                }
            break;
 
        }
 
        // Должно вернуть TRUE или анализатор будет остановлен
        return TRUE;
    }
 
    // ...
 
}

Последний этап — обновление кода преобразователя (renderer.php) новой функцией и её реализация в XHTML преобразовании (xhtml.php):

class Doku_Renderer {
 
    // ...
 
    function bookmark($name) {}
 
    // ...
 
}

class Doku_Renderer_XHTML {
 
    // ...
 
    function bookmark($name) {
        $name = $this->__xmlEntities($name);
 
        // id is required in XHTML while name still supported in 1.0
        echo '<a class="bookmark" name="'.$name.'" id="'.$name.'"></a>';
 
    }
 
    // ...
 
}

См. скрипт tests/parser_replacements.test.php в качестве примера того, как можно использовать этот код.

Добавление синтаксиса форматирования (с состоянием)

Предупреждение: нижеприведённый код ещё не протестирован — это только пример.

Для того, чтобы показать расширенное использование анализатора, этот пример добавляет разметку, которая позволяет пользователям менять цвет обрамляемый текст на красный, жёлтый или зелёный.

Разметка будет выглядеть так:

<red>Это красный цвет</red>.
Это чёрный цвет
<yellow>Это жёлтый цвет</yellow>.
Это тоже чёрный цвет
<green>Это зелёный цвет</green>.

Шаги, необходимые для внедрения данной возможности, в сущности, являются такими же, как в предыдущем примере, начинаются с нового синтаксического режима, но добавляет некоторые детали, поскольку задействуются другие режимы:

class Doku_Parser_Mode_TextColors extends Doku_Parser_Mode {
 
    var $color;
 
    var $colors = array('red','green','blue');
 
    function Doku_Parser_Mode_TextColor($color) {
 
        // Предотвращает ошибки использования этого режима
        if ( !array_key_exists($color, $this->colors) ) {
            trigger_error('Invalid color '.$color, E_USER_WARNING);
        }
 
        $this->color = $color;
 
        // Этот режим принимает другие режимы:
        $this->allowedModes = array_merge (
            Doku_Parser_Formatting($color),
            Doku_Parser_Substition(),
            Doku_Parser_Disabled()
        );
 
    }
 
    // connectTo вызывается однократно для каждого режима, зарегистрированного анализатором
    function connectTo($mode) {
 
        // Шаблон с просмотром вперёд проверяет наличие закрывающего тэга...
        $pattern = '<'.$this->color.'>(?=.*</'.$this->color.'>)';
 
        // arg0: шаблон сравнения при входе в режим;
        // arg1: другие режимы, может сравниваться этот шаблон;
        // arg2: наименование режима.
        $this->Lexer->addEntryPattern($pattern,$mode,$this->color);
    }
 
    // post connect вызывается однократно
    function postConnect() {
 
        // arg0: шаблон сравнения при выходе из режима;
        // arg1: наименование режима.
        $this->Lexer->addExitPattern('</'.$this->color.'>',$this->color);
 
    }
 
}

Некоторые особенности вышеприведённых классов:

В действительности представляют множество режимов, один для каждого цвета. Цвета следует выделять в отдельные режимы так, что, например, </green> не будет закрывающим тэгом для <red>.
Эти режимы могут содержать, например, <red>**Предупреждение**</red> для полужирного текста красного цвета. Это регистрируется в конструкторе класса назначением полученных наименований режимов свойству allowedModes.
Когда регистрируется входной шаблон, имеет смысл проверить существование выходного шаблона (с помощью просмотра вперёд). Это поможет в защите пользователей от них самих, когда они забудут добавить закрывающий тэг.
Входной шаблон требует регистрации для каждого режима, внутри которого тэги <color /> могут использоваться. Нам требуется толь один выходной шаблон, помещённый в метод postConnect, который исполняется однократно, после всех вызовов connectTo по всем вызванным режимам.

Когда с классом режимами обработки покончено, новые режимы требуется добавить в в функцию Doku_Parser_Formatting:

function Doku_Parser_Formatting($remove = '') {
    $modes = array(
        'strong', 'emphasis', 'underline', 'monospace', 
        'subscript', 'superscript', 'deleted',
        'red','yellow','green',
        );
    $key = array_search($remove, $modes);
    if ( is_int($key) ) {
        unset($modes[$key]);
    }
 
    return $modes;
}

Замечание: эта функция обрабатывается, чтобы снять режим для предотвращения включения режима форматирования в самого себя (так, например, нежелательно: <red>Срочное<red>и важное</red>сообщение</red>).

Далее обработчик должен быть обновлён методами для каждого цвета:

class Doku_Handler {
 
    // ...
 
    function red($match, $state, $pos) {
        // Метод nestingTag в обработчике предотвращает
        // многократное повторение одного и того же кода.
        // Он создаёт открывающий и закрывающий инструкции
        // для входных и выходных шаблонов,
        // пропуская остальные как cdata.
        $this->__nestingTag($match, $state, $pos, 'red');
        return TRUE;
    }
 
    function yellow($match, $state, $pos) {
        $this->__nestingTag($match, $state, $pos, 'yellow');
        return TRUE;
    }
 
    function green($match, $state, $pos) {
        $this->__nestingTag($match, $state, $pos, 'green');
        return TRUE;
    }
 
    // ...
 
}

Наконец мы может обновить преобразователи:

class Doku_Renderer {
 
    // ...
 
    function red_open() {}
    function red_close() {}
 
    function yellow_open() {}
    function yellow_close() {}
 
    function green_open() {}
    function green_close() {}
 
    // ...
 
}

class Doku_Renderer_XHTML {
 
    // ...
 
    function red_open() {
        echo '<span class="red">';
    }
    function red_close() {
        echo '</span>';
    }
 
    function yellow_open() {
        echo '<span class="yellow">';
    }
    function yellow_close() {
        echo '</span>';
    }
 
    function green_open() {
        echo '<span class="green">';
    }
    function green_close() {
        echo '</span>';
    }
 
    // ...
 
}

См. скрипт tests/parser_formatting.test.php в качестве примера того, как можно использовать этот код.

Добавление блочных синтаксических конструкций

Предупреждение: приведённый ниже код ещё не тестировался — это только пример.

Развивая предыдущий пример, этот будет создавать новый тэг для разметки сообщений о том, что ещё предстоит сделать. Пример использования может выглядеть так:

===== Синтаксис цитирования в вики =====

Этот синтаксис позволяет

<todo>
Опишите синтаксис цитирования '>'
</todo>

Другой текст

Этот синтаксис позволяет искать страницы вики и находить вопросы, которые предстоит решить, выделяя их в документе бросающимся в глаза стилем.

Особенностью данного синтаксиса является то, что он должен отображаться в отдельном блоке документа (например, внутри

, так что он с помощью CSS может «плавать»). Это требует модификации класса Doku_Handler_Block, который пробегает по всем инструкциям, после того, как обработчиком найдены все вхождения, и заботиться о добавлении тэгов <p/>.

Режим парсера для этого синтаксиса может быть таким:

class Doku_Parser_Mode_Todo extends Doku_Parser_Mode {
 
    function Doku_Parser_Mode_Todo() {
 
        $this->allowedModes = array_merge (
            Doku_Parser_Formatting(),
            Doku_Parser_Substition(),
            Doku_Parser_Disabled()
        );
 
    }
 
    function connectTo($mode) {
 
        $pattern = '<todo>(?=.*</todo>)';
        $this->Lexer->addEntryPattern($pattern,$mode,'todo');
    }
 
    function postConnect() {
        $this->Lexer->addExitPattern('</todo>','todo');
    }
 
}

Затем этот режим добавляется в функцию Doku_Parser_BlockContainers в файле parser.php:

function Doku_Parser_BlockContainers() {
    $modes = array(
        'footnote', 'listblock', 'table','quote',
        // горизонтальные разрывы нарушают принцип, но они не могут использоваться в таблицах / списках, 
        // так что вставляем их сюда
        'hr',
        'todo',
    );
    return $modes;
}

Обновление класса Doku_Handler:

class Doku_Handler {
 
    // ...
 
    function todo($match, $state, $pos) {
        $this->__nestingTag($match, $state, $pos, 'todo');
        return TRUE;
    }
 
    // ...
 
}

Класс Doku_Handler_Block (см. файл inc/parser/handler.php) также нуждается в обновлении, чтобы регистрировать открывающие и закрывающие инструкции todo:

class Doku_Handler_Block {
 
    // ...
 
    var $blockOpen = array(
            'header',
            'listu_open','listo_open','listitem_open',
            'table_open','tablerow_open','tablecell_open','tableheader_open',
            'quote_open',
            'section_open', // Needed to prevent p_open between header and section_open
            'code','file','php','html','hr','preformatted',
            'todo_open',
        );
 
    var $blockClose = array(
            'header',
            'listu_close','listo_close','listitem_close',
            'table_close','tablerow_close','tablecell_close','tableheader_close',
            'quote_close',
            'section_close', // Needed to prevent p_close after section_close
            'code','file','php','html','hr','preformatted',
            'todo_close',
        );

Регистрация todo_open и todo_close в массивах $blockOpen и $blockClose сообщает классу Doku_Handler_Block, что любые предыдущие абзацы должны быть закрыты до входа в секцию todo, а новый абзац должен начинаться после секции todo. Внутри todo дополнительные абзацы не вставляются.

После этого должен быть обновлён код преобразователя:

class Doku_Renderer {
 
    // ...
 
    function todo_open() {}
    function todo_close() {}
 
    // ...
 
}

class Doku_Renderer_XHTML {
 
    // ...
 
    function todo_open() {
        echo '<div class="todo">';
    }
    function todo_close() {
        echo '</div>';
    }
 
    // ...
 
}

Сериализация инструкций преобразователя

Список выводимых обработчиком инструкций можно сериализировать, чтобы устранить повторную обработку исходного документа при каждом запросе, если содержание документа не менялось.

Самая простая реализация может быть такой:

$ID = DOKU_DATA . 'wiki/syntax.txt';
$cacheID = DOKU_CACHE . $ID.'.cache';
 
// Если кэш-файл отсутствует или утратил актуальность
// (исходный документ модифицирован), получить «свежий» список инструкций
if ( !file_exists($cacheID) || (filemtime($ID) > filemtime($cacheID)) ) {
 
    require_once DOKU_INC . 'parser/parser.php';
 
    // Создать парсер
    $Parser = & new Doku_Parser();
 
    // Добавить обработчик
    $Parser->Handler = & new Doku_Handler();
 
    // Загрузить все режимы
    $Parser->addMode('listblock',new Doku_Parser_Mode_ListBlock());
    $Parser->addMode('preformatted',new Doku_Parser_Mode_Preformatted()); 
    $Parser->addMode('notoc',new Doku_Parser_Mode_NoToc());
    $Parser->addMode('header',new Doku_Parser_Mode_Header());
    $Parser->addMode('table',new Doku_Parser_Mode_Table());
 
    // и т. д., и т. п.
 
    $instructions = $Parser->parse(file_get_contents($filename));
 
    // Сериализировать и кэшировать 
    $sInstructions = serialize($instructions);
 
    if ($fh = @fopen($cacheID, 'a')) {
 
        if (fwrite($fh, $sInstructions) === FALSE) {
            die("Cannot write to file ($cacheID)");
        }
 
        fclose($fh);
    }
 
} else {
    // Загрузить и десериализировать
    $sInstructions = file_get_contents($cacheID);
    $instructions = unserialize($sInstructions);
}
 
$Renderer = & new Doku_Renderer_XHTML();
 
foreach ( $instructions as $instruction ) {
    call_user_func_array(
        array(&$Renderer, $instruction[0]),$instruction[1]
        );
}
 
echo $Renderer->doc;

Замечание: эта реализация не является полной. Что должно просходить, если кто-либо, например, модифицирует файл smiley.conf, добавив новый смайл? Это изменение должно порождать изменение кэша с обработкой нового смайла. Также необходимо позаботиться о блокировке файлов (или их переименовании).

Сериализация парсера

По аналогии с приведённым выше примером, возможна сериализация самого парсера до начала обработки. Поскольку установка режимов поддерживает довольно высокую перегрузку, этот пример может немного увеличить производительность. По неточной оценке, обработка страницы syntax в медленной системе занимает около 1,5-а секунд для завершения без сериализации и около 1,25-х секунды в версии парсера с поддержкой сериализации.

Если коротко, то сериализация может быть реализована таким способом:

$cacheId = DOKU_CACHE . 'parser.cache';
 
if ( !file_exists($cacheId) ) {
 
    // Создаём парсер
    $Parser = & new Doku_Parser();
    $Parser->Handler = & new Doku_Handler();
 
    // Загружаем все режимы
    $Parser->addMode('listblock',new Doku_Parser_Mode_ListBlock());
    $Parser->addMode('preformatted',new Doku_Parser_Mode_Preformatted());
 
    # и т. д., и т. п.
    
    // ВАЖНО: вызов connectModes()
    $Parser->connectModes();
 
    // Сериализация
    $sParser = serialize($Parser);
 
    // Запись в файл
    if ($fh = @fopen($cacheID, 'a')) {
 
        if (fwrite($fh, $sParser) === FALSE) {
            die("Cannot write to file ($cacheID)");
        }
 
        fclose($fh);
    }
 
} else {
    // Загружаем сериализированную версию
    $sParser = file_get_contents($cacheID);
    $Parser = unserialize($sParser);
}
 
$Parser->parse($doc);

Некоторые замечания по реализации, не упомянутые выше:

Для некоторых файлов вместо записи требуется блокировка, в противном случае в ответ на запрос может быть получен частично кэшированный файл, если он будет считываться, пока продолжается запись.
Что следует делать, если обновляется один из файлов *.conf? Необходимо очистить кэш.
Могут быть различные версии парсера (например, с проверкой на спам), так что используйте кэш-идентификаторы (cache IDs).

Тестирование

Тесты программных единиц обеспечивают использование «Simple Test for PHP». «Simple Test» является отличным инструментом для тестирования единиц php-кода. Особенно выделяются блестящая документация (см. simpletest.sourceforge.net и www.lastcraft.com/simple_test.php) и хорошо продуманый код, обеспечивающий «прозрачное» решение многих вопросов (вроде перехвата ошибок PHP и сообщения о них в результатах тестирования).

Для парсера «Докувики» тесты проводились по всем внедряемым синтаксическим конструкциям, и я очень сильно рекомендую написание новых тестов, если добавляется новый синтаксис.

Чтобы запустить тесты, вам следует модифицировать файл tests/testconfig.php, указав корректные директории «Simple Test» и «Докувики».

Некоторые заметки и рекомендации:

Повторно запускайте тесты каждый раз, когда вы меняете что-нибудь в парсере — проблемы немедленно выплывают на поверхность, экономя кучу времени.
Это только тесты для специфических ситуаций. Они не гарантируют отсутствие ошибок, если в этих специфических ситуациях работают корректно.
Если найдена ошибка, в процессе её устранения напишите тесты (даже лучше, до её устранения), чтобы предотвратить её повторное возникновение.

Ошибки и проблемы

Некоторые вопросы остаются за рамками подробного рассмотрения.

Важность порядка добавления режимов

Требуется выполение не столько «правил», сколько порядка, в котором добавляются режимы (парсер этого не проверяет). В особенности, режим eol должен быть загружен последним, т. к. он «съедает» «обёрточные» символы, что может нарушить корректную работу других режимов, вроде list или table.

В общем случае рекомендуется загружать режимы в порядке, описанном выше в первом примере.

По моим наработкам, порядок важен, только если два и более режима имеют шаблоны, с которыми могут сравниваться одинаковые совокупности символов - в этом случае «выиграет» режим, имеющий низший порядковый номер. Синтаксический плагин может извлечь из этого выгоду, заменяя оригинальный обработчик, в качестве примера см. плагин «Code» — ChrisS 2005-07-30

Замены «блокиратора слов»

В оригинале функционирование «блокиратора слов» wordblock заключалось в сравнении URL ссылок с «чёрным списком». Сейчас этот режим используется для нахождения грубых слов. Для блокирования спамовых URL лучше использовать приведённый выше пример.

Рекомендация — файл conf/wordblock.conf следует переименовать в conf/spam.conf, содержащий «чёрный список» URL. Новый файлconf/badwords.conf будет содержать список цензурируемых грубых слов.

Слабые моменты

С точки зрения архитектуры, наихудшие части кода находятся в файле inc/parser/handler.php, преимущественно в «re-writing»-классах;

Doku_Handler_List (inline re-writer)
Doku_Handler_Preformatted (inline re-writer)
Doku_Handler_Quote (inline re-writer)
Doku_Handler_Table (inline re-writer)
Doku_Handler_Section (post processing re-writer)
Doku_Handler_Block (post processing re-writer)
Doku_Handler_Toc (post processing re-writer)

«Inline re-writers» используются, пока обработчик получает вхождения от анализатора, в то время как «post processing re-writers», вызываются из Doku_Handler::__finalize() и выполняются однократно в отношении полного списка инструкций, созданных обработчиком.

Возможно лучше устранить Doku_Handler_List, Doku_Handler_Quote и Doku_Handler_Table, использовав взамен многострочные лексические режимы.

Также возможно лучше изменить Doku_Handler_Section и Doku_Handler_Toc в «inline re-writers«, срабатывающие на вхождения заголовков, принимаемых Обработчиком.

Самое «больное место» — это класс Doku_Handler_Block, отвечающий за вставку абзацев в инструкции. Имеет значение добавить в него больше абстракций для облегчения разработки, но в общем-то я не вижу каких-либо путей полного его устранения.

«Жадные» тэги

Рассмотрим следующий синтаксис вики:

Привет, <sup>Мир! 

----

<sup>Пока,</sup> Мир...

Пользователь забыл закрыть первый тэг <sup>.

В результате получится:

Привет, ^{Мир!

—-

<sup>Пока,} Мир…

Первый тэг <sup> оказался слишком «жадным» в проверке своего входного шаблона.

Это применимо ко всем подобным режимам. Входные шаблоны проверяют наличие закрывающего тэга, но также они должны проверять, чтобы раньше не встретился второй открывающий тэг.

Сноски через список

В сущности, если сноска закрывается через несколько элементов списка, это вызывает эффект открывающей инструкции сноски без соответствующей закрывающей. Вот пример синтаксиса, вызывающего проблему:

  *((A))
    *(( B
  * C ))

Это будет происходить до тех пор, пока пользователи не поправят страницу. Решение — разбить захват элементов списка в многострочные режимы (сейчас для списков есть только единственный режим listblock).

Захват «обёрточных» символов

Баг № 261.

Поскольку синтаксис заголовка, горизонтальной линии, списка, таблицы, цитаты и неформатируемого (выделяемого) текста полагается на «обёрточные» символы для разметки своих начала и окончания, им требуются регулярные выражения, которые поглощают «обёрточные» символы. Это означает, что пользователь должен добавлять «обёрточные» символы, если таблица находится сразу после списка, например:

До списка
  - Элемент списка
  - Элемент списка
| Ячейка A | Ячейка B |
| Ячейка C | Ячейка D |
После таблицы

Выдаёт:

До списка

Элемент списка
Элемент списка

| Ячейка A | Ячейка B |

Ячейка C

Ячейка D

После таблицы

Заметьте, что первая строка таблицы воспринимается как обычный текст.

Чтобы скорректировать это, синтаксис вики должен иметь дополнительную «обёртку» между списком и таблицей:

До списка
  - Элемент списка
  - Элемент списка

| Ячейка A | Ячейка B |
| Ячейка C | Ячейка D |
После таблицы

Что будет выглядеть следующим образом:

До списка

Элемент списка
Элемент списка

Ячейка A	Ячейка B
Ячейка C	Ячейка D

После таблицы

Без сканирования текста множества раз (некая разновидность «предварительных» операций, которые вставляют «обёртку»), едва ли можно найти простое решение.

Проблемы списков, таблиц и цитат

Для синтаксиса списков, таблиц и цитат есть вероятность, что использование внутри их другого синтаксиса «съест» несколько строк. Например, таблица вроде:

| Cell A | <sup>Cell B |
| Cell C | Cell D</sup> |
| Cell E | Cell F |

выдаёт:

Cell A	^{Cell B \| \| Cell C \| Cell D}
Cell E	Cell F

В идеале должно быть преобразовано так:

Cell A	<sup>Cell B
Cell C	Cell D</sup>
Cell E	Cell F

Т. е. открывающий тэг <sup> должен игнорироваться, если в текущей ячейке отсутствует закрывающий тэг.

Для устранения этого требуется поддержка многострочного режима внутри таблиц, списков и цитат.

Сноски и блоки

Внутри сносок блоки игнорируются, вместо этого используется эквивалент инструкции <br/>. Это связано с неудобным в разработке классом Doku_Handler_Block. Если внутри сноски используются таблица, список, цитата или горизонтальная линия, это сработает как абзац.

Устраняется модификацией класса Doku_Handler_Block, однако рекомендуется предварительно тщательно ознакомиться с его устройством.

Заголовки

Текущие заголовки могут находиться на той же строке, что и предшествующий текст. Это вытекает из эффекта, рассмотренного выше в вопросе «Захват строк», и требует некоторой предварительной обработки для устранения. Например:

До заголовка есть
Некоторый текст == Заголовок ==
После заголовка

Если бы поведение было бы таким же, как в оригинальном парсере «Докувики», преобразование было бы таким:

До заголовка есть Некоторый текст == Заголовок == После заголовка

Но в результате будет:

До заголовка есть Некоторый текст

Заголовок

После заголовка

Конфликт блоков и списков

Существует проблема: если до списка находится пустая строка с двумя пробелами, всё это вместе будет интерпретироваться как блок:

* list item
* list item 2

Что ещё необходимо сделать

Вот некоторые вопросы, которые ещё предстоит решить…

Больше состояний для закрывающих инструкций

Для преобразования в иные форматы, нежели XHTML, может оказаться полезным добавление отождествления уровня для закрывающих инструкций списка, и т. д.

Почему бы просто не «преобразовать» в XML и затем применить к нему некоторые парсеры XSLT/XML?

Подрежимы для таблиц, списков, цитат

Анализатор с множественными режимами для предотвращения случаев вложенности состояний друг в друга.

Обсуждение

Спасибо за перевод!

¹⁾

Lexer относится к классу Doku_Lexer и содержится в файле inc/parser/lexer.php.

²⁾

Сканирование — чтение строки PHP от начала до конца.

³⁾

Термин «токен» в этом документе относится к совпадению регулярного выраждения, полученного лексическим анализатором, и соответствующему вызову метода обработчиком.

⁴⁾

Handler относится к классу Doku_Handler и содержится в файле inc/parser/handler.php.

⁵⁾

Последовательность инструкций содержится в массиве $calls, который является атрибутом обработчика. Предназначен для использования с call_user_func_array.

⁶⁾

Parser относится к классу Doku_Parser и содержится в файле inc/parser/parser.php.

⁷⁾

Renderer ( от «to render» в значении превращать, преобразовывать) относится к абстрактному (implemented) классу Doku_Renderer - см. inc/parser/renderer.php и inc/parser/xhtml.php.

⁸⁾

Прим. переводчика: возможно, речь идёт о т.н. незахватывающем поиске, подробнее см. литературу по регулярным выражениям, например, Джеффри Фридла «Регулярные выражения: библиотека программиста. Второе издание.» — СПб.: Питер, 2003, или документацию по PHP — ru.php.net/manual/en/ref.pcre.php.

⁹⁾

Термины «состояние» и «режим» используются отчасти как взаимозаменяемые, когда здесь говориться об анализаторе

¹⁰⁾

Смысл «плохо форматируемый» не применим к парсеру «Докувики» — он разработан так, чтобы предотвращать случаи, когда пользователь забывает добавить закрывающий тэг некоторой разметки, полностью игнорируя эту разметку.

plugin_development_link

anonymous@undisclosed.example.com (Anonymous) — Fri, 21 Feb 2025 03:53:27 +0000

Пример разработки плагина ссылки

Суть нашего плагина будет во вставке часто используемых шаблонов описания ссылок, например: Ссылка на оригинальную статью, См. также и Читать далее…. Статья затронет добавление кнопки нашего плагина на панель инструментов редактора (toolbar), описание процесса разработки и закончим переводом нашего плагина на другие языки.

Подготовка папок и файлов

В папке lib/plugins создадим папку нашего плагина (например link или mylink). Я использую название mylink, т.к. более простые могут быть заняты. В нашей папке создадим файлы:

plugin.info.txt
README.md
script.js

и папку:

images

Файл plugin.info.txt

Каждый плагин должен предоставить некоторую базовую информацию о себе. Это делается через файл с именем, plugin.info.txt расположенный в каталоге плагина .

Вот пример того, как должен выглядеть такой файл.

plugin.info.txt

base   mylink 
author VladPolskiy 
email  polskiyvn@gmail.com 
date   2025-01-09 
name   mylink syntax plugin 
desc   Inserts frequently used link descriptions into Dokuwiki. 
url    https://www.dokuwiki.org/plugin:mylink

Параметр	Описание
base	Техническое имя плагина. Менеджер расширений установит его в этот каталог.
author	Полное имя автора плагина
email	Электронная почта для связи с автором плагина по поводу этого плагина
date	Дата последнего обновления этого плагина в формате ГГГГ-ММ-ДД. Не забудьте обновить это, когда будете обновлять свой плагин! ⁸⁾
name	Удобочитаемое имя плагина
desc	Описание того, что делает плагин
url	URL-адрес , по которому можно получить более подробную информацию о плагине
minphp	Минимальная версия PHP, требуемая для этого плагина. Пусто для того же, что и DokuWiki. Только `Major.Minor` версия, например 8.2, не 8.2.3 может быть указана!
maxphp	Максимальная версия PHP, поддерживаемая этим плагином. Пусто для того же, что и DokuWiki. Только `Major.Minor` версия, например 8.2, не 8.2.3может быть указана!

Примечание: plugin.info.txt заменяет старый вызов getInfo() в ваших компонентах плагина для DokuWiki 2009-12-25 «Lemming» и более поздних версий. getInfo() теперь реализован в базовом классе и будет считывать всю информацию из этого файла. Его больше не нужно реализовывать в ваших подклассах.

Файл README.md

README.md служит первым документом для пользователей и разработчиков, которые хотят понять назначение, настройку и использование проекта.

README.md

# плагин моих ссылок
 
Это плагин для [dokuwiki](https://www.dokuwiki.org/start)..
 
См. [домашнюю страницу](https://www.dokuwiki.org/plugin:mylink) для получения подробной документации. Здесь мы приводим краткое описание требуемого синтаксиса:
 
```
{magnifier-lefticon}См. так-же [[:example|]]
{blue-document--arrowicon}[[http://example.com| Ссылка на оригинальную статью]]
```
 
- Квадратные скобки обозначают ссылку.

Файл script.js

JavaScript файл с рабочим кодом нашего плагина (подключения кнопки и вывод описания нашей ссылки в тело редактируемой страницы. Поскольку пользовательские и плагинные скрипты загружаться при всех запросах, а панель инструментов инициализируется только при редактировании, нам нужно сначала убедиться, что массив панелей инструментов существует. Проверим это, window.toolbar определен ли он. Если определен, вы можете добавить свою кнопку в конец массива.

script.js

/* JavaScript function to create mylink toolbar in Dokuwiki */
/* see http://www.dokuwiki.org/plugin:mylink for more info */
 
/* Путь к папке с иконками для кнопок панели */
mylink_icobase = "../../plugins/mylink/images/";
 
if(window.toolbar != undefined) {       
  toolbar[toolbar.length] = {           
    "type":"picker",                    
    "title":"My links",                 
    "icon":mylink_icobase+"toolbar_icon.png",  
    "list":[{ 
      "type":"format", 
      "title":"Link to the original article", 
      "icon":mylink_icobase+"blog.png",  
      "open":"[[",
	  "sample":"http://example.com|Link to the original article",
      "close":"]]"
    }, {
      "type":"format", 
      "title":"See also",   
      "icon":mylink_icobase+"magnifier-medium-left.png", 
      "open":"See also: [[",   
	  "sample":"http://example.com|",
	  "close":"]]"         
    }
	]
  };
}

«Подробности и пояснения»

script.js

/* JavaScript function to create mylink toolbar in Dokuwiki */
/* see http://www.dokuwiki.org/plugin:mylink for more info */
 
/* Путь к папке с иконками для кнопок панели */
mylink_icobase = "../../plugins/mylink/images/";
 
if(window.toolbar != undefined) {       // Проверка наличия массива панели инструментов
  toolbar[toolbar.length] = {           // Кнопка верхнего уровня панели инструментов
    "type":"picker",                    // тип действия кнопки: picker⇒ меню выбора
    "title":"My links",                 // название кнопки, отображаемое при наведении курсора
    "icon":mylink_icobase+"toolbar_icon.png",  //значок, используемый для кнопки
    "list":[{ //список выпадающего меню кнопок
      "type":"format", // 1я кнопка в выпадающем окне. тип действия кнопки: format⇒ вики-разметка
      "title":"Link to the original article", // название кнопки, отображаемое при наведении курсора
      "icon":mylink_icobase+"blog.png",  //путь к иконке, используемой для кнопки
      "open":"[[",
	  "sample":"http://example.com|Link to the original article",
      "close":"]]"
    }, {
      "type":"format", // 2я кнопка в выпадающем окне. тип действия кнопки: format⇒ вики-разметка
      "title":"See also",   // название кнопки, отображаемое при наведении курсора
      "icon":mylink_icobase+"magnifier-medium-left.png", //путь к иконке, используемой для кнопки
      "open":"See also: [[",   //открывающий тег вики-разметки для вставки
	  "sample":"http://example.com|",
	  "close":"]]"         //закрывающий тег вики-разметки для вставки
    }
	]
  };
}

в данном случае наш код
          "open":"See also: [[",   //открывающий тег вики-разметки для вставки
	  "sample":"http://example.com|",
	  "close":"]]"             //закрывающий тег вики-разметки для вставки
представляют собою разрезанный код для вывода:
See also: [[   http://example.com|    ]]

После редактирования и сохранения с нашим кодом файла script.js, переходим в редактор страниц и видим нашу новую кнопку на панели инструментовЖ При нажатии на кнопку проверяем открытие выпадающего списка кнопок и работу кода по выводу нашего текста: Проверяем вторую кнопку: Мы видим код, который мы разрезали на части в файле script.js

See also: [[http://example.com|]]

Пример вывода на странице нашего кода: Ниже вы видите, как это отображается на этой странице, что говорит о том, что наш код работаетю Link to the original article
See also: http://example.com
Регистрация в программе нашего плагина прошла автоматически,т.к. мы создавали наш проект в папке lib/plugins. При этом мы можем заорхивировать наш проект и установить через менеджер плагинов.
Просмотрим информацию о плагине в менеджере плагинов: Если мы удалим наш проект из lib/plugins и заархивируем нашу папку в формате .zip, то сможем произвести установку плагина через менеджер управления дополнениями:

Перевод плагина на разные языки

Заходим в папку нашего проекта и создадим внутри папку lang Внутри создадим папки с необходимыми нам языковыми пакетами (в нашем примере это папки: en - англиский и ru - русский)). В каждой из папок создадим файл перевода lang.php Примерное содержание файлов lang.php для русского и английского переводов:

lang.php

<?php
/**
 * English language file
 */
 
$lang['js']['mylink_picker']  = 'My links';
 
$lang['js']['tb_see_also']      = 'See also';
$lang['js']['tb_link_to_the_original']       = 'Link to the original article';

lang.php

<?php
/**
 * Russian language file
 */
 
$lang['js']['mylink_picker']  = 'Мои ссылки';
 
$lang['js']['tb_see_also']      = 'См. также';
$lang['js']['tb_link_to_the_original']       = 'Ссылка на оригинальную статью';

Атрибут	Значение
$lang['js']['mylink_picker'] = 'My links';	mylink_picker - имя вехней кнопки, My links - название (при наведении мыши) на английском и Мои ссылки - название на русском языке.
$lang['js']['tb_see_also'] = 'See also';	тоже самое для 1й кнопки в раскравающемся списке
$lang['js']['tb_link_to_the_original'] = 'Link to the original article';	тоже самое для 2й кнопки в раскравающемся списке

Вносим правки в наш файл script.js

script.js

/* JavaScript function to create mylink toolbar in Dokuwiki */
/* see http://www.dokuwiki.org/plugin:mylink for more info */
 
mylink_icobase = "../../plugins/mylink/images/";
 
if(window.toolbar != undefined) {
  toolbar[toolbar.length] = {
    "type":"picker",
    "title":LANG['plugins']['mylink']['mylink_picker'],
    "icon":mylink_icobase+"toolbar_icon.png",
    "list":[{
      "type":"format",
      "title":LANG['plugins']['mylink']['tb_link_to_the_original'],
      "icon":mylink_icobase+"blog.png",
      "open":"[[http://example.com|",
	  "sample":LANG['plugins']['mylink']['tb_link_to_the_original'],
      "close":"]]"
    }, 	{
      "type":"format",
      "title":LANG['plugins']['mylink']['tb_see_also'],
      "icon":mylink_icobase+"magnifier-medium-left.png",
      "open":LANG['plugins']['mylink']['tb_see_also'],
	  "sample":":[[http://example.com|",
	  "close":"]]"
    },
	]
  };
}

Переведем Dokuwiki в английский язык и проверим работу нашего плагина при английской локализации: И то же самое при установленном русском языке в настройках Dokuwiki Работа кода кнопки См. также и вывод в редакторе текста на русском языке Пример вывода на страницу Примеры работы нашего плагина и вывода наших ссылок на этой странице при английской и русской локализациях:

Примеры использования

Как мы уже знает, переменные

open - открывающий тег вики-разметки для вставки
sample- код php
close - закрывающий тег вики-разметки для вставки

Соответственно и вставлять мы можем любые шаблоны, например: Ссылка на оригинальную статью

index.php

Вставить код PHP

style.css

Вставить код CSS

script.js

Вставить код JS

Дополнения и Файлы

⁸⁾

Эта дата должна быть равна дате «Последнее обновление» на странице плагинов в репозитории. Это необходимо для автоматической маркировки обновлений, используемой Extension Manager, представленной в релизе Ponder Stibbons

plugin_file_structure

anonymous@undisclosed.example.com (Anonymous) — Mon, 26 Aug 2024 06:00:45 +0000

Структура файлов плагина

Существует две структуры для файлов класса плагина DokuWiki. Выбор структуры определяет имя класса(-ов) плагина.

<dokuwiki>/lib/plugins/<plugin name>/<plugin type>.php
Имя класса плагина будет <plugin type>_plugin_<plugin name>
```
т.е. файл                                       класс
     <dokuwiki>/lib/plugins/acl/admin.php   =>  admin_plugin_acl
```
<dokuwiki>/lib/plugins/<plugin name>/<plugin type>/<filename>.php
Эта структура допускает несколько классов одного типа в одном плагине, имена классов будут <plugin_type>_plugin_<plugin name>_<filename>,
```
т.е. файл                        тип                   класс
     <dokuwiki>/lib/plugins/code/syntax/code.php   =>  syntax_plugin_code_code
     <dokuwiki>/lib/plugins/code/syntax/file.php   =>  syntax_plugin_code_file
```

Заметьте, что _ (подчерк) это зарезервированный символ, и не может использоваться имени плагина <plugin name>.

Плагин может содержать как несколько типов плагинов, так и несколько классов плагинов каждого типа.

?Кроме того, плагин может (опционально) использовать другие встроенные ? In addition, a plugin can (optionally) take advantage of other built-in facilities to have its styles, JavaScript, localisation, and configuration included in DokuWiki.

Все пути и файлы – относительны к корневой директории плагина.

<dokuwiki>/lib/plugins/<pluginname>/
- style.css – стили CSS для плагина
- script.js – JavaScript используемые плагином
- lang/<language>/lang.php – Английские языковые строки (доступные через $this→getLang())
- lang/<language>/settings.php – локализованные строки, используемые в Менеджере конфигурации
- lang/<language>/<filename>.txt – локализованный текст включая разметку DokuWiki (доступен через $this→locale_xhml())
- conf/default.php – настройки по умолчанию (доступные через $this→getConf(), локальные настройки добавляются к глобальному файлу DokuWiki <dokuwiki>/conf/local.php)
- conf/metadata.php – Метаданные настроек описывающие настройки для использования в Менеджере конфигурации

Как включить более чем один файл JavaScript

DokuWiki поддерживает специальный синтаксис include, который можно использовать для включения в файл JavaScript других файлов.

Как включить более чем один файл CSS

Все CSS должны быть сведены в один файл.

Выключение плагина

Плагин может быть установлен, но выключен. Признаком того, что плагин выключен, служит файл нулевой длинны disabled в директории плагина.

Признаком того, что плагин выключен, служит суффикс .disabled добавленный к имени директории. Безопасный метод получить имя директории плагина – использовать функцию plugin_directory() inc/pluginutils.php.

plugin_info

anonymous@undisclosed.example.com (Anonymous) — Thu, 09 Jan 2025 20:21:07 +0000

Информация о плагине

Вот пример того, как должен выглядеть такой файл.

lib/plugins/example/plugin.info.txt

base   example
author My Full Name
email  me@example.com
date   2010-01-17
name   Example Plugin to do Stuff
desc   This is just an Example of how a plugin description looks like
url    https://www.dokuwiki.org/plugin:example

Параметр	Описание
base	Техническое имя плагина. Менеджер расширений установит его в этот каталог.
author	Полное имя автора плагина
email	Электронная почта для связи с автором плагина по поводу этого плагина
date	Дата последнего обновления этого плагина в формате ГГГГ-ММ-ДД. Не забудьте обновить это, когда будете обновлять свой плагин! ⁹⁾
name	Удобочитаемое имя плагина
desc	Описание того, что делает плагин
url	URL-адрес , по которому можно получить более подробную информацию о плагине
minphp	Минимальная версия PHP, требуемая для этого плагина. Пусто для того же, что и DokuWiki. Только `Major.Minor` версия, например 8.2, не 8.2.3 может быть указана!
maxphp	Максимальная версия PHP, поддерживаемая этим плагином. Пусто для того же, что и DokuWiki. Только `Major.Minor` версия, например 8.2, не 8.2.3может быть указана!

⁹⁾

plugin_programming_tips

anonymous@undisclosed.example.com (Anonymous) — Thu, 09 Jan 2025 09:54:08 +0000

https://www.dokuwiki.org/devel:plugin_programming_tips

plugins

anonymous@undisclosed.example.com (Anonymous) — Thu, 09 Jan 2025 11:11:42 +0000

Разработка плагинов

Написать плагин DokuWiki очень просто. Перед тем, как написать свой собственный, не забудьте поискать похожие плагины среди уже написанных and read through рекомендации по безопасности для авторов плагинов .

DokuWiki имеет гибкий API-интерфейс плагина, который позволяет разработчикам расширять его функциональность, будь то дополнительные режимы синтаксиса , пользовательские режимы действий или новые форматы экспорта и многое другое. В зависимости от назначения плагина, он может состоять из одного или нескольких компонентов следующих типов плагинов.

Типы плагинов

На данный момент DokuWiki предлагает семь различных типов плагинов.

Плагины синтаксиса расширяют базовый синтаксис DokuWiki.
Плагины действий можно использовать для расширения или замены многих аспектов основных операций DokuWiki: от сохранения вики-страниц до добавления новых режимов действий.
Плагины администратора могут обеспечить функциональные возможности администрирования DokuWiki — эти плагины доступны суперпользователям и менеджерам с помощью кнопки «Администратор».
Вспомогательные плагины можно использовать для предоставления функциональности многим другим плагинам, поэтому каждому плагину не придется снова и снова реализовывать определенную функцию.
renderer_plugins позволяют создавать новые режимы экспорта и заменять стандартный рендерер DokuWiki XHTML.
Удаленные плагины позволяют добавлять веб-сервисы в ваш плагин.
Плагины аутентификаци и добавляют в DokuWiki дополнительный бэкэнд аутентификации, который можно активировать через менеджер конфигурации.
Плагины CLI добавляют инструменты командной строки в ваш плагин

Plugin types are not mutually exclusive, i.e. a plugin can also be assigned to several plugin types.

Типы плагинов не являются взаимоисключающими, т.е. плагин может быть отнесен к нескольким типам плагинов. плагин цвета, может состоять только из одного файла syntax.php. Более продвинутые плагины состоят из нескольких компонентов, например, плагин структурированных данных имеет обработку синтаксиса, разделенную на компоненты «ввод данных» и «табличное представление», компонент действия для специальной кнопки редактирования, прикрепленной к каждой записи данных, и интерфейс администратора для обслуживания базы данных.

Sources

There are a number of sources especially for plugin development:

The plugin file structure gives overview of the naming convention and structure, and where you add JavaScript and CSS stylesheets, relevant for all plugin types
There are some common plugin functions, available in all plugins types. Adds localisation, configuration and interspection.
These security guidelines give some deeper understanding of common issues and presents some protection measures.
Some general plugin programming tips are available, mostly good practices and pointers to handsome tools in DokuWiki.

Plugin Name

A valid plugin name:

Should only contain the characters a-z and 0-9.
Underscore is NOT allowed as:
- This is used to separate <plugin name> from <component name>.
- Using underscore will also give a popularity rating of zero.
If the same name is used by two different plugins
- they are mutually excluding and inherently incompatible,
- furthermore only one of them can have a plugin homepage on dokuwiki.org.

Plugin Wizard

A Wizard to create the basic skeleton for a DokuWiki plugin can be found at http://pluginwizard.dokuwiki.org/ and is recommended to be used for starting the development. Alternatively use the command line dev Plugin.

If you later need to extend your plugin refer to the plugin file structure on how files are arranged in a plugin.

Publishing a Plugin on dokuwiki.org

If you created a plugin, please share it with the community. Just create a page named after your plugin in the plugin namespace. E.g. if your pluginfolder is named sample create a page plugin:sample here in the wiki.

The page should contain all needed documentation on how to install and use the plugin and give users a pretty good idea what it does before installing the plugin. Adding screenshots might be a good idea as well. When creating the new page, a namespace template will prefill sections and tips for you.

At the top of the plugin page a few metadata fields have to be filled. A description of each field can be found on Repository Plugin page.

Users will see that an update is available in the extension manager. For this to work properly it is necessary that the date “Last updated on” at the Plugin wiki page equals the date in the file plugin.info.txt in the source tarball/zipfile. If this is not the case, available updates will not be shown or the “Update” signal will persist despite the plugin being up-to-date!

Uploads are not allowed on dokuwiki.org, so you need to host your plugin 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 GitHub, GitLab or Bitbucket which offers also a bug tracker for your repository.

Plugin developers can check the bad extension page for differences in their github repository checkin, the plugin.info.txt and the respective page at dokuwiki.org.

Inspirations

Existing Plugins

Already more than 1400 plugins are written for DokuWiki. To learn how things are working, you might study some existing plugins that have some similarity with your ideas. At codesearch.dokuwiki.org you can find all them in a browsable format.

Event List

Another way is to search the event list for a suitable event that may be used to implement the desired plugin function. The plugins that use this event can then be found using the code search mentioned above.

At the bottom of each event page, where the details of the event are listed, there is a link to a pre-filled code search. It provides specific examples of the function and application of the respective event.

Дополнения и Файлы

см. также

preload

anonymous@undisclosed.example.com (Anonymous) — Fri, 03 Jan 2025 12:35:12 +0000

Предварительная загрузка

inc/preload.php не является частью стандартной установки dokuwiki
inc/init.php пытается включить inc/preload.php прежде, чем он сделает что-либо еще
preload.php имеет возможность переопределять многие аспекты стандартной dokuwiki, в т.ч.
- большинство местоположений каталога
- каскад конфигурации
- контроллер плагина

Это представляет особый интерес для вики-ферм, позволяя им управлять несколькими независимыми вики из одной установки dokuwiki.

Смотрите также

Константы DOKU_*

Примеры

Локальная папка конфигурации

preload.php

<?php
/**
 *  Sample preload.php to use a separate folder for all local configuration settings
 * 
 *  By default this script will locate the local config files in
 *      /path/to/doku/conf/local/
 * 
 *  The locations of both the default dokuwiki configuration and local configuration
 *  can be controlled using DOKU_DEFAULT & DOKU_CONF.
 * 
 *  NOTE: DOKU_CONF controls the location of several other files not contained in the
 *  configuration cascade.  They are:
 *    acl.auth.php
 *    users.auth.php
 *    userscript.php
 *    userstyle.css (and media specific user stylesheets, e.g. userscreen.css, userprint.css)
 *    report_e_all
 *    msg
 *
 */
 
if(!defined('DOKU_DEFAULT')) define('DOKU_DEFAULT',DOKU_INC.'conf/');
if(!defined('DOKU_CONF')) define('DOKU_CONF',DOKU_DEFAULT.'local/');
 
global $config_cascade;
$config_cascade = array(
  'main' => array(
    'default'   => array(DOKU_DEFAULT.'dokuwiki.php'),
    'local'     => array(DOKU_CONF.'dokuwiki.php'),
    'protected' => array(DOKU_CONF.'protected.php'),
  ),
  'acronyms'  => array(
    'default'   => array(DOKU_DEFAULT.'acronyms.conf'),
    'local'     => array(DOKU_CONF.'acronyms.conf'),
  ),
  'entities'  => array(
    'default'   => array(DOKU_DEFAULT.'entities.conf'),
    'local'     => array(DOKU_CONF.'entities.conf'),
  ),
  'interwiki' => array(
    'default'   => array(DOKU_DEFAULT.'interwiki.conf'),
    'local'     => array(DOKU_CONF.'interwiki.conf'),
  ),
  'license' => array(
    'default'   => array(DOKU_DEFAULT.'license.php'),
    'local'     => array(DOKU_CONF.'license.php'),
  ),
  'mediameta' => array(
    'default'   => array(DOKU_DEFAULT.'mediameta.php'),
    'local'     => array(DOKU_CONF.'mediameta.php'),
  ),
  'mime'      => array(
    'default'   => array(DOKU_DEFAULT.'mime.conf'),
    'local'     => array(DOKU_CONF.'mime.conf'),
  ),
  'scheme'    => array(
    'default'   => array(DOKU_DEFAULT.'scheme.conf'),
    'local'     => array(DOKU_CONF.'scheme.conf'),
  ),
  'smileys'   => array(
    'default'   => array(DOKU_DEFAULT.'smileys.conf'),
    'local'     => array(DOKU_CONF.'smileys.conf'),
  ),
  'wordblock' => array(
    'default'   => array(DOKU_DEFAULT.'wordblock.conf'),
    'local'     => array(DOKU_CONF.'wordblock.conf'),
  ),
  'acl'       => array(
    'default'   => DOKU_CONF.'acl.auth.php',
  ),
  'plainauth.users' => array(
    'default'   => DOKU_CONF.'users.auth.php',
  ),
  'plugins' => array(
    'local'     => array(DOKU_CONF.'plugins.local.php'),
    'protected' => array(
      DOKU_CONF.'plugins.required.php',
      DOKU_CONF.'plugins.protected.php',
    ),
  ),
  'userstyle' => array(
    'default' => DOKU_CONF.'userstyle.css',
    'print'   => DOKU_CONF.'printstyle.css',
    'feed'    => DOKU_CONF.'feedstyle.css',
    'all'     => DOKU_CONF.'allstyle.css',
  ),
  'userscript' => array(
    'default' => DOKU_CONF.'userscript.js'
  ),
);

request_vars

anonymous@undisclosed.example.com (Anonymous) — Fri, 03 Jan 2025 15:21:59 +0000

Доступ к переменным запроса

DokuWiki не запрещает доступ к $_POST, $_GET, $_REQUEST и $_SERVER. Однако мы настоятельно рекомендуем обращаться к ним не напрямую, а использовать наш Input класс. Глобальный экземпляр этого класса доступен везде как $INPUT.

Класс предоставляет вам типобезопасный доступ к переменным запроса, обеспечивает их правильную инициализацию и позволяет вам устанавливать значения по умолчанию.

Чтобы получить доступ к переменной в $_REQUEST, просто вызовите соответствующий метод в $INPUT. Например, для доступа к Integer в $_REQUEST['foo'], просто вызовите $INPUT->int('foo').

Если вы хотите получить доступ к $_GET или $_POST явно, вызовите методы для членов get и post $INPUT. Например $INPUT->get->int('foo') или $INPUT->post->int('foo').

Доступ к $_SERVER переменным всегда осуществляется через server член $INPUT: Например. $INPUT->server->str('REMOTE_USER').

Все функции доступа позволяют второму параметру задать значение по умолчанию. Это значение будет возвращено, если переменная не была установлена или имела неправильный тип (например, ожидаемое целое число было массивом). Все функции доступа имеют разумные значения по умолчанию, соответствующие типу функции. Например int() returns 0, arr() возвращает пустой массив по умолчанию.

Третий параметр сообщает функции, следует ли возвращать параметр empty() по умолчанию. Этот третий параметр по умолчанию равенfalse.

Примеры

Вот несколько примеров, чтобы дать вам представление о том, как работает класс Input. Для получения подробной информации, пожалуйста, обратитесь к inc/input/input.php.

global $INPUT;
 
$_REQUEST = ['foo' => '3'];
 
var_dump($INPUT->int('foo')); // expect an integer
// int(3)
 
var_dump($INPUT->str('foo')); // expect a string
// string(1) "3"
 
var_dump($INPUT->int('bar')); // standard default
// int(0)
 
var_dump($INPUT->int('bar',42)); // setting an explicit default
// int(42)
 
var_dump($INPUT->bool('foo')); // we cast when reasonable
// bool(true)
 
var_dump($INPUT->arr('foo')); // we don't cast here
// array(0) {
// }
 
var_dump($INPUT->has('foo')); // is set
// bool(true)
 
 
$_POST = ['foo' => '0', 'bar' => ''];
 
// now accessing $_POST and trying the third parameter 
 
var_dump($INPUT->post->int('foo', -1));
// int(0)
 
var_dump($INPUT->post->int('bar', -1));
// int(-1)
 
var_dump($INPUT->post->int('foo', -1, true));
// int(-1)
 
var_dump($INPUT->post->int('bar', -1, true));
// int(-1)
 
 
$_SERVER 
 
var_dump($INPUT->server->str('REMOTE_USER'));
// string(8) "username"

security

anonymous@undisclosed.example.com (Anonymous) — Fri, 03 Jan 2025 14:48:19 +0000

Правила безопасности для авторов плагинов

Создание плагинов для DokuWiki очень просто даже для начинающих программистов PHP. Чтобы убедиться, что ваш плагин не ставит под угрозу безопасность всей вики, на которой он установлен, вам следует следовать рекомендациям, изложенным на этой странице.

Улучшение этой страницы всегда приветствуется. Она находится в очень сыром состоянии и должна быть расширена более подробной информацией, ссылками и примерами.

Краткое содержание

Список наиболее распространенных проблем безопасности и способы их избежания можно найти на этой странице. Краткое резюме:

Межсайтовый скриптинг (XSS) — вставляет вредоносный код на веб-сайт для манипулирования сайтом в браузере пользователя.
Подделка межсайтовых запросов (CSRF) — уловки, позволяющие вам совершать неосознанные вредоносные действия на вашем сайте.
Удаленное включение кода – включает код на сервере, который там выполняется.
Утечка информации – отображается слишком много информации
SQL-инъекция – можно выполнить нежелательные запросы к вашим данным

Также добавлено примечание о необходимости сообщать о проблемах безопасности .

Межсайтовый скриптинг (XSS)

Это, вероятно, самая распространенная уязвимость, встречающаяся в плагинах DokuWiki.

Cross Site Scripting относится к атаке, при которой вредоносный код JavaScript внедряется на веб-сайт. Это может использоваться для перенаправления невинных пользователей на вредоносные веб-сайты или для кражи аутентификационных cookie-файлов.

Механизм плагинов DokuWiki дает разработчикам плагинов большую гибкость. В случае с плагинами синтаксиса, в частности, фреймворк дает плагинам возможность работать с сырым необработанным выводом. Это означает, что данные страницы вики, которые достигают вашего плагина, вообще не были обработаны. И не будет никакой дальнейшей обработки вывода после того, как он покинет ваш плагин.

Выход из режима экранирования

Как минимум, плагин должен гарантировать, что все выходные необработанные данные будут содержать все специальные символы HTML , преобразованные в сущности HTML с помощью функции htmlspecialchars(). DokuWiki предоставляет удобный ярлык hsc() для этой функции. Значения URL-адресов следует экранировать с помощью rawurlencode().

Кроме того, следует с подозрением относиться к любым данным вики, извлеченным и используемым внутри компании (например, именам пользователей).

Проверка входных данных

Всегда проверяйте все ваши входные данные. Используйте белые списки, фильтры, преобразования в точный тип данных, который вы имеете в виду, например, из числа, введенного как смешанное значение php, в целое число и т. д., чтобы убедиться, что у вас есть только разрешенные вами данные.

Также ознакомьтесь с нашей главой об обработке переменных запросов, таких как _GET, _POST или _SERVER.

Смотрите также:

Типичные примеры уязвимостей

Ниже показаны некоторые очень распространенные проблемы. Примеры очень просты, чтобы сделать общую проблему понятной. Ваш плагин, вероятно, сложнее, но вам нужно отслеживать те же уязвимости.

Синтаксис Тела

Многие простые плагины синтаксиса принимают часть введенных пользователем данных и форматируют их в виде пользовательского HTML .

Пример: Вот плагин сокращенного синтаксиса, позволяющий выделить заданный ввод жирным шрифтом.

class syntax_plugin_bold extends DokuWiki_Syntax_Plugin {
    // общие функции плагина опущены
 
    public function connectTo($mode) {
        $this->Lexer->addSpecialPattern('!!!.*?!!!', $mode, 'plugin_bold');
    }
 
    public function handle($match, $state, $pos, Doku_Handler $handler){
        return [substring($match, 3, -3)];
    }
 
    public function render($format, Doku_Renderer $renderer, $data) {
        if($format != 'xhtml') return false;
        $renderer->doc .= '<b>' . $data[0] . '</b>';  // без экранирования
    }
}

Как вы можете видеть, необработанные входные данные, захваченные в шаблоне лексера, просто передаются в метод рендеринга, где экранирование вообще не выполняется. Злонамеренные пользователи могут вводить любой код JavaScript и HTML , который они хотят.

Решение простое: правильный побег.

class syntax_plugin_bold extends DokuWiki_Syntax_Plugin {
    // общие функции плагина опущены
 
    public function connectTo($mode) {
        $this->Lexer->addSpecialPattern('!!!.*?!!!', $mode, 'plugin_bold');
    }
 
    public function handle($match, $state, $pos, Doku_Handler $handler){
        return [substring($match, 3, -3)];
    }
 
    public function render($format, Doku_Renderer $renderer, $data) {
        if($format != 'xhtml') return false;
        $renderer->doc .= '<b>' . htmlspecialchars($data[0]) . '</b>'; //экранирование 
    }
}

Формы

Когда ваш плагин предоставляет форму, очень часто требуется проверить вводимые данные и повторно отобразить форму с полученными данными пользователя в случае возникновения ошибки проверки.

Пример: ниже показана форма, уязвимая для атаки XSS, поскольку она не экранирует правильно введенные пользователем данные:

<form action="" method="post">
    <input type="text" name="q" value="<?php echo $_REQUEST['q']?>" /> 
    <input type="submit" />                     //без экранирования
</form>

Предоставление данных "><script>alert('bang')</script> в качестве входных данных пользователя приведет к эксплуатации уязвимости.

Для исправления формы используйте функцию htmlspecialchars() или функцию DokuWiki shortcut hsc():

<form action="" method="post">
    <input type="text" name="q" value="<?php echo hsc($_REQUEST['q'])?>" />
    <input type="submit" />                                      //экранирование
</form>

В целом рекомендуется не создавать формы вручную, а использовать библиотеку форм DokuWiki .

Классы и другие атрибуты

Часто плагины принимают несколько параметров и опций, которые используются для изменения выходных данных плагина.

Представьте себе плагин, принимающий следующие входные данные для отображения окна сообщения:

<msg warning>Do not believe anything!</msg>

В методе рендеринга этого синтаксиса может быть такой код:

$renderer->doc .= '<div class="msg_' . $class . '">'  //$class может быть чем угодно 
                       . htmlspecialchars($message)
                . '</div>';

Как вы видите, само сообщение правильно экранировано, но класс — нет. Вместо экранирования может быть разумнее использовать белый список разрешенных классов с резервным вариантом по умолчанию::

$allowed = ['notice', 'info', 'warning', 'error'];   // белый список 
if(!in_array($class, $allowed){                         
    $class = 'notice'; // неизвестный ввод, вернуться к разумному значению по умолчанию
}
$renderer->doc .= '<div class="msg_' . $class . '">'
                       . htmlspecialchars($message)
                . '</div>';

входные URL-адреса

Когда плагин принимает URL-адреса в качестве входных данных, необходимо убедиться, что пользователи не смогут передать javascript:// псевдо-протокол.

Вот пример того, как может выглядеть очень простая проверка, позволяющая убедиться, что используются только URL-адреса http и https.

// пустой URL при несоответствии протокола 
if(!preg_match('/^https?:\/\//i', $url)) {
    $url = '';
}

Подделка межсайтовых запросов (CSRF)

Эта уязвимость часто появляется в плагинах из-за отсутствия понимания этой проблемы, ее часто путают с XSS.

Подделка межсайтовых запросов относится к атаке, при которой вредоносный сайт обманывает браузер жертвы, запрашивая страницу на уязвимом сайте для выполнения нежелательного действия. Атака предполагает, что браузер жертвы имеет учетные данные для изменения чего-либо на уязвимом сайте.

Добавление токена безопасности

DokuWiki предлагает функции, которые помогут вам бороться с атаками CSRF. getSecurityToken() создаст токен, который следует использовать для защиты любого аутентифицированного действия. Он должен быть включен в ссылки или формы, запускающие это действие. Все формы, созданные с помощью библиотеки форм будут иметь автоматически добавленные токены безопасности, для форм, созданных вручную, можно использовать функцию formSecurityToken().

Вы как автор плагина несете ответственность за фактическую проверку токена перед выполнением авторизованных действий с использованием функции checkSecurityToken().

Типичный пример уязвимости

Ниже приведен простейший пример для начала. У вас может быть более сложный плагин для защиты, вот простой пример на основе формы.

Представьте, что вы хотите узнать что-то, на что можно ответить «Да» или «Нет», у вас получится форма такого типа:

<form action="" method="GET">
    <input type="radio" name="yn" value="Yes" />
    <input type="radio" name="yn" value="No" />
    <input type="submit" value="Answer" />
</form>

Затем вы обрабатываете эту форму следующим образом:

global $INPUT;
 
if($INPUT->get->has('yn')){
    do_something_with_yn($INPUT->get->str('yn'));
}

Итак, пользователь подключен, чтобы ответить на этот вопрос, но он пока не знает ответа. Давайте уделим время размышлениям и просмотрим веб-страницы… Теперь пользователь посещает вредоносный веб-сайт, который знает или нет, что пользователь может быть подключен к вашему DokuWiki. На этом веб-сайте разработчик включил этот HTML- тег изображения:

<img src="http://your.dokuwi.ki/formpage?yn=Yes" />

Что тогда будет делать браузер пользователя?

Браузер обработает это изображение как любое другое и отправит запрос на этот URL . Ваш плагин увидит, что $_GET['yn'] установлено, и вызовет do_something_with_yn() функцию.

Это один из примеров CSRF. Теперь, как исправить эту дыру в безопасности?

Предотвращение CSRF-атак

Помните вашу форму выше? Давайте добавим в нее ввод:

<form action="" method="GET">
    <input type="hidden" name="sectok" value="<?php getSecurityToken(); ?>" />
    <input type="radio" name="yn" value="Yes" />
    <input type="radio" name="yn" value="No" />
    <input type="submit" value="Answer" />
</form>

Видите первый ввод? Да? Хорошо. Теперь вам нужно проверить токен безопасности при получении формы, перед ее обработкой:

global $INPUT;
 
if($INPUT->get->has('yn') && checkSecurityToken()) {
    do_something_with_yn($INPUT->get->str('yn'));
}

Поскольку вредоносный веб-сайт никогда не найдет значение скрытого ввода «sectok», ваша форма больше не уязвима для CSRF.

Примечание: Если токен безопасности недействителен, checkSecurityToken() функция отображает сообщение, информирующее пользователя.

Удаленное включение кода

Эта атака позволяет злоумышленнику внедрить код (PHP) в ваше приложение. Это может произойти при включении файлов или использовании небезопасных функций операций, таких как eval() или system().

Всегда фильтруйте любые входные данные, которые будут использоваться для загрузки файлов или которые передаются в качестве аргумента внешним командам.

Утечка информации

Эта атака может привести к раскрытию файлов, которые обычно должны быть защищены ACL DokuWiki , или может раскрыть файлы на сервере (например, /etc/passwd).

Всегда фильтруйте любые входные данные, которые будут использоваться для загрузки файлов или которые передаются в качестве аргумента внешним командам.

Всегда используйте функции проверки ACL DokuWiki при доступе к данным страницы.

SQL-инъекция

Эта атака редко актуальна в DokuWiki, поскольку база данных не используется. Однако, если ваш плагин обращается к базе данных, всегда экранируйте все значения перед их использованием в операторах SQL.

Дополнительная информация:

SQL-инъекция

Сообщение о проблемах безопасности

Если у вас возникли проблемы с плагином, сообщите об этом автору плагина по электронной почте, при желании указав Andi or the список рассылки on CC.

Дополнительно к данным на странице плагина securityissue следует добавить поле с кратким описанием проблемы . Это создаст красное предупреждающее поле и исключит плагин из основного списка плагинов.

После устранения проблемы и выпуска новой версии это поле следует снова удалить.

smileys.conf

anonymous@undisclosed.example.com (Anonymous) — Tue, 14 Jan 2025 09:45:51 +0000

smileys.conf

Используется для замены текстовых макросов графическим представлением. Также может использоваться для размещения других изображений smileys внутри текстового потока.

Текст заменяется, если он найден в исходном коде вики-страницы, другой синтаксис не требуется.

# Настроенные здесь смайлики будут заменены на
# настроенные изображения в каталоге смайликов

8-)         icon_cool.gif
8-O         icon_eek.gif
8-o         icon_eek.gif
:-(         icon_sad.gif
:-)         icon_smile.gif
=)          icon_smile2.gif
:-/         icon_doubt.gif
:-\         icon_doubt2.gif
:-?         icon_confused.gif
:-D         icon_biggrin.gif
:-P         icon_razz.gif
:-o         icon_surprised.gif
:-O         icon_surprised.gif
:-x         icon_silenced.gif
:-X         icon_silenced.gif
:-|         icon_neutral.gif
;-)         icon_wink.gif
m(          facepalm.gif
^_^         icon_fun.gif
:?:         icon_question.gif
:!:         icon_exclaim.gif
LOL         icon_lol.gif
FIXME       fixme.gif
DELETEME    delete.gif

Или находится в репозитории git: conf/smileys.conf

Администраторы Вики должны разместить свои смайлики conf/smileys.local.conf, см. также Настройка смайликов.

style.ini

anonymous@undisclosed.example.com (Anonymous) — Mon, 28 Aug 2023 10:54:45 +0000

Шаблон style.ini

The style.ini is an ini file in each template's directory¹⁰⁾ configuring the generation of CSS styles. It has two sections: [stylesheets] and [replacements] described below.

[stylesheets]

This part defines which CSS files are loaded. Each line is defined as follow:

cssfile.css = mode

cssfile.css is your file name and mode is one of the supported output modes as described at mode.

The stylesheet can also be a .less file. (See LESS).

[replacements]

DokuWiki's CSS dispatcher is able to replace placeholders in the loaded stylesheets which are configured through the [replacements] section in the templates style.ini. This is especially useful for defining a color scheme once and reuse these colors in all files.

These replacements can also be used as LESS variables.

The Styling Plugin let users preview and change the appearance of any template based on the defined replacements. See the Styling Plugin for details.

Guaranteed color placeholders

The following placeholders are the only ones that are safe to be used by plugins. All templates have to implement these at least, but are free to add more.

placeholder variable	meaning
`__background__`	main background color
`__background_alt__`	alternative background color (also used for the theme color in the manifest)
`__background_neu__`	neutral background color
`__border__`	border color
`__text__`	main text color
`__text_alt__`	alternative text color
`__text_neu__`	neutral text color
`__highlight__`	highlighted text color (new since Adora Belle)
`__link__`	the general link color (new since Greebo)

Template authors should generally try to reuse the placeholder names of the default template.

Example

See for example the style.ini of the Starter template for an overview of the file. If your are a wiki admin who like to modify the style, please use a local style.ini.

Local style.ini

Loal changes can be stored in a local style.ini at the location conf/tpl/<tpl>/style.ini. (Where <tpl> needs to be substituted with the name of the template folder. Just create it if it doesn't exist.)

This prevents losing those changes after an upgrade. The file still needs to include each section (i.e. [stylesheets] or [replacements]) and paths are relative to the added ini file.

If you use the Styling Plugin you can preview and change the replacement values via the admin interface, before it is stored in this file.

Example:

conf/tpl/dokuwiki/style.ini

[stylesheets]
extra.css  = all
 
[replacements]
__text__        = "#000"
__site_width__  = "100%"

¹⁰⁾

if the template supports it

syntax_plugin_skeleton

anonymous@undisclosed.example.com (Anonymous) — Thu, 09 Jan 2025 10:05:26 +0000

Скелет синтаксического плагина

syntax.php

<?php
/**
 * Плагин Skeleton: отображает «Hello World!»
 *
 * Синтаксис: <TEST> — будет заменен на «Hello World!»
 *
 * @license GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @автор Кристофер Смит <chris@jalakai.co.uk>
 */
 
 
/**
 * Все плагины DokuWiki для расширения механизма парсера/рендеринга
 * необходимо унаследовать от этого класса
 */ 
class syntax_plugin_test extends DokuWiki_Syntax_Plugin {
 
 
 
   /**
    * Получите тип синтаксиса, который определяет этот плагин.
    *
    * @параметр нет
    * @return String <tt>'substition'</tt> (т. е. 'подстановка').
    * @общественность
    * @статичный
    */ 
    function getType(){
        return 'substition';
    }
 
    /**
     * Какой синтаксис мы допускаем (необязательно)
     */ 
//    function getAllowedTypes() {
//        return array();
//    }
 
   /**
    * Определите, как этот плагин обрабатывается в отношении абзацев.
    *
    * <р>
    * Этот метод важен для правильного вложения XHTML. Он возвращает
    * одно из следующих значений:
    * </р>
    * <дл>
    * <dt>normal</dt><dd>Плагин можно использовать внутри абзацев.</dd>
    * <dt>блок</dt><dd>Открытые абзацы необходимо закрыть перед
    * вывод плагина.</dd>
    * <dt>стек</dt><dd>Особый случай: плагин оборачивает другие абзацы.</dd>
    * </dl>
    * @параметр нет
    * @return String <tt>'блок'</tt>.
    * @общественность
    * @статичный
    */ 
//    function getPType(){
//        return 'normal';
//    }
 
   /** 
    * Где сортировать? 
    * 
    * @param none 
    * @return Integer <tt>6</tt>. 
    * @public 
    * @static 
    */ 
    function getSort(){
        return 999;
    }
 
 
   /** 
    * Подключить шаблон поиска к лексеру. 
    * 
    * @param $aMode String Требуемый режим визуализации.
    * @return none 
    * @public 
    * @see render() 
    */ 
    function connectTo($mode) {
      $this->Lexer->addSpecialPattern('<TEST>',$mode,'plugin_test');
//      $this->Lexer->addEntryPattern('<TEST>',$mode,'plugin_test');
    }
 
//    function postConnect() {
//      $this->Lexer->addExitPattern('</TEST>','plugin_test');
//    }
 
 
   /** 
    * Обработчик для подготовки сопоставленных данных для процесса рендеринга. 
    * 
    * <p> 
    * Параметр <tt>$aState</tt> задает тип шаблона 
    , * который вызвал вызов этого метода: 
    * </p> 
    * <dl> 
    * <dt>DOKU_LEXER_ENTER</dt> 
    * <dd>шаблон , установленный функцией <tt>addEntryPattern()</tt></dd> * 
    <dt>DOKU_LEXER_MATCHED </dt> * <dd> 
    шаблон, установленный функцией <tt>addPattern()</tt></dd> 
    * <dt>DOKU_LEXER_EXIT </dt> 
    * <dd>шаблон, установленный функцией <tt>addExitPattern()</tt> </dd> 
    * <dt>DOKU_LEXER_SPECIAL</dt> 
    * <dd>шаблон, установленный функцией <tt>addSpecialPattern()</tt></dd> 
    * <dt>DOKU_LEXER_UNMATCHED</dt> 
    * <dd>обычный текст, встречающийся в режим синтаксиса плагина 
    , * который не соответствует ни одному шаблону.</dd> 
    * </dl> 
    * @param $aMatch String Текст, соответствующий шаблонам. 
    * @param $aState Integer Состояние лексера для сопоставления. 
    * @param $aPos Integer Позиция символа сопоставленного текста. 
    * @param $aHandler Object Ссылка на объект Doku_Handler. 
    * @return Integer Текущее состояние лексера для сопоставления. 
    * @public 
    * @see render() 
    * @static 
    */ 
    function handle($match, $state, $pos, Doku_Handler $handler){
        switch ($state) {
          case DOKU_LEXER_ENTER : 
            break;
          case DOKU_LEXER_MATCHED :
            break;
          case DOKU_LEXER_UNMATCHED :
            break;
          case DOKU_LEXER_EXIT :
            break;
          case DOKU_LEXER_SPECIAL :
            break;
        }
        return array();
    }
 
   /** 
    * Обработка фактического создания выходных данных. 
    * 
    * <p> 
    * Метод проверяет заданный <tt>$aFormat</tt> и возвращает
    * <tt>FALSE</tt>, если формат не поддерживается. <tt>$aRenderer</tt> 
    * содержит ссылку на объект рендерера, который в данный момент 
    * обрабатывает рендеринг. Содержимое <tt>$aData</tt> является 
    * возвращаемым значением метода <tt>handle()</tt>. 
    * </p> 
    * @param $aFormat String Формат выходных данных для генерации. 
    * @param $aRenderer Object Ссылка на объект рендерера. 
    * @param $aData Array Данные, созданные методом <tt>handle()</tt> 
    *. 
    * @return Boolean <tt>TRUE</tt> при успешном рендеринге или 
    * <tt>FALSE</tt> в противном случае. 
    * @public 
    * @see handle() 
    */ 
    function render($mode, Doku_Renderer $renderer, $data) {
        if($mode == 'xhtml'){
            $renderer->doc .= "Hello World!";            // ptype = 'normal'
//            $renderer->doc .= "<p>Hello World!</p>";     // ptype = 'block'
            return true;
        }
        return false;
    }
}

Примечание:

Имя этого плагина — test. Это видно по имени класса: syntax_plugin_test — все, что следует далее, syntax_plugin_ воспринимается как имя плагина.

Поскольку имя плагина — test, его нужно сохранить в lib/plugins/test чтобы DokuWiki автоматически распознал его. Его нужно сохранить как syntax.php

Дополнения и Файлы

см. также

syntax_plugins

anonymous@undisclosed.example.com (Anonymous) — Thu, 09 Jan 2025 19:44:11 +0000

Синтаксические плагины

Синтаксические плагины — это плагины расширения синтаксиса «ДокуВики». Чтобы понять, что необходимо для регистрации нового синтаксиса в «ДокуВики», вы должны прочитать, как работает парсер.

Краткий обзор

Для синтаксического плагина example требуется объявить имя класса как syntax_plugin_<example>, который расширяет класс DokuWiki_Syntax_Plugin, определённый в файле lib/plugins/syntax.php. Класс необходимо сохранить в файле с названием lib/plugins/example/syntax.php. Для более подробной информации можно обратиться к статье о структуре файлов плагина.

Класс должен содержать как минимум следующие функции:

~~getInfo() — возвращает хэш с информацией о плагине: автор, электропочта, дата, название, описание, ссылки.~~
Теперь вместо неё прилагается отдельный файл plugin.info.txt
getType() — должен возвращать тип синтаксиса (см. ниже).
getSort() — возвращает число, по которому определяется, в каком порядке должны добавляться состояния, см. также parser, order of adding modes и getSort list.
connectTo($mode) — эта функция наследуется от класса Doku_Parser_Mode, определённого в inc/parser/parser.php. Это место, где регистрируется регулярные выражения, необходимые для опознания вашего синтаксиса.
handle($match, $state, $pos, Doku_Handler $handler) — функция для подготовки совпавшего синтаксиса для использования рендером.
render($mode, Doku_Renderer $renderer, $data) — функция для отображения контента.

Следующие дополнительные методы могут быть переопределены при необходимости:

getPType() — определяет, как данный синтаксис размещается относительно параграфов¹⁾. Возвращает:
- normal — (значение по умолчанию, используется, если метод не переопределяется) Плагин может использоваться внутри параграфов,
- block — Открытые параграфы должны быть закрыты до вывода плагина или
- stack — Специальный случай. Плагин обёртывает другие параграфы
getAllowedTypes() (значение по умолчанию: array()) Должен вернуть массив типов состояний, которые могут быть включены в собственную разметку плагина.
accepts($mode) — Эта функция говорит парсеру, допускает ли плагин синтаксическое состояние $mode в своей разметке. Поведение по умолчанию заключается в проверке наличия $mode в массиве состояний, хранящемся в унаследованном свойстве allowedModes.

При необходимости могут быть определены дополнительные функции. Рекомендуется добавлять впереди символ подчерка к названиям самостоятельно определённых функций для того, чтобы избежать возможных пересечений имён при дальнейшем развитии спецификации плагинов.

Унаследованные свойства

allowedModes — начальное значение: пустой массив, унаследованный от класса Doku_Parser_Mode, определённого в inc/parser/parser.php. Содержит список других синтаксических состояний, появление которых допустимо внутри собственного синтаксического состояния плагина (т. е. состояния, которые относятся к любым другим элементам разметки «ДокуВики», которые могут быть включены внутрь собственной разметки плагина). Обычно он автоматически заполняется функцией accepts(), используя результаты getAllowedTypes().

Синтаксические типы

«ДокуВики» использует различные синтаксические типы для того, чтобы определить, какие синтаксические конструкции могут быть вставлены внутрь другой. Например, вы можете вставить текстовое форматирование внутрь таблицы.

Для того, чтобы интегрировать свой плагин в эту систему, нужно указать, какой тип он имеет и какие типы могут вставляться в него. В настоящий момент доступны следующие типы:

Тип	Используется в…	Описание
container	listblock, table, quote, hr	Контейнеры — это сложные состояния, которые могут содержать много других состояний, но они не должны использоваться в таблицах и списках (состояние `hr` нарушает общий принцип), поэтому они отнесены к этому типу.
baseonly	header	Некоторые состояния допустимы только внутри базового состояния.
formatting	strong, emphasis, underline, monospace, subscript, superscript, deleted, footnote	Состояния для изменения стиля текста (сноски (footnote) также можно рассматривать как стиль).
substition²⁾	acronym, smiley, wordblock, entity, camelcaselink, internallink, media, externallink, linebreak, emaillink, windowssharelink, filelink, notoc, nocache, multiplyentity, quotes, rss	Состояния, в которых токен просто меняется на что-то; не могут содержать в себе другие состояния.
protected	preformatted, code, file, php, html	Состояния, имеющие начальный и конечный токены, но внутри которых не допустимы никакие другие состояния.
disabled	unformatted	Внутри этого состояния вики-разметка не отрабатывается, переносы строки и пробелы не сохраняются.
paragraphs	eol	Используется для отметки границ параграфов.

Для описания того, что каждый из типов значит и какие другие классы форматирования зарегистрированы в них, читайте комментарии в файле inc/parser/parser.php.

Руководство: разбор синтаксического плагина

Цель данного руководства — разобрать концепции, касающиеся синтаксических плагинов «ДокуВики» и пройти шаги, связанные с написанием своего собственного плагина.

Для тех, кто с особым нетерпением жаждет начать: возьмите копию плагина syntax plugin skeleton. Это своего рода костяк — плагин, который выводит «Hello World!», когда встречает токен «<TEST>» в статье вики. Начните наращивать на него «мясо».

Краткая выжимка

состояния — modes

Каждый отдельный элемент синтаксиса «ДокуВики», включая и ваш собственный плагин, имеет своё собственное состояние.
Похожие состояния группируются в типы состояний.
«allowedTypes» каждого состояния определяет, какие другие синтаксические конструкции «ДокуВики» опознаются внутри собственной синтаксической конструкции этого состояния. Все состояния из «allowedTypes» допустимы.
«Тип» состояния даёт понять другим состояниям, могут ли они допустить использование данного состояния внутри своего синтаксиса.

handle

Метод handle() вызывается, когда парсер решит, что столкнулся в содержимом статьи вики с куском, относящимся к синтаксису вашего состояния.
Параметр $state говорит, какой тип шаблона из приписанных к вашему состоянию сработал. Если это просто обычный текст, то параметр state будет установлен в DOKU_LEXER_UNMATCHED.
Производите как можно больше обработки и принятия решений именно тут, оставляя как можно меньше на обработку методу render(), потому что выдача метода handle кэшируется. This also means that you shouldn't do any stuff here that mustn't be cached.

render

Метод render() выполняет инструкции отображения, которые применимы к синтаксическому состоянию плагина (и которые были созданы методом handle() плагина.
Добавляйте содержание к выходному документу с помощью $renderer->doc .= 'content';
Убедитесь, что любая выдача вашего плагина безопасна (run raw wiki data through an entity conversion function).
Совершайте как можно меньше операций по обработке и принятию решений здесь, это всё следует делать в методе handle().

Нет никакой гарантии, что метод render() будет вызван в то же время, что и метод handle(). Инструкции, произведённые хэндлером, кэшируются и могут использоваться рендером в более позднее время. Единственный надёжный способ передать данные от handle() к render() — это использовать возвращаемый методом handle() массив, который передаётся методу render() в качестве параметра $data.

Ключевые концепции

Состояния

Состояния (более точно синтаксические состояния) — это основа, на которой базируется парсер «ДокуВики». Каждый отдельный элемент разметки «ДокуВики» имеет своё синтаксическое состояние. Например, существует состояние strong для работы со strong, состояние superscript для работы с ^superscript, состояние table для работы таблицами и многие другие.

Когда парсер сталкивается с разметкой, он попадает в соответствующее этой разметке синтаксическое состояние. Свойства и методы конкретного синтаксического состояния управляют тем, как ведёт себя парсер, пока он в этом состоянии, включая:

какие другие состояния могут произойти;
какие инструкции подготовить для рендера.

Ваш плагин добавит своё синтаксическое состояние к парсеру — это автоматически производится «ДокуВики», когда впервые загружает плагин, назначаемое имя — plugin_+ имя директории плагина (которое является также именем класса плагина без префикса «syntax_»). Затем, когда парсер сталкивается с разметкой, используемой вашим плагином, он (парсер) войдёт в это синтаксическое состояние. Пока он находится в этом состоянии, ваш плагин управляет тем, что может делать парсер.

Типы состояний

Для упрощения синтаксические состояния, которые ведут себя одинаковым образом, были сгруппированы в несколько типов состояний — полный список может быть найден в разделе «Синтаксические плагины».

Каждый тип состояний соотносится с ключом в массиве $PARSER_MODES. Элемент этого массива, соответствующий каждому типу состояний, сам является массивом, который содержит все синтаксические состояния, относящиеся к этому типу. Например, в «чистой» «ДокуВики» без установленных плагинов элемент массива $PARSER_MODES['formatting'] содержит: strong, emphasis, underline, superscript, subscript, monospace, deleted и footnote.

Когда плагин загружается в парсер, то через getType() он запрашивается о типе состояния, к которому относится. Затем синтаксические состояния, относящиеся к плагину, добавляются в соответствующий массив $PARSER_MODES.

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

Если они допускают конкретный тип состояний, он допускают все состояния этого типа, включая любые плагины, которые заявили этот тип состояний.

Выберите тип состояний для своего плагина, сравнивая поведение своего плагина с поведением стандартных состояний «ДокуВики». Выберите тип, к которому относятся наиболее похожие состояния.

Допустимые состояния

Есть другие состояния, которые могут возникнуть внутри разметки вашего собственного состояния.

Каждое синтаксическое состояние имеет собственный массив допустимых состояний, который говорит парсеру, какие именно другие синтаксические состояния будут опознаваться во время обработки состояния. То есть, если вы хотите, чтобы ваш плагин мог оказаться внутри разметки «**strong**», тогда состояние strong должен включить состояние вашего плагина в свой массив «allowedModes». И если вы хотите позволить разметке strong включаться внутрь разметки вашего плагина, то ваш плагин должен содержать 'strong' в своём массиве «allowModes».

Ваш плагин собирает в массив «allowedModes» другие синтаксические состояния посредством типа состояний, объявляемого методом getType().

Ваш плагин сообщает парсеру, какие другие синтаксические состояния он допускает, декларируя (объявляя) их через метод getAllowedTypes().

PType

PType определяет, как парсеру работать с HTML-элементами <p>, когда он имеет дело с вашим синтаксическим состоянием.

Обычно в тот момент, когда парсер сталкивается с некоторой разметкой, имеется открытый HTML-тэг параграфа. Парсеру необходимо знать, должен ли он закрыть этот тэг перед входом в ваше синтаксическое состояние и затем открыть другой параграф на выходе (PType='block' или PType='stack') или парсер должен оставить параграф в покое (PType='normal').

PType также определяет будет ли параграф создаваться внутри вашего синтаксического состояния. И если будет - то как.

Если PType='normal', то параграф не будет создаваться вовсе.

Если PType='block', то парсер закроет параграф перед входом в ваше синтаксическое состояние, и откроет новый параграф после выходы из вашего синтаксического состояния. Внутри вашего синтаксического состояния создание параграфов должно быть запрещено (см. "Допустимые состояния"), иначе открытый параграф закроется как обычно (как только встретятся два подряд или более newlines), и откроется новый. В результате, например, открывающий TAG <DIV> может оказаться внутри одного параграфа, а закрывающий </DIV> внутри другого. Или ещё что-то.

Если PType='stack', то парсер:

закроет параграф перед входом в ваше синтаксическое состояние;
откроет параграф после входа в ваше синтаксическое состояние;
если внутри вашего синтаксического состояния разрешёно создавать параграфы (см. "Допустимые состояния"), то параграфы внутри вашего синтаксического состояния будут создаваться как обычно (как только встретятся два подряд или более newlines). Если не разрешено, то параграф так и останется открытым до выхода из вашего синтаксического состояния;
перед выходом из вашего синтаксического состояния парсер закроет параграф (в этом месте он должен быть открыт, не зависимо от того, разрешено ли создавать параграфы внутри или нет);
после выходы из вашего синтаксического состояния парсер откроет новый параграф.

Для тех, кто знает CSS, возвращение PType='block' означает, что html, произведённый вашим плагином, будет похож на display:block, а возвращение PType='normal' означает html, похожий на display:inline.

Пример

Предполагается, что вы хорошо знакомы со стандартным шаблоном syntax plugin ENTRY ⇒ UNMATCHED ⇒ EXIT. В зависимости от значения PType <p> и </p> будут расставляться автоматически рендером в разных точках снаружи и внутри текста плагина. Поэтому вашему плагину не нужно заботиться об этих тэгах.

wikisyntax	PType=normal	PType=block	PType=stack
foo <plugin>text</plugin> bar	<p>foo ENTRY("<plugin>") UNMATCHED("text") EXIT("</plugin>") </p> <p>bar</p>	<p>foo</p> ENTRY("<plugin>") UNMATCHED("text") EXIT("</plugin>") <p>bar</p>	<p>foo</p> ENTRY("<plugin>") <p> UNMATCHED("text") </p> EXIT("</plugin>") <p>bar</p>

wikisyntax

PType=normal

PType=block

PType=stack

foo
<plugin>text</plugin>

bar

<p>foo
ENTRY("<plugin>")
UNMATCHED("text")
EXIT("</plugin>")
</p>
<p>bar</p>

<p>foo</p>
ENTRY("<plugin>")
UNMATCHED("text")
EXIT("</plugin>")
<p>bar</p>

<p>foo</p>
ENTRY("<plugin>")
<p>
UNMATCHED("text")
</p>
EXIT("</plugin>")
<p>bar</p>

Порядковый номер

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

Вы можете использовать это свойство для написания плагина, который заменяет или расширяет «родной» хендлер «ДокуВики» для той же синтаксической конструкции. Примером является плагин «Code».

Подробности о существующих порядковых номерах доступны для обоих parser (sort list).

Шаблоны

Парсер использует PHP-функции «preg»⁴⁾. Детальное объяснения регулярных выражений и их синтаксиса выходит за пределы этого руководства. Существует много хороших источников в интернете.

Полный синтаксис «preg» не доступен для использования в конструировании шаблонов синтаксических плагинов. Ниже приведён список известных различий:

Шаблоны не окружаются разделителями.
Для использования вертикальной черты «|» при множественных альтернативах, сделайте их non-captured-группами, т. е. «(?:cat|dog)».
Будьте очень осторожны с «заглядыванием назад». Парсер только пытается сравнить шаблон со следующим куском «ещё не проверенных» данных. Если вам нужно заглянуть в символы, которые уже участвовали в предыдущем сравнении с шаблоном, то этих символов там на самом деле не будет.
Флаги опций могут быть включены только как встроенные опции, т. е. (?i), (?-i).

Парсер предоставляет плагину четыре функции для регистрации необходимых шаблонов. Каждая функция относится к шаблонам с разными смыслами.

специальные шаблоны — addSpecialPattern() — это шаблоны, которые используются, когда один шаблон — это всё, что нужно. В терминах парсера эти шаблоны представляют и вход в синтаксическое состояние плагина, и выход из этого синтаксического состояния, всё в одно сравнение. Обычно они используются в плагинах substition.
входные шаблоны — addEntryPattern() — шаблон, указывающий на начало данных, которые должны быть обработаны плагином. Обычно эти шаблоны должны включать в себя заглядывание вперёд для проверки существования выходного шаблона. Любой плагин, который регистрирует входной шаблон, также должен зарегистрировать выходной шаблон.
выходные шаблоны — addExitPattern() — шаблон, указывающий на конец данных, которые должны быть обработаны плагином. Этот совпадение с этим шаблоном может произойти, только если было найдено совпадение с входным шаблоном⁵⁾.
внутренние шаблоны — addPattern() — представляют специальный синтаксис, применимый к плагину, который может встретиться между входным и выходным шаблонами. Обычно это нужно только для достаточно сложных структур, например, таблиц и списков.

Один плагин может добавить несколько шаблонов в парсер, включая более чем один шаблон одного типа.

Советы

Используйте «нежадные» идентификаторы, т. е. +? или *? вместо + или *.
Будьте осторожны с использованием нескольких выходных шаблонов. Скорее всего сработает выход из состояния по первому встреченному выходному шаблону, даже если это будет не тот шаблон, который «увидел при заглядывании вперёд» входной шаблон. Необходимость нескольких выходных шаблонов может означать, что на самом деле вам нужны несколько плагинов.
В ранних версиях «ДокуВики» лексер имел баг, не дававший использовать угловые скобки «<» или «>» в «заглядывающих вперёд» шаблонах. Этот баг был исправлен и угловые скобки теперь допустимы. Некоторые плагины всё ещё содержат шестнадцатеричные обозначения для угловых скобкок («\x3C», «\x3E») — такой приём позволял обойти баг.

Метод handle()

Это часть вашего плагина, которая должна совершать всю работу. До того как «ДокуВики» выведет статью вики, он создаёт список инструкций для рендера. Метод handle() плагина создаёт инструкции отображения для собственного синтаксического состояния. В некий более поздний момент они будут интерпретированы методом render() плагина. Список инструкций кэшируется и может быть использован много раз, разумно максимально увеличить объём работы, совершаемой один раз этой функцией и максимально уменьшить объём работы, совершаемый много раз функцией render().

Параметр $match — текст, который совпадает с шаблоном, или, в случае DOKU_LEXER_UNMATCHED, непрерывный кусок обычного текста, который не совпал с каким-либо шаблоном.

Параметр $state — тип шаблона, из-за которого запустился вызов handle().

DOKU_LEXER_ENTER — шаблон установлен функцией addEntryPattern();
DOKU_LEXER_MATCHED — шаблон установлен функцией addPattern();
DOKU_LEXER_EXIT — шаблон установлен функцией addExitPattern();
DOKU_LEXER_SPECIAL — шаблон установлен функцией addSpecialPattern();
DOKU_LEXER_UNMATCHED — обычный текст, встреченный внутри синтаксического состояния плагина, который не совпал ни с одним шаблоном.

Параметр $pos — позиция первого символа найденного текста.

Параметр &$handler — ссылка на объект Doku_Handler.

Метод render()

Часть плагина, которая производит вывод окончательной веб-страницы или какой-либо другой поддерживаемый формат. Именно здесь плагин добавляет собственный вывод к уже созданным другими частями рендерера путём склейки со свойством doc рендера. Т. е.:

$renderer->doc .= "некий вывод плагина...";

В любых сырых данных вики, которые передаются render(), все спецсимволы должны быть преобразованы в элементы HTML. Вы можете использовать PHP-функции htmlspecialchars(), htmlentities() или собственный метод xmlEntities() рендера. Т. е.:

$renderer->doc .= $renderer->_xmlEntities($text);

Параметр $mode — имя формата состояния финального вывода произведённого рендером. В настоящее время «ДокуВики» поддерживает только один формат вывода — XHTML ⁶⁾.

Новые состояния могут быть представлены в плагинах рендера. Плагины должны производить вывод только для тех форматов, которые они поддерживают, это значит, что эта функция должна быть структурирована…

if ($mode == 'xhtml') {  // supported mode
  // code to generate XHTML output from instruction $data
}

Параметр $data — массив, содержащий инструкции, предварительно подготовленные собственным методом handle() плагина. Эта функция должна интерпретировать инструкции и выдавать соответствующий вывод.

Безопасность

Сырые данные вики, которые достигли вашего плагина, больше никогда не должны обрабатываться. Никакой дальнейшей обработки не производится над выводом после того, как он покидает плагин. Как минимум, плагин должен убедиться, что в выводе все спецсимволы HTML заменены на HTML-последовательности. Также к извлечённым и используемым внутри данным вики нужно относится с вниманием. См. также статью «Безопасность».

Локализация

Смотрите статьи «Локализация» и «Структура файлов плагина».

Конфигурация

Смотрите статью «Конфигурация».

Использование CSS и JavaScript

Смотрите статью «Структура файлов плагина».

Добавление кнопок к панели инструментов

Для того, чтобы облегчить жизнь пользователям вики, которые установили ваш плагин, следует добавить кнопку в панель инструментов редактора.

См. статьи:

Написание своего собственного плагина

Ну хорошо, вы решили расширить синтаксис «ДокуВики» своим собственным плагином. Вам придётся разработать, каким будет ваша синтаксическая конструкция и как она будет отображаться в браузере пользователя. Теперь вам необходимо написать сам плагин.

Примите решение, как назвать плагин. Возможно вы захотите проверить список доступных плагинов, чтобы убедиться, что такое имя уже не используется.
В своей собственной установке «ДокуВики» создайте собственную поддиректорию в директории lib/plugins/. Эта директория должна называться также, как ваш плагин.
Создайте в новой директории файл syntax.php. В качестве отправной точки, можете использовать скелет плагина. Скопируйте его в свою директорию.
Отредактируйте этот файл под свои нужды:
- измените название класса, чтобы он был вида syntax_plugin_<название вашего плагина>⁷⁾;
- измените метод getInfo(), чтобы он выдавал информацию о вашем плагине;
- измените метод getType(), чтобы он выдавал тип состояний, к которому относится ваш плагин;
- добавьте метод getAllowedTypes() для сообщения всех типов состояний, которые ваш плагин может включать внутрь своей собственной синтаксической конструкции. Если ваш плагин не желает позволять какому-либо состоянию включаться в себя, он может быть выкинут;
- измените метод getPType(), чтобы он выдавал PType, который относится к вашему плагин. Если это 'normal', вы можете просто убрать этот метод;
- измените метод getSort(), чтобы он выдавал уникальный номер, проверьте его в списке плагинов;
- измените метод connectTo(), чтобы зарегистрировать шаблон для опознавания вашего синтакиса;
- добавьте метод postConnect(), если ваш синтаксис имеет второй шаблон, для того, чтобы указать, когда парсер должен покинуть ваше синтаксическое состояние.
Ну вот, простая часть работы сделана, теперь у вас есть плагин, которой скажет «Hello World!», когда встретит шаблон вашего синтаксиса. Самое время проверить его и убедиться, что шаблон работает как надо — посетите свою вики и создайте статью с синтаксической страницей своего плагина, сохраните её и убедитесь, что «Hello World!» действительно показывается.
Напишите свои собственные методы handle() и render():
- если у вас есть входной и выходной шаблоны, не забудьте обработать не совпавшие с шаблоном данные;
- относитесь к сырым данным вики с подозрением (вниманием) и убедитесь, что все спецсимволы прошли конвертор последовательностей.
Протестируйте и добавьте плагин на страницу плагинов «ДокуВики».

Пример 1-й плагина — Now

Когда синтаксическая конструкция этого плагина [NOW] встречается в статье вики, текущая дата и время отображается в формате RFC2822.

Типом является 'substition'. Мы подставляем временую метку вместо токена [NOW], аналогично смайлам и акронимами. Они также относятся к типу состояний 'substition'.
Заполнять «allowedTypes» не требуется, т. к. никакие другие синтаксические конструкции не могут появиться в конструкции [NOW]. Т. о. нам не нужен метод getAllowedTypes().
PType — normal — это значение по умолчанию, поэтому нам не нужно определять метод getPType().
Нет необходимости во входном и выходном шаблонами, только специальный шаблон, чтобы найти [NOW]. Единственная вещь, с которой нужно быть осторожным, это то, что символы «[» и «]» имеют специальное значение в регулярных выражениях, поэтому нам нужно «выключить» (escape) их, создав шаблон '\[NOW\]'.
В нашем случае метод handler() не должен ничего делать. Нам не нужно заботиться о специальных состояниях или дополнительных параметрах в нашем синтаксисе. Мы просто вернём пустой массив в качестве инструкций для рендера.
Всё, что нужно методу render() — добавить штамп времени к текущей статье вики — $renderer->doc .= date('r');

И вот наш плагин завершён!

syntax.php

<?php
/**
 * Plugin Now: Inserts a timestamp.
 * 
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Christopher Smith <chris@jalakai.co.uk>
 */
 
// must be run within DokuWiki
if(!defined('DOKU_INC')) die();
 
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'syntax.php');
 
/**
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
 */
class syntax_plugin_now extends DokuWiki_Syntax_Plugin {
 
    function getInfo(){
      return array(
        'author' => 'me',
        'email'  => 'me@someplace.com',
        'date'   => '2005-07-28',
        'name'   => 'Now Plugin',
        'desc'   => 'Include the current date and time',
        'url'    => 'http://www.dokuwiki.org/plugin:tutorial',
      );
    }
 
    function getType() { return 'substition'; }
    function getSort() { return 32; }
    function connectTo($mode) { 
        $this->Lexer->addSpecialPattern('\[NOW\]',$mode,'plugin_now'); 
    }
    function handle($match, $state, $pos, &$handler) { 
        return array($match, $state, $pos); 
    }
    function render($mode, &$renderer, $data) {
 
      if($mode == 'xhtml'){
          $renderer->doc .= date('r');
          return true;
      }
      return false;
    }
}
?>

Замечание: из-за способа, которым «ДокуВики» кэширует страницы, этот плагин будет отображать дату/время для момента, когда был создан кэш страницы. Вам нужно добавить на страницу макрос ~~NOCACHE~~,чтобы отображалось правильное время каждый раз, когда запрашивается страница.

Пример 2-й плагина — Color

Когда встретится синтаксическая конструкция плагина <color somecolour/somebackgroundcolour> встречается в статье вики, цвет текста сменяется на «somecolour», а цвет фона — на «somebackgroundcolour»; и оба остаются такими, пока не встретится </color>.

То, что мы делаем, подобно тому, что делает состояние strong, его тип — 'formatting', поэтому мы тоже должны использовать этот тип.
«allowedTypes» должны быть inline состояния - substition, formatting и disabled.
PType — normal — это значение по умолчанию, поэтому нам снова не нужен метод getPType().
Нам нужны входные и выходные шаблоны. Входной шаблон должен проверять, что есть и выходной шаблон, т. е. '<color.*>(?=.*?</color>)'. Выходной шаблон аналогично </color>.
Метод handle() должен иметь дело с тремя состояниями: совпадающими с входным и выходным шаблонами и «несовпадающим» для промежуточного текста.
- Состояние DOKU_LEXER_ENTER требует некоторой обработки для извлечения значений цветов текста и фона, они войдут в инструкцию для нашего рендера.
- Состояние DOKU_LEXER_UNMATCHED не требует какой-либо обработки, но нам придётся передать «несовпадающий» текст (в параметре $match) методу render(), поэтому он войдёт в инструкцию для нашего рендера.
- Состояние DOKU_LEXER_EXIT не требует какой-либо обработки и не имеет никаких особых данных, мы просто должны сделать выходную инструкцию для render().
Методу render() необходимо иметь дело с теми же тремя сотояниями, что и handle().
- DOKU_LEXER_ENTER — отрыть тэг span с указанием стиля, использующего значения цветов текста и фона.
- DOKU_LEXER_UNMATCHED — добавить «несовпавший» текст к выходному документу.
- DOKU_LEXER_EXIT — закрыть тэг span.

Опять же, всё достаточно очевидно. И вот, что мы имеем:

syntax.php

<?php
/**
 * Plugin Color: Sets new colors for text and background.
 * 
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Christopher Smith <chris@jalakai.co.uk>
 */
 
// must be run within Dokuwiki
if(!defined('DOKU_INC')) die();
 
if(!defined('DOKU_PLUGIN')) define('DOKU_PLUGIN',DOKU_INC.'lib/plugins/');
require_once(DOKU_PLUGIN.'syntax.php');
 
/**
 * All DokuWiki plugins to extend the parser/rendering mechanism
 * need to inherit from this class
 */
class syntax_plugin_color extends DokuWiki_Syntax_Plugin {
 
    /**
     * return some info
     */
    function getInfo(){
        return array(
            'author' => 'Christopher Smith',
            'email'  => 'chris@jalakai.co.uk',
            'date'   => '2008-02-06',
            'name'   => 'Color Plugin',
            'desc'   => 'Changes text colour and background',
            'url'    => 'http://www.dokuwiki.org/plugin:tutorial',
        );
    }
 
    function getType(){ return 'formatting'; }
    function getAllowedTypes() { return array('formatting', 'substition', 'disabled'); }   
    function getSort(){ return 158; }
    function connectTo($mode) { $this->Lexer->addEntryPattern('<color.*?>(?=.*?</color>)',$mode,'plugin_color'); }
    function postConnect() { $this->Lexer->addExitPattern('</color>','plugin_color'); }
 
 
    /**
     * Handle the match
     */
    function handle($match, $state, $pos, &$handler){
        switch ($state) {
          case DOKU_LEXER_ENTER :
                list($color, $background) = preg_split("/\//u", substr($match, 6, -1), 2);
                if ($color = $this->_isValid($color)) $color = "color:$color;";
                if ($background = $this->_isValid($background)) $background = "background-color:$background;";
                return array($state, array($color, $background));
 
          case DOKU_LEXER_UNMATCHED :  return array($state, $match);
          case DOKU_LEXER_EXIT :       return array($state, '');
        }
        return array();
    }
 
    /**
     * Create output
     */
    function render($mode, &$renderer, $data) {
        if($mode == 'xhtml'){
            list($state,$match) = $data;
            switch ($state) {
              case DOKU_LEXER_ENTER :      
                list($color, $background) = $match;
                $renderer->doc .= "<span style='$color $background'>"; 
                break;
 
              case DOKU_LEXER_UNMATCHED :  $renderer->doc .= $renderer->_xmlEntities($match); break;
              case DOKU_LEXER_EXIT :       $renderer->doc .= "</span>"; break;
            }
            return true;
        }
        return false;
    }
 
    // validate color value $c
    // this is cut price validation - only to ensure the basic format is correct and there is nothing harmful
    // three basic formats  "colorname", "#fff[fff]", "rgb(255[%],255[%],255[%])"
    function _isValid($c) {
        $c = trim($c);
 
        $pattern = "/^\s*(
            ([a-zA-z]+)|                                #colorname - not verified
            (\#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}))|        #colorvalue
            (rgb\(([0-9]{1,3}%?,){2}[0-9]{1,3}%?\))     #rgb triplet
            )\s*$/x";
 
        if (preg_match($pattern, $c)) return trim($c);
 
        return "";
    }
}
?>

Замечание: никаких проверок на корректность названий цветов или значения RGB не производилось.

Дополнения и Файлы

Ссылка на оригинал статьи

¹⁾

См. Doku_Handler_Block

²⁾

Да, это неправильное написание, но мы не хотели бы его менять, чтобы избежать нарушения существующих плагинов. Иногда опечатки становятся стандартами, возьмите к примеру HTTP-заголовок «referer»

³⁾

Lexer — часть парсера, анализируящая «сырую» (исходную) статью вики.

⁴⁾

Совместимые с Perl регулярные выражения. Ссылка: www.php.net/manual/en/ref.pcre.php.

⁵⁾

Криво переведено с англ.

⁶⁾

Существует ещё специальное состояние metadata, которое ничего не выводит, только собирает метаданные для страницы. Используйте его для вставки значений в массив метаданных.

⁷⁾

Название не может содержать символов подчерка и должно совпадать с названием класса

table_css

anonymous@undisclosed.example.com (Anonymous) — Mon, 26 Aug 2024 06:04:01 +0000

Таблицы стилей CSS

Многое в отображении «ДокуВики» контролируется через таблицы стилей CSS. «ДокуВики» сама по себе определяет очень ограниченный набор стилей. Остальные описания CSS берутся из используемых шаблонов и плагинов.

Все файлы CSS предоставляются через единый диспетчер в lib/exe/css.php, который, кроме того, управляет кэшированием, заменами по маске и оптимизацией. Загрузка таблиц стилей производится (наряду с другими вещами) функцией tpl_metaheaders(), так что не забывайте включить её в свой шаблон.

Режимы таблиц стилей

«ДокуВики» знает о пяти типах режимов по умолчанию:

screen — этот режим используется при отображении страниц в окне веб-браузера;
all — применяется во всех режимах отображения;
print — определения отсюда будут использоваться при печати страницы;
rtl — определения из файлов rtl будут загружены дополнительно, когда используется язык с написанием справа-налево;
feed — применяется для отображения новостной ленты.

Таблицы стилей «ДокуВики»

«ДокуВики» загружает таблицы стилей из 4-х источников в следующем порядке (таблицы стилей RTL добавляются в конце каждого шага):

1. Базовые таблицы стилей

Эти таблицы располагаются в /lib/styles. Они определяют базовый стиль, вроде оформления сообщений об ошибках.

2. Стили плагинов

Плагины могут объявить свои собственные определения стиля, используя следующие файлы:

Режим	Файл CSS
screen	`style.css` или `screen.css`
print	`print.css`
all	`all.css`
rtl	`rtl.css`
feed	`feed.css`

Чтобы лучше сочетаться с цветовой схемой любого шаблона, авторы плагинов должны использовать гарантированные цветовые подстановки.

Таблицы стилей плагина загружаются, даже если сам плагин не используется (но не если он выключен).

Определённые здесь стили должны позаботиться о возможных конфликтах. Поэтому будьте осторожны при написании плагинов. Если возможно, добавляейте префиксы к названиям ваших стилей для избежания конфликтов.

3. Стили шаблонов

Таблицы стилей шаблонов загружаются из директории выбранного шаблона. «ДокуВики» читает style.ini, расположенный в директории шаблона и загружает все CSS, упомянутые в этом файле. Загрузка происходит в соответствии с текущим режимом.

Дополнительно в файле style.ini определяются подстановки.

См. также: «Разработка шаблонов»

4. Пользовательские стили

Независимо от используемого шаблона, администратором вики могут быть определены дополнительные стили с помощью следующих файлов CSS в директории conf/:

Файл CSS в «Муравьеде»	Файл CSS после и до «Муравьеда»¹¹⁾	Когда используется
`conf/userstyle.css`	`conf/userstyle.css`	Применяется во всех режимах отображения
`conf/printstyle.css`	`conf/userprint.css`	Применяется при отправке на печать
`conf/rtlstyle.css`	`conf/userrtl.css`	Применяется, если используется языковой интерфейс с написанием справа-налево (right-to-left)
`conf/feedstyle.css`	`conf/userfeed.css`	Applied when displaying the feed
`conf/allstyle.css`	`conf/userall.css`	Applied in all display modes

Это полезно для переопределения небольшой части стилей шаблона или плагина без возникновения проблем при их дальнейшем обновлении.

Использование ID

Когда вы используете произвольный ID в вашем шаблоне для назначения стиля, убедитесь, что этот ID не конфликтует с уже имеющимися. В частности, убедитесь, что нет конфликта с автоматически назначаемыми ID для заголовков разделов. Простейший путь добиться этого — использовать два смежных символа подчерка (__) в вашем ID. Поскольку ID разделов всегда представляют собой допустимое имя статьи, они никогда не будут содержать смежных подчерков.

style.ini

Файл style.ini — это ini-файл. Он содержит два раздела:

[stylesheets]

В этой части определяется какие файлы CSS будут загружены. Каждая строка имеет вид:

cssfile.css = mode

cssfile.css — имя вашего файла; mode — режим, к которому применяется файл.

[replacements]

Диспетчер CSS «ДокуВики» способен заменять подстановки в загружаемый таблицах стилей, которые назначаются в разделе [replacements] в файле style.ini шаблона. Это исключительно полезно для определения цветовых схем в одном месте и дальнейшем использовании их во всех других файлах. После этого смена цветовой схемы сводится к просто редактированию ini-файла.

Гарантированные цветовые подстановки

Только следующие подстановки могут безопасно применяться в плагинах.

Переменная подстановки	Назначение	Значение в шаблоне по умолчанию	Название до 2006-08-05
`__background__`	основной цвет фона	`#fff`	`__white__`
`__background_alt__`	альтернативный цвет фона	`#dee7ec`	`__medium__`
`__background_neu__`	нейтральный цвет фона	`#f5f5f5`	`__darkgray__`
`__border__`	цвет окантовки	`#8cacbb`	`__dark__`
`__text__`	основной цвет текста	`#000`	`__black__`
`__text_alt__`	альтернативный цвет текста	`#638c9c`	`__darker__`
`__text_neu__`	нейтральный цвет текста	`#666`	`__lightgray__`

Начиная с 2006-08-05 подстановки были переименованы, их названия стали более корректными семантически. Плагины и шаблоны, использующие подстановки написанные после этого, могут даже не адаптироваться к старым переменным, но всё же желательно это делать.

Другие цветовые подстановки, используемые шаблоном по умолчанию

Эти дополнительные подстановки используются в шаблоне по умолчанию. Другие шаблоны также могут использовать их, но не обязаны делать это.

Переменная подстановки	Назначение	Значение в шаблоне по умолчанию	Название до 2006-08-05
`__background_other__`	другой цвет фона	`#f7f9fa`	`__lighter__`
`__text_other__`	другой цвет текста	`#ccc`	`__mediumgray__`
(none, omitted)	-	`#eef3f8`	`__light__`
`__extern__`	цвет ссылки	`#436976`	(не менялось)
`__existing__`	цвет для существующих внутренних ссылок	`#090`	(не менялось)
`__missing__`	цвет для несуществующих внутренних ссылок	`#f30`	(не менялось)
`__highlight__`	цвет для подсвечивания найденых кусков текста	`#ff9`	(не менялось)

¹¹⁾

changed back on 2011-02-26

template_info

anonymous@undisclosed.example.com (Anonymous) — Mon, 10 Feb 2025 15:57:09 +0000

Информация о шаблоне

Каждый шаблон должен предоставить некоторую базовую информацию о себе. Это делается с помощью файла с именем, template.info.txt расположенного в каталоге шаблона .

Вот пример того, как должен выглядеть такой файл.

lib/tpl/example/template.info.txt

base     example
author   My Full Name
email    me@example.com
date     2012-09-08
name     Example Template
desc     This is just an Example of how a template description looks like
url      https://www.dokuwiki.org/template:example

Параметр	Описание
base	Техническое имя шаблона. Extension Manager установит его в этот каталог.¹²⁾. См. также соглашения об именовании шаблонов
author	Полное имя автора шаблона
email	Электронная почта для связи с автором шаблона по поводу этого шаблона
date	Дата последнего обновления этого шаблона в формате ГГГГ-ММ-ДД. Не забудьте обновить это, когда будете обновлять свой шаблон! ¹³⁾
name	Удобочитаемое имя шаблона
desc	Описание того, что делает шаблон и как он выглядит
url	URL-адрес , по которому можно получить более подробную информацию о шаблоне

¹²⁾

Важно иметь уникальное базовое значение поля (т. е. имя шаблона), иначе уже существующий шаблон с таким именем может быть перезаписан.

¹³⁾

Эта дата должна быть равна дате «Последнее обновление» на странице шаблонов в репозитории. Это необходимо для автоматической маркировки обновлений, используемой Extension Manager, представленной в выпуске Ponder Stibbons

template

anonymous@undisclosed.example.com (Anonymous) — Sat, 24 Aug 2024 18:36:02 +0000

Шаблоны

Вид «Докувики» может быть изменён при помощи шаблонов (другое название — скины или темы). Ниже представлен список доступных шаблонов. Дополнительная информация доступна по ссылкам ниже:

Установка шаблона

Установить шаблон очень легко. Просто распакуйте архив с шаблоном (обычно .zip или .tgz) в lib/tpl/ ¹⁾.

Затем в настройках вики выберите установленный шаблон.

Создание шаблона

Если вы создали шаблон, которым хотите поделиться с остальными, — добавьте его в список, создав новую страницу в пространстве имён template, например, перейдя по ссылке:

http://www.dokuwiki.org/template:<название_вашего_шаблона>

Пожалуйста, всегда указывайте имя автора шаблона, информацию о совместимости с различными версиями «ДокуВики» и дату последнего изменения.

Замечание разработчикам шаблонов: пожалуйста, вносите приемлемое описание ключевых функциональных возможностей и отличительных качеств вашего шаблона. Также, приветствуются достаточно большие для просмотра снимки экрана (пример есть в «Монобуке»).

Доступные шаблоны

Поиск шаблонов

Если вы хотите, чтобы шаблон другого проекта портировали в «ДокуВики», обратитесь на подфорум Template Wishlist.

¹⁾

Если в архиве нет самой папки, нужно создать lib/tpl/<templatename> и распаковать туда архив.

templates

anonymous@undisclosed.example.com (Anonymous) — Mon, 10 Feb 2025 15:50:20 +0000

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

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

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

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

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

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

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

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

<dokuwiki>/lib/tpl/<template>/
- <filename>.css
- main.php (англ.) — главный файл разметки шаблона «Докувики»
- detail.php (англ.) — страница подробного описания изображения
- mediamanager.php (англ.) — медиаменеджер
- images/ — все используемые в шаблоне изображения
- conf/
  - default.php — стандартные настройки (см. tpl_getConf)
  - metadata.php — конфигурационные метаданные (см. tpl_getConf())
- lang/ — языковые файлы
  - <код языка>/lang.php — локализованные строки, используемые в шаблоне
  - <код языка>/settings.php — локализованные строки, используемые на странице настроек «Докувики»
- style.ini — см. style.ini
- favicon.ico – (можно перезаписать, загрузив другой в корневое или вики-пространство имен при использовании tpl_favicon() is used)
- template.info.txt – Требуется текстовый файл с информацией о шаблоне.

Обработка параметров конфигурации аналогична плагинам . Используйте tpl_getConf(<setting>) для получения пользовательских настроек шаблона. Сохраненные локальные настройки хранятся в глобальном conf/local.php.

Объяснение внутренних механизмов

Функции

Список доступных функций вы можете найти здесь: API documentation. Самые важные приведены ниже.

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

tpl_content(false);

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

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

Пример:

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

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

Пример:

<?php
    // помещает содержимое страницы в буфер для последующего использования
    ob_start();
    tpl_content(false);
    $buffer = ob_get_clean();
?>
 
<div id="sidebar">
    <?php tpl_toc()?>
</div>
 
<div id="content">
    <?php echo $buffer?>
</div>

tpl_getConf('key')
Функция используется для доступа к конфигурационным параметрам из шаблона.

tpl_getLang('key')
Эта функция используется для доступа к локализованным строкам шаблона. Подробности см. в документации по разработке localization development documentation.

Кроме того, доступно множество других полезных функций шаблона. Пожалуйста, посмотрите в документации API.

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

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

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

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

Класс «dokuwiki»

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

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

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

Стандартный шаблон «Докувики» ищет файлы со специальными именами в каталоге 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/wiki:devel:templates

Дополнения и Файлы

К сожалению новый шаблон если имеет ширину страницы > 75em то таблицы в в настройке конфигурации не войдут в размер шаблона. Так как это отдельный плаген и для него отдельный стиль. Для того чтобы его изменить необходимо в файле <dokuwiki>/lib/plugins/config/style.css править значение width в следующих строках кода:

#config__manager td input.edit {
    width: 30em;
}
#config__manager td .input {
    width: 30.8em;
}
#config__manager td select.edit { }
#config__manager td textarea.edit {
    width: 27.5em;
    height: 4em;
}

заменить на следующие значения:

#config__manager td input.edit {
    width: 20em;
}
#config__manager td .input {
    width: 20.8em;
}
#config__manager td select.edit { }
#config__manager td textarea.edit {
    width: auto;
    height: 4em;
}

Боковая панель Aside справа

<dokuwiki>/lib/tpl/starter/css/structure.css

#dokuwiki__site .wrapper {
    position: relative;
}
 
    #dokuwiki__aside {
        width: __sidebar_width__;
        float: right; /* по умолчанию слева (float: left;) */
        position: relative;
        display: block;
    }
    [dir=rtl] #dokuwiki__aside {
        float: right;
    }

toolbar

anonymous@undisclosed.example.com (Anonymous) — Fri, 10 Jan 2025 07:52:36 +0000

Панель инструментов

Панель инструментов делает DokuWiki простым в использовании даже для новичков. Иногда вам может понадобиться расширить панель инструментов еще одной кнопкой. Эта страница расскажет вам немного о том, как работает панель инструментов и как ее расширить.

How the toolbar is built (and cached)

The toolbar is completely built through JavaScript. Which buttons the toolbar contains, is read from an array called toolbar. This array is initialized in /lib/exe/js.php. This is simply done by converting the PHP array structure defined in inc/toolbar.php to JavaScript using JSON.

This means the toolbar gets cached like any other JavaScript in DokuWiki. Whenever you do changes affecting the toolbar you should invalidate DokuWiki's cache (eg. touch conf/local.php) and refresh your browser cache while editing a page (Hit Shift/Ctrl-Reload and ignore the post warning).

The toolbar array

The mentioned toolbar array contains one entry per button. The order of the entries defines the position of the button, with the first entry defining the most left button.

Each entry is an associative array itself, defining the behavior of the button. The following table explains the available fields for the entries.

Name	Description
`type`	button action type: `format` ⇒ wiki markup `mediapopup` ⇒ popup window `picker` ⇒ picker menu `signature` ⇒ signature generation and insertion e.g. `yourtype` ⇒ looks for your custom action function `addBtnActionYourtype`
`title`	title of the button, displayed on mouseover
`icon`	icon to use for the button (based in `DOKUBASE/lib/images/toolbar/`)
`key`	(optional) Hotkey for the button, a value of `n` here would result in the button being pressed when the user presses `ALT + n` in his browser. (See also the access keys used by DokuWiki)
`class`	(optional) classname for styling buttons
`id`	(optional) id added to button, and with a postfix to icon e.g. `<id>_ico`
`format` type specific parameters
`open`	opening tag of wiki markup to insert, cursor will be placed between opening and closing tag
`sample`	example input to be placed between opening and closing tag, will be automatically selected to be overwritten on first input
`close`	closing tag of the wiki markup to insert, cursor will be placed between opening and closing tag
`insert`	wiki markup to insert (for full substitutions)
`mediapopup` type specific parameters
`url`	URL of the popup to open
`name`	internal name of the popup to open
`options`	additional options for the popup window (comma-separated name-value-pairs valid as parameters for the JS function `window.open`
`picker` type specific parameters
`list`	list of insertable items. can either be an associative array (with the item to insert as the key and an image located in `icobase` to use as the value) or just a simple array (with the text-items to insert directly displayed)
`icobase`	subdirectory for item images (based in `DOKUBASE/lib/images/`).

A look at inc/toolbar.php should give you enough examples of what can be defined. Because the array is simply translated from PHP to JavaScript, the above description applies to the PHP array as well as to the resulting JavaScript array from which the toolbar is finally built.

Extending the Toolbar...

The toolbar can be customized in two ways - via JavaScript or PHP. Which method you choose basically depends on your skills and familiarity with the language at hand. For the PHP approach, you will always need to write a plugin, the JavaScript method can be used from a userscript as well.

...using PHP

To extend the toolbar from your plugin you need to write a Action Plugin which registers as a handler for the TOOLBAR_DEFINE event with an AFTER advice. Your handler function will receive the toolbar array as described earlier.

Create your button structure according to the above information and add it to the received event data.-function in inc/toolbar.php.

Example:

function register(Doku_Event_Handler $controller) {
    $controller->register_hook('TOOLBAR_DEFINE', 'AFTER', $this, 'insert_button', array ());
}
 
// ...
 
/**
 * Inserts a toolbar button
 */
function insert_button(Doku_Event $event, $param) {
    $event->data[] = array (
        'type' => 'format',
        'title' => $this->getLang('abutton'),
        'icon' => '../../plugins/example/abutton.png',
        'open' => '<abutton>',
        'close' => '</abutton>',
        'block' => false,
    );
}

Try to use custombuttons

...using JavaScript

Adding a button using JavaScript is similar to doing it in PHP. You just extend the toolbar array.

Because user and plugin scripts will be loaded on all requests, but the toolbar is initialized on editing only, you need to make sure the toolbar array does exist first. Do this by checking if window.toolbar is defined. If it is, you can add your button at the end of the array.

if (typeof window.toolbar !== 'undefined') {
    toolbar[toolbar.length] = {
        type: "format",
        title: "A Button",
        icon: "abutton.png", // located in lib/images/toolbar/
        key: "",
        open: "<abutton>",
        sample: "Text between the tags",
        close: "</abutton>"
    };
}

Here is another example defining a picker dropdown (assumes plugin context):

if (typeof window.toolbar !== 'undefined') {
    var notes_arr = {
        //'insertion string as key' : '[path/]filename.extension of the icon'
        '<note></note>\\n':           'note.png',
        '<note tip></note>\\n':       'tip.png',
        '<note important></note>\\n': 'important.png',
        '<note warning></note>\\n':   'warning.png'
    };
 
    toolbar[toolbar.length] = {
        type: "picker",
        title: LANG.plugins.note.note_tb_title, // localisation
        icon: '../../plugins/note/images/toolbar.png',  //where in lib/images/toolbar/ the images are located
        key: "n", //access key
        list: notes_arr,
        icobase: "../plugins/note/images/toolbar" // subdir of lib/images/ where images can be found.
    };
}

You can register a simple global onclick function for your button by sticking to the naming convention tb_<yourButtonType>. Here is an example for the insert type from lib/scripts/toolbar.js

function tb_insert(btn, props, edid) {
    insertAtCarret(edid,fixtxt(props.insert));
    pickerClose();
    return false;
}

Some notes:

Be aware of the default locations of the images: lib/images/toolbar/ and lib/images/
The available options for access keys depends on the access keys used by DokuWiki and the whether they are reserved by a browser or operation system as short cut. There are many differences.
More about javascript localization

Dynamic Data

The above methods work well for adding static buttons that add static data. When you need to do something more dynamic like adding the current date, you can not simply extend the toolbar array. Instead, you need to dynamically add your button into the DOM using JavaScript.

The files lib/scripts/edit.js, lib/scripts/toolbar.js and lib/scripts/linkwiz.js contains some useful functions to help you with this.

When adding to the toolbar array you must set a custom value for type. You must use characters that are valid in a function name and should capitalize on the first character. When the toolbar is constructed it looks at the value of type and appends it to the string addBtnAction before calling your code. So if you set type to Click the toolbar will call addBtnActionClick. This is an important note because if two plugins use the same type they will conflict with each other and cause strange behavior (such as both buttons doing the exact same thing).

The returned string is «the id for in aria-control». This is explained further in Accessible Rich Internet Applications.

Here is an example partly from the toolbar picker:

/**
 * With the first function we create a new button type called Click
 * 
 * the function name must be addBtnAction<Your type name>
 * in our case it is addBtnActionClick
 *
 * in the other function we simply use the simple toolbar method with the new type
 * 
 * you can easily extend it to complex scripts like the link wizard etc
 */
 
/**
 * Add button action for your toolbar button
 *
 * @param  {jQuery}   $btn  Button element to add the action to
 * @param  {Array}    props Associative array of button properties
 * @param  {string}   edid  ID of the editor textarea
 * @return {string}   If button should be appended return the id for in aria-controls, 
 *                    otherwise an empty string
 */
function addBtnActionClick($btn, props, edid) {
    // initialize stuff if required
    // ...
 
    $btn.click(function() {
        // your click handler
        alert('hey you clicked me');
        return false;
    });
 
    return 'click';
}
 
// add a new toolbar button, but first check if there is a toolbar
if (typeof window.toolbar !== 'undefined') {
    window.toolbar[window.toolbar.length] = {
        type: "Click", // we have a new type that links to the function
        title: "Hey Click me!",
        icon: "../../plugins/click/clickme.png"
    };
}

Tips

If you don't want to append your button at the end of the toolbar, you just need to insert your data into the toolbar array at the position where you want your button, shifting the other buttons to the right.
There are some predefined global variables available which you can access from your Javascript. For example JSINFO contains the page id and namespace, usage: JSINFO.namespace. This might be handy when doing some more dynamic stuff.
Important: If the button does not appear, expire the cache of your DokuWiki by saving your config in the Config Manager or touching the conf/local.php of your wiki AND delete your browser cache (Ctrl+F5 or Ctrl+R)! Then reload the editor page and your button should appear.

Removing Buttons

If you want to remove some of the toolbar buttons, you can do so by adding the following code into /conf/userscript.js. Note that this is not in any function, simply append this code to the end of the file:

/conf/userscript.js

if (typeof window.toolbar !== 'undefined') {
   var blacklist = ["Bold Text", "Italic Text", "Underlined Text", "Monospaced Text", "Strike-through Text", 
   "Same Level Headline", "Lower Headline", "Higher Headline", "Select Headline", "Internal Link", "External Link", 
   "Horizontal Rule", "Add Images and other files (opens in a new window)", "Smileys", "Special Chars", "Insert Signature"];
    window.toolbar = window.toolbar.filter(function(elem){ return jQuery.inArray(elem.title, blacklist) === -1; });
}

This is from my personal wiki where I removed almost all the buttons. You can figure out what the title of your button is by running the following snippet in a javascript console:

for (i in window.toolbar) { console.log(toolbar[i].title)}

Then take the string and append it to the 'blacklist' array in the code.

See also the toolbuttondel plugin for removing toolbar items.

CSS Spritemap

If you need to reduce the number of server requests for downloading micro-icons, you can use the following style fix.

15 icons of the 20 in the /lib/images/toolbar/ folder are used in a constant order and can be combined into a vertical ribbon named spritemap.
1. You can take the finished spritemap here and put it in /lib/images/toolbar/ named as toolbar.png.
CSS used to show a certain point on spritemap.
1. Add the following CSS rules to your local style file /conf/userstyle.less or template's style file /lib/tpl/<name>/css/design.less:

#tool__bar {
	button:nth-of-type(1), button:nth-of-type(2), button:nth-of-type(3), button:nth-of-type(4), button:nth-of-type(5),
	button:nth-of-type(6), button:nth-of-type(7), button:nth-of-type(8), button:nth-of-type(9), button:nth-of-type(10),
	button:nth-of-type(11), button:nth-of-type(12), button:nth-of-type(13), button:nth-of-type(14), button:nth-of-type(15) {
		background: url(/lib/images/toolbar/toolbar.png);
		height: 16px;
		margin: 4px 7px 3px 3px;
		vertical-align: middle;
		width: 16px;
		img {
			display: none;
		}
	}
	button:nth-of-type(1) { background-position: 0 0; }
	button:nth-of-type(2) { background-position: 0 -16px; }
	button:nth-of-type(3) { background-position: 0 -32px; }
	button:nth-of-type(4) { background-position: 0 -48px; }
	button:nth-of-type(5) { background-position: 0 -64px; }
	button:nth-of-type(6) { background-position: 0 -80px; }
	button:nth-of-type(7) { background-position: 0 -96px; }
	button:nth-of-type(8) { background-position: 0 -112px; }
	button:nth-of-type(9) { background-position: 0 -128px; }
	button:nth-of-type(10) { background-position: 0 -144px; }
	button:nth-of-type(11) { background-position: 0 -160px; }
	button:nth-of-type(12) { background-position: 0 -176px; }
	button:nth-of-type(13) { background-position: 0 -192px; }
	button:nth-of-type(14) { background-position: 0 -208px; }
	button:nth-of-type(15) { background-position: 0 -224px; }
}

Maybe one day this fix will be obsolete due to the introduction of spritemap in the Dokuwiki.
см. также https://www.dokuwiki.org/devel:toolbar

xmlrpc

anonymous@undisclosed.example.com (Anonymous) — Wed, 15 Jan 2025 07:29:00 +0000

XML-RPC

XML-RPC is one of the available protocols to access DokuWiki's Remote API.

The API implements the Wiki RPC Interface 2.0 Specifications (web.archive.org) in the wiki.* namespace and adds additional DokuWiki specific calls in the dokuwiki.* namespace.

Plugins can add their own calls to the API using Remote Plugin components.

Note: there is also a JSON-RPC API which provides the same functionality but is based on JSON rather XML.

Get It Working

Set the remote option to enable XML-RPC in the Configuration Settings «Authentication» section
Set the remoteuser option with a mix of comma separated «usernames,groups»
For security reasons it's safer to allow access to the XML-RPC over HTTPS only. DokuWiki's .htaccess.dist contains some rewrite rules to do that.
You might need to install an XML package like php-xml (on debian)

Accessing The XML-RPC Interface

You can access the XML-RPC interface via the following URLs:

http://<your wiki/domain/ip>/lib/exe/xmlrpc.php

https://<your wiki/domain/ip>/lib/exe/xmlrpc.php

Here are some Samples of Clients using the XML-RPC Api to test with

Sample XML Requests

You should use an XML-RPC library instead of hand-crafting your requests.

Here is an example of how to post to the API:

POST /RPC2 HTTP/1.0
User-Agent: Frontier/5.1.2 (WinNT)
Host: betty.userland.com
Content-Type: text/xml
Content-length: 181
 
<?xml version="1.0"?>
<methodCall>
    <methodName>examples.getStateName</methodName>
    <params>
        <param> 
            <value>
                <i4>41</i4>
            </value>
        </param> 
    </params> 
</methodCall>

<?xml version="1.0"?>
<methodCall>
    <methodName>dokuwiki.getVersion</methodName>
</methodCall>

example put page

<?xml version="1.0"?>
<methodCall>
    <methodName>wiki.putPage</methodName>
    <params>
        <param> 
            <value>
                <string>myputpage  
                </string>
            </value>
        </param> 
        <param> 
            <value>
                <string>This is my page content</string>
            </value>
        </param>
        <param> 
            <value>
                <struct>
                    <member>
                        <name>sum</name>
                        <value><string>Spiceworks</string></value>
                    </member>
                    <member>
                        <name>minor</name>
                        <value><boolean>True</boolean></value>
                    </member>
                </struct>
            </value>
        </param> 
    </params> 
</methodCall>

Available Functions

Functions are listed in the following format:

Name	The name of the function
Parameters	A list of parameters to pass to the function
Data	The type of the returned data
Description	Short explanation what the function does
Since	The DokuWiki (and XML-RPC API Version) this function was introduced

dokuwiki.getPagelist

Name	`dokuwiki.getPagelist`
Parameters	(string) namespace, (array) options
Data	(array) list of page items
Description	Lists all pages within a given namespace. The options are passed directly to search_allpages().
Since	2009-03-06 (1)

dokuwiki.getVersion

Name	`dokuwiki.getVersion`
Parameters	-
Data	(string) version number
Description	Returns the DokuWiki version of the remote Wiki.

dokuwiki.getTime

Name	`dokuwiki.getTime`
Parameters	-
Data	(int) timestamp
Description	Returns the current time at the remote wiki server as Unix timestamp.
Since	2009-03-06 (1)

dokuwiki.getXMLRPCAPIVersion

Name	`dokuwiki.getXMLRPCAPIVersion`
Parameters	-
Data	(int) version number
Description	Returns the XML RPC interface version of the remote Wiki. This is DokuWiki implementation specific and independent of the supported standard API version returned by wiki.getRPCVersionSupported.
Since	2009-03-06 (1)

dokuwiki.login

Name	`dokuwiki.login`
Parameters	(string) user, (string) password
Data	(boolean) login successful
Description	Uses the provided credentials to execute a login and will set cookies. This can be used to make authenticated requests afterwards. Your client needs to support cookie handling. Alternatively use HTTP basic auth credentials.
Since	2009-03-06 (1)

dokuwiki.search

Name	`dokuwiki.search`
Parameters	(string) a query string as described on search
Data	(array) associative array with matching pages similar to what is returned by `dokuwiki.getPagelist`, snippets are provided for the first 15 results
Description	Performs a fulltext search.
Since	2010-02-28 (3)

dokuwiki.getTitle

Name	`dokuwiki.getTitle`
Parameters	-
Data	(string) the title of the wiki
Description	Returns the title of the wiki.
Since	2010-04-18 (4)

dokuwiki.appendPage

Name	`dokuwiki.appendPage`
Parameters	(string) pagename, (string) raw Wiki text, (array) attrs Where `attrs` can contain the following: $attrs['sum'] = (string) change summary $attrs['minor'] = (boolean) minor
Data	(boolean)
Description	Appends text to a Wiki Page.
Since	2010-11-20 (5)

dokuwiki.setLocks

Name	`dokuwiki.setLocks`
Parameters	(array) list of two lists of page ids [ 'lock' => [...], 'unlock' => [...] ]
Data	(array) array with 4 lists of pageids [ 'locked' => [...], 'lockfail' => [...], 'unlocked' => [...], 'unlockfail' => [...] ]
Description	Allows you to lock or unlock a whole bunch of pages at once. Useful when you are about to do an operation over multiple pages.
Since	2009-03-06 (1)

dokuwiki.createUser

Name	`dokuwiki.createUser`
Parameters	(array) parameters, where `parameters` can contain: $params = [ 'user' => 'username', 'password' => 'password1', 'name' => 'User Name', 'mail' => 'user@example.com', 'groups' => [ 'user', 'test' ], 'notify' => false ]
Data	(bool) true if the user is created
Description	Create a user. Returns 400 range error codes if input is not accepted.
Since	2022-06-24

dokuwiki.deleteUsers

Name	`dokuwiki.deleteUsers`
Parameters	(array) list of usernames to delete
Data	(bool) true if the users were deleted
Description	Allows you to delete one or more users. Useful to implement GDPR right to be forgotten tools.
Since	2018-05-24

wiki.getRPCVersionSupported

Name	`wiki.getRPCVersionSupported`
Parameters	-
Data	(string) version number
Description	Returns 2 with the supported RPC API version.

wiki.aclCheck

Name	`wiki.aclCheck`
Parameters	(string) pagename
Data	(int) Permissions of given wiki page
Description	Returns the permission of the given wikipage.

wiki.getPage

Name	`wiki.getPage`
Parameters	(string) pagename
Data	(string) raw Wiki text
Description	Returns the raw Wiki text for a page.

wiki.getPageVersion

Name	`wiki.getPageVersion`
Parameters	(string) pagename, (int) Timestamp
Data	(string) raw Wiki text
Description	Returns the raw Wiki text for a specific revision of a Wiki page.

wiki.getPageVersions

Name	`wiki.getPageVersions`
Parameters	(string) pagename, (int) offset
Data	(array) each array item holds the following data: $data['user'] = username $data['ip'] = ip address $data['type'] = type of change $data['sum'] = summary $data['modified'] = modification date as IXR_Date Object $data['version'] = page version as timestamp
Description	Returns the available versions of a Wiki page. The number of pages in the result is controlled via the recent configuration setting. The offset can be used to list earlier versions in the history.

wiki.getPageInfo

Name	`wiki.getPageInfo`
Parameters	(string) pagename
Data	(array) an array containing the following data: $data['name'] = [[:pagename]] $data['lastModified'] = modification date as IXR_Date Object $data['author'] = author of the Wiki page. $data['version'] = page version as timestamp
Description	Returns information about a Wiki page.

wiki.getPageInfoVersion

Name	`wiki.getPageInfoVersion`
Parameters	(string) pagename, (int) timestamp
Data	(array) an array containing the following data: $data['name'] = [[:pagename]] $data['lastModified'] = modification date as UTC timestamp $data['author'] = author of the Wiki page. $data['version'] = page version as timestamp
Description	Returns information about a specific version of a Wiki page.

wiki.getPageHTML

Name	`wiki.getPageHTML`
Parameters	(string) pagename
Data	(string) rendered HTML
Description	Returns the rendered XHTML body of a Wiki page.

wiki.getPageHTMLVersion

Name	`wiki.getPageHTMLVersion`
Parameters	(string) pagename, (int) timestamp
Data	(string) rendered HTML
Description	Returns the rendered HTML of a specific version of a Wiki page.

wiki.putPage

Name	`wiki.putPage`
Parameters	(string) pagename, (string) raw Wiki text, (array) attrs Where `attrs` can contain the following: $attrs['sum'] = (string) change summary $attrs['minor'] = (boolean) minor
Data	(boolean)
Description	Saves a Wiki Page.

wiki.listLinks

Name	`wiki.listLinks`
Parameters	(string) pagename
Data	(array) each array item holds the following data: $data['type'] = local/extern $data['page'] = the wiki page (or the complete URL if extern) $data['href'] = the complete URL
Description	Returns a list of all links contained in a Wiki page.

wiki.getAllPages

Name	`wiki.getAllPages`
Parameters	-
Data	(array) One item for each page, each item containing the following data: $data['id'] = id of the page $data['perms'] = integer denoting the permissions on the page $data['size'] = size in bytes $data['lastModified'] = dateTime object of last modification date
Description	Returns a list of all Wiki pages in the remote Wiki.

wiki.getBackLinks

Name	`wiki.getBackLinks`
Parameters	(string) pagename
Data	(array)
Description	Returns a list of backlinks of a Wiki page.

wiki.getRecentChanges

Name	`wiki.getRecentChanges`
Parameters	(int) timestamp
Data	(array) each array item holds the following data: $data['name'] = page id $data['lastModified'] = modification date as UTC timestamp $data['author'] = author $data['version'] = page version as timestamp
Description	Returns a list of recent changes since given timestamp. As stated in recent_changes: Only the most recent change for each page is listed, regardless of how many times that page was changed.

wiki.getRecentMediaChanges

Name	`wiki.getRecentMediaChanges`
Parameters	(int) timestamp
Data	(array) each array item holds the following data: $data['name'] = media id $data['lastModified'] = modification date as UTC timestamp $data['author'] = author $data['version'] = page version as timestamp $data['perms'] = media permissions $data['size'] = media size in bytes
Description	Returns a list of recent changed media since given timestamp.

wiki.getAttachments

Name	`wiki.getAttachments`
Parameters	(String) namespace, (array) options
Data	(array) each array item holds the following data: $data['id'] = media id $data['file'] = name of the file $data['size'] = size in bytes $data['mtime'] = upload date as a timestamp $data['lastModified'] = modification date as XML-RPC Date object $data['isimg'] = true if file is an image, false otherwise $data['writable'] = true if file is writable, false otherwise $data['perms'] = permissions of file
Description	Returns a list of media files in a given namespace. The options are passed directly to search_media().

wiki.getAttachment

Name	`wiki.getAttachment`
Parameters	(String) id
Data	(string) the data of the file, encoded in base64
Description	Returns the binary data of a media file.

wiki.getAttachmentInfo

Name	`wiki.getAttachmentInfo`
Parameters	(String) id
Data	(array) an array containing the following information about the file: $data['size'] = size in bytes $data['lastModified'] = modification date as XML-RPC Date object
Description	Returns information about a media file.

wiki.putAttachment

Name	`wiki.putAttachment`
Parameters	(String) id, (base64) data, (array) params Available parameters are: $params['ow'] = true if file is to overwrite an already existing media object of the given id.
Data
Description	Uploads a file as a given media id.

wiki.deleteAttachment

Name	`wiki.deleteAttachment`
Parameters	(String) id
Data
Description	Deletes a file. Fails if the file is still referenced from any page in the wiki.

plugin.acl.listAcls

Name	`plugin.acl.listAcls`
Parameters	-
Data	(array) of ACLs {scope, user, permission}'
Description	Get the list of all ACLs.

plugin.acl.addAcl

Name	`plugin.acl.addAcl`
Parameters	(String) scope, (String) username, (int) permission
Data	(boolean) return true if the rule was correctly added
Description	Add an ACL rule. Use `@groupname` instead of `user` to add an ACL rule for a group.

plugin.acl.delAcl

Name	`plugin.acl.delAcl`
Parameters	(String) scope, (String) username
Data	(boolean) return true if the rules were correctly deleted
Description	Delete any ACL rule matching the given scope and user. Use `@groupname` instead of `user` to delete the ACL rules for the group.

Adding methods to the XML-RPC API

Use Remote Plugins to add other methods to the XML-RPC API.

A summary of recent plugins which indicate Remote support:

Name	Description	Remote plugins compatible with last two releases
JSON Data Plugin	Build JSON database inside DokuWiki page and use the data in the page	1	json
struct Plugin	A new structured data plugin	1	struct

∑ 2 plugins matching query

To implement such a plugin please have a look at the remote plugins development documentation.

XML-RPC Error Codes

Since XML-RPC API Version 7 (API Version 7 is since Release Adora Belle (2012-10-13)) useful hierarchical error codes have been introduced. The following error codes can be returned by the XML-RPC Interface:

Italic rows are just categories. Only normal printed rows are returned by the interface.

100 → Page errors
- 110 → Page access errors
  - 111 → User is not allowed to read the requested page
  - 112 → User is not allowed to edit the page
  - 113 → manager permission is required
  - 114 → superuser permission is required
- 120 → Page existence errors
  - 121 → The requested page does not exist
- 130 → Page edit errors
  - 131 → Empty page id
  - 132 → Empty page content
  - 133 → Page is locked
  - 134 → Positive wordblock check
200 → Media errors
- 210 → Media access errors
  - 211 → User is not allowed to read the requested media
  - 212 → User is not allowed to delete media
  - 215 → User is not allowed to list media
- 220 → Media existence errors
  - 221 → The requested media does not exist
- 230 → Media edit errors
  - 231 → Filename not given
  - 232 → File is still referenced
  - 233 → Could not delete file
300 → Search errors
- 310 → Argument errors
  - 311 → The provided value is not a valid timestamp
- 320 → Search result errors
  - 321 → No changes in specified timeframe
400 → User management errors
- 401 invalid user name given
- 402 invalid user name given
- 403 invalid email address given

Additionally there are some server error codes that indicate some kind of server or XML-RPC failure. The codes are the following:

-32600 → Invalid XML-RPC request. Not conforming to specification.
-32601 → Requested method does not exist.
-32602 → Wrong number of parameters or invalid method parameters.
-32603 → Not authorized to call the requested method (No login or invalid login data was given).
-32604 → Forbidden to call the requested method (but a valid login was given).
-32605 → The XML-RPC API has not been enabled in the configuration
-32700 → Parse Error. Request not well formed.
-32800 → Recursive calls to system.multicall are forbidden.
-99999 → Unknown server error.

Sample Clients

A number of clients written in different languages are available.