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