PluginInterface.php 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162
  1. <?php
  2. namespace dokuwiki\Extension;
  3. /**
  4. * DokuWiki Plugin Interface
  5. *
  6. * Defines the public contract all DokuWiki plugins will adhere to. The actual code
  7. * to do so is defined in dokuwiki\Extension\PluginTrait
  8. *
  9. * @license GPL 2 (http://www.gnu.org/licenses/gpl.html)
  10. * @author Christopher Smith <chris@jalakai.co.uk>
  11. */
  12. interface PluginInterface
  13. {
  14. /**
  15. * General Info
  16. *
  17. * Needs to return a associative array with the following values:
  18. *
  19. * base - the plugin's base name (eg. the directory it needs to be installed in)
  20. * author - Author of the plugin
  21. * email - Email address to contact the author
  22. * date - Last modified date of the plugin in YYYY-MM-DD format
  23. * name - Name of the plugin
  24. * desc - Short description of the plugin (Text only)
  25. * url - Website with more information on the plugin (eg. syntax description)
  26. */
  27. public function getInfo();
  28. /**
  29. * The type of the plugin inferred from the class name
  30. *
  31. * @return string plugin type
  32. */
  33. public function getPluginType();
  34. /**
  35. * The name of the plugin inferred from the class name
  36. *
  37. * @return string plugin name
  38. */
  39. public function getPluginName();
  40. /**
  41. * The component part of the plugin inferred from the class name
  42. *
  43. * @return string component name
  44. */
  45. public function getPluginComponent();
  46. /**
  47. * Access plugin language strings
  48. *
  49. * to try to minimise unnecessary loading of the strings when the plugin doesn't require them
  50. * e.g. when info plugin is querying plugins for information about themselves.
  51. *
  52. * @param string $id id of the string to be retrieved
  53. * @return string in appropriate language or english if not available
  54. */
  55. public function getLang($id);
  56. /**
  57. * retrieve a language dependent file and pass to xhtml renderer for display
  58. * plugin equivalent of p_locale_xhtml()
  59. *
  60. * @param string $id id of language dependent wiki page
  61. * @return string parsed contents of the wiki page in xhtml format
  62. */
  63. public function locale_xhtml($id);
  64. /**
  65. * Prepends appropriate path for a language dependent filename
  66. * plugin equivalent of localFN()
  67. *
  68. * @param string $id id of localization file
  69. * @param string $ext The file extension (usually txt)
  70. * @return string wiki text
  71. */
  72. public function localFN($id, $ext = 'txt');
  73. /**
  74. * Reads all the plugins language dependent strings into $this->lang
  75. * this function is automatically called by getLang()
  76. *
  77. * @todo this could be made protected and be moved to the trait only
  78. */
  79. public function setupLocale();
  80. /**
  81. * use this function to access plugin configuration variables
  82. *
  83. * @param string $setting the setting to access
  84. * @param mixed $notset what to return if the setting is not available
  85. * @return mixed
  86. */
  87. public function getConf($setting, $notset = false);
  88. /**
  89. * merges the plugin's default settings with any local settings
  90. * this function is automatically called through getConf()
  91. *
  92. * @todo this could be made protected and be moved to the trait only
  93. */
  94. public function loadConfig();
  95. /**
  96. * Loads a given helper plugin (if enabled)
  97. *
  98. * @author Esther Brunner <wikidesign@gmail.com>
  99. *
  100. * @param string $name name of plugin to load
  101. * @param bool $msg if a message should be displayed in case the plugin is not available
  102. * @return PluginInterface|null helper plugin object
  103. */
  104. public function loadHelper($name, $msg = true);
  105. /**
  106. * email
  107. * standardised function to generate an email link according to obfuscation settings
  108. *
  109. * @param string $email
  110. * @param string $name
  111. * @param string $class
  112. * @param string $more
  113. * @return string html
  114. */
  115. public function email($email, $name = '', $class = '', $more = '');
  116. /**
  117. * external_link
  118. * standardised function to generate an external link according to conf settings
  119. *
  120. * @param string $link
  121. * @param string $title
  122. * @param string $class
  123. * @param string $target
  124. * @param string $more
  125. * @return string
  126. */
  127. public function external_link($link, $title = '', $class = '', $target = '', $more = '');
  128. /**
  129. * output text string through the parser, allows dokuwiki markup to be used
  130. * very ineffecient for small pieces of data - try not to use
  131. *
  132. * @param string $text wiki markup to parse
  133. * @param string $format output format
  134. * @return null|string
  135. */
  136. public function render_text($text, $format = 'xhtml');
  137. /**
  138. * Allow the plugin to prevent DokuWiki from reusing an instance
  139. *
  140. * @return bool false if the plugin has to be instantiated
  141. */
  142. public function isSingleton();
  143. }