DokuWiki

It's better when it's simple

User Tools

Site Tools


devel:plugin_file_structure

Plugin File Structure

There are two structures for the files of a DokuWiki plugin class. The structure chosen determines the name for the plugin class(es).

Definitions:

  • <pluginname> – simple and unique name, also name of plugin directory
  • <plugin type> – characterizes the function of plugin e.g. syntax, auth, action…
  • <plugin component> – needed when plugin has more components of one type

Class definition:

  1. Single component of one plugin type:
    <dokuwiki>/lib/plugins/<plugin name>/<plugin type>.php
    the plugin class name will be <plugin type>_plugin_<plugin name>
    e.g. file                  name type          class
         <dokuwiki>/lib/plugins/acl/admin.php  => admin_plugin_acl
  2. More components of one plugin type:
    <dokuwiki>/lib/plugins/<plugin name>/<plugin type>/<filename>.php
    This structure allows several plugin classes of one plugin type within one plugin.
    The class names will be <plugin type>_plugin_<plugin name>_<filename>.
    e.g. file                   name type   component     class
         <dokuwiki>/lib/plugins/code/syntax/code.php   => syntax_plugin_code_code
         <dokuwiki>/lib/plugins/code/syntax/file.php   => syntax_plugin_code_file
    or
         <dokuwiki>/lib/plugins/code/auth/file.php     => auth_plugin_code_file
         <dokuwiki>/lib/plugins/code/auth/file.php     => auth_plugin_code_file

    If you are creating multiple syntax components, their mode name in the connectTo() method must also have _<filename> appended, e.g.: plugin_code_code and plugin_code_file.

Name conventions of plugin name

  • an _ (underscore) is a reserved character and cannot be used in the <pluginname>
  • valid <pluginname> should only contain the characters a-z and 0-9
  • two different plugins with the same name are mutually exclusive and inherently incompatible.

Combining of plugin types and functions

A plugin may contain several different plugins types as well as several different plugin classes(components) of each type.

In addition, a plugin can (optionally) take advantage of other built-in facilities to have its styles, JavaScript, localisation, and configuration included in DokuWiki. See also common plugin functions.

File Structure

All paths and files are relative to the plugin root directory.

  • <dokuwiki>/lib/plugins/<pluginname>/
    • style.cssCSS styles for the plugin
    • print.css – print CSS styles for the plugin
    • script.jsJavaScript used by the plugin
    • plugin.info.txt – A text file with plugin informations required!
    • deleted.files– (optional) A text file that lists files that are deleted if the plugin is updated.
    • lang/
      • <language>/lang.phpLanguage strings (accessible via $this->getLang())
      • <language>/settings.php – localised strings used in the Configuration Manager
      • <language>/<filename>.txt – localised text including DokuWiki markup (accessible via $this->locale_xhtml())
    • conf/
      • default.phpDefault settings for the plugin settings (accessible via $this->getConf(), saved local settings are stored in DokuWiki's global <dokuwiki>/conf/local.php)
      • metadata.phpconfiguration metadata describing properties of the settings for use by Configuration Manager

Use Plugin Wizard

The simplest and recommended way to create the initial file system structure for new plugin is to use the DokuWiki Plugin Wizard.

CSS Styles

Please refer to CSS stylesheets for plugins for more info which style files you can use and how. Only the CSS style files listed below are available, all your CSS should be merged into one of these files, including or referring other style files is not available.

Possible files, all optional:

  • <dokuwiki>/lib/plugins/<pluginname>/
    • style.cssCSS styles for the plugin. Usually only used css file.
    • print.css – print CSS styles for the plugin
    • all.css – Applied in all display modes
    • feed.css – Applied when displaying the feed

Since Binky, DokuWiki supports LESS parsing, you may use *.less files as well.

JavaScript

Please read javascript for javascript loading and coding guidelines. Javascript files can contain DokuWiki specific syntax for including other javascript files.

Possible files, all optional:

See also FAQ about jQuery

Don't include Extension manager files

There can be also auto-generated files around from the extension manager, don't include these in your final plugin download package:

  • <dokuwiki>/lib/plugins/<pluginname>/
    • disabled – This 0 byte file indicates the plugin is disabled.
    • manager.dat – Stores extension manager data e.g. download url and installation date

See also

devel/plugin_file_structure.txt · Last modified: 2023-04-13 11:47 by hsins

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki