aboutsummaryrefslogtreecommitdiff
path: root/vendors/dokuwiki/inc/plugin.php
blob: 3645347399904d6f04bee7351ffc0193dda91791 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
<?php
/**
 * DokuWiki Plugin base class
 *
 * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
 * @author     Christopher Smith <chris@jalakai.co.uk>
 */

/**
 * Do not inherit directly from this class, instead inherit from the specialized
 * ones in lib/plugin
 */
class DokuWiki_Plugin {

    var $localised = false;        // set to true by setupLocale() after loading language dependent strings
    var $lang = array();           // array to hold language dependent strings, best accessed via ->getLang()
    var $configloaded = false;     // set to true by loadConfig() after loading plugin configuration variables
    var $conf = array();           // array to hold plugin settings, best accessed via ->getConf()

    /**
     * General Info
     *
     * Needs to return a associative array with the following values:
     *
     * author - Author of the plugin
     * email  - Email address to contact the author
     * date   - Last modified date of the plugin in YYYY-MM-DD format
     * name   - Name of the plugin
     * desc   - Short description of the plugin (Text only)
     * url    - Website with more information on the plugin (eg. syntax description)
     */
    function getInfo(){
        $parts = explode('_',get_class($this));
        $info  = DOKU_PLUGIN.'/'.$parts[2].'/plugin.info.txt';
        if(@file_exists($info)) return confToHash($info);
        trigger_error('getInfo() not implemented in '.get_class($this).' and '.$info.' not found', E_USER_WARNING);
    }

    // plugin introspection methods
    // extract from class name, format = <plugin type>_plugin_<name>[_<component name>]
    function getPluginType() {
        list($t) = explode('_', get_class($this), 2);
        return $t;
    }
    function getPluginName() {
        list($t, $p, $n) = explode('_', get_class($this), 4);
        return $n;
    }
    function getPluginComponent() {
        list($t, $p, $n, $c) = explode('_', get_class($this), 4);
        return (isset($c)?$c:'');
    }

    // localisation methods
    /**
     * getLang($id)
     * use this function to access plugin language strings
     * to try to minimise unnecessary loading of the strings when the plugin doesn't require them
     * e.g. when info plugin is querying plugins for information about themselves.
     *
     * @param   $id     id of the string to be retrieved
     * @return  string  string in appropriate language or english if not available
     */
    function getLang($id) {
        if (!$this->localised) $this->setupLocale();

        return (isset($this->lang[$id]) ? $this->lang[$id] : '');
    }

    /**
     * locale_xhtml($id)
     *
     * retrieve a language dependent file and pass to xhtml renderer for display
     * plugin equivalent of p_locale_xhtml()
     *
     * @param   $id     id of language dependent wiki page
     * @return  string  parsed contents of the wiki page in xhtml format
     */
    function locale_xhtml($id) {
        return p_cached_output($this->localFN($id));
    }

    /**
     * localFN($id)
     * prepends appropriate path for a language dependent filename
     * plugin equivalent of localFN()
     */
    function localFN($id) {
        global $conf;
        $plugin = $this->getPluginName();
        $file = DOKU_PLUGIN.$plugin.'/lang/'.$conf['lang'].'/'.$id.'.txt';
        if(!@file_exists($file)){
            //fall back to english
            $file = DOKU_PLUGIN.$plugin.'/lang/en/'.$id.'.txt';
        }
        return $file;
    }

    /**
     *  setupLocale()
     *  reads all the plugins language dependent strings into $this->lang
     *  this function is automatically called by getLang()
     */
    function setupLocale() {
        if ($this->localised) return;

        global $conf;            // definitely don't invoke "global $lang"
        $path = DOKU_PLUGIN.$this->getPluginName().'/lang/';

        $lang = array();

        // don't include once, in case several plugin components require the same language file
        @include($path.'en/lang.php');
        if ($conf['lang'] != 'en') @include($path.$conf['lang'].'/lang.php');

        $this->lang = $lang;
        $this->localised = true;
    }

    // configuration methods
    /**
     * getConf($setting)
     *
     * use this function to access plugin configuration variables
     */
    function getConf($setting){

        if (!$this->configloaded){ $this->loadConfig(); }

        return $this->conf[$setting];
    }

    /**
     * loadConfig()
     * merges the plugin's default settings with any local settings
     * this function is automatically called through getConf()
     */
    function loadConfig(){
        global $conf;

        $defaults = $this->readDefaultSettings();
        $plugin = $this->getPluginName();

        foreach ($defaults as $key => $value) {
            if (isset($conf['plugin'][$plugin][$key])) continue;
            $conf['plugin'][$plugin][$key] = $value;
        }

        $this->configloaded = true;
        $this->conf =& $conf['plugin'][$plugin];
    }

    /**
     * read the plugin's default configuration settings from conf/default.php
     * this function is automatically called through getConf()
     *
     * @return    array    setting => value
     */
    function readDefaultSettings() {

        $path = DOKU_PLUGIN.$this->getPluginName().'/conf/';
        $conf = array();

        if (@file_exists($path.'default.php')) {
            include($path.'default.php');
        }

        return $conf;
    }

    /**
     * Loads a given helper plugin (if enabled)
     *
     * @author  Esther Brunner <wikidesign@gmail.com>
     *
     * @param   $name   name of plugin to load
     * @param   $msg    message to display in case the plugin is not available
     *
     * @return  object  helper plugin object
     */
    function loadHelper($name, $msg){
        if (!plugin_isdisabled($name)){
            $obj =& plugin_load('helper',$name);
        }else{
            $obj = null;
        }
        if (is_null($obj) && $msg) msg("Helper plugin $name is not available or invalid.",-1);
        return $obj;
    }

    // standard functions for outputing email addresses and links
    // use these to avoid having to duplicate code to produce links in line with the installation configuration

    /**
     * email
     * standardised function to generate an email link according to obfuscation settings
     */
    function email($email, $name='', $class='', $more='') {
        if (!$email) return $name;
        $email = obfuscate($email);
        if (!$name) $name = $email;
        $class = "class='".($class ? $class : 'mail')."'";
        return "<a href='mailto:$email' $class title='$email' $more>$name</a>";
    }

    /**
     * external_link
     * standardised function to generate an external link according to conf settings
     */
    function external_link($link, $title='', $class='', $target='', $more='') {
        global $conf;

        $link = htmlentities($link);
        if (!$title) $title = $link;
        if (!$target) $target = $conf['target']['extern'];
        if ($conf['relnofollow']) $more .= ' rel="nofollow"';

        if ($class) $class = " class='$class'";
        if ($target) $target = " target='$target'";
        if ($more) $more = " ".trim($more);

        return "<a href='$link'$class$target$more>$title</a>";
    }

    /**
     * output text string through the parser, allows dokuwiki markup to be used
     * very ineffecient for small pieces of data - try not to use
     */
    function render($text, $format='xhtml') {
        return p_render($format, p_get_instructions($text),$info);
    }

    /**
     * Allow the plugin to prevent DokuWiki creating a second instance of itself
     *
     * @return bool   true if the plugin can not be instantiated more than once
     */
    function isSingleton() {
        return false;
    }

    // deprecated functions
    function plugin_localFN($id) { return $this->localFN($id); }
    function plugin_locale_xhtml($id) { return $this->locale_xhtml($id); }
    function plugin_email($e, $n='', $c='', $m='') { return $this->email($e, $n, $c, $m); }
    function plugin_link($l, $t='', $c='', $to='', $m='') { return $this->external_link($l, $t, $c, $to, $m); }
    function plugin_render($t, $f='xhtml') { return $this->render($t, $f); }
}