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