Roundcubemail devel
view | history | commit | commitdiff
Aleksander Machniak
2012-08-08 2bbc3da52aee81e920e46778d68278bd31f7bb6b
commit | author | age
cc97ea 1 <?php
T 2
3 /*
4  +-----------------------------------------------------------------------+
5  | program/include/rcube_plugin.php                                      |
6  |                                                                       |
e019f2 7  | This file is part of the Roundcube Webmail client                     |
f5e7b3 8  | Copyright (C) 2008-2009, The Roundcube Dev Team                       |
7fe381 9  |                                                                       |
T 10  | Licensed under the GNU General Public License version 3 or            |
11  | any later version with exceptions for skins & plugins.                |
12  | See the README file for a full license statement.                     |
cc97ea 13  |                                                                       |
T 14  | PURPOSE:                                                              |
15  |  Abstract plugins interface/class                                     |
16  |  All plugins need to extend this class                                |
17  +-----------------------------------------------------------------------+
18  | Author: Thomas Bruederli <roundcube@gmail.com>                        |
19  +-----------------------------------------------------------------------+
20 */
21
22 /**
23  * Plugin interface class
24  *
d062db 25  * @package PluginAPI
cc97ea 26  */
T 27 abstract class rcube_plugin
28 {
2cd443 29   /**
A 30    * Class name of the plugin instance
31    *
32    * @var string
33    */
cc97ea 34   public $ID;
5c461b 35
A 36   /**
2cd443 37    * Instance of Plugin API
5c461b 38    *
A 39    * @var rcube_plugin_api
40    */
cc97ea 41   public $api;
2cd443 42
A 43   /**
44    * Regular expression defining task(s) to bind with 
45    *
46    * @var string
47    */
cc97ea 48   public $task;
2cd443 49
A 50   /**
51    * Disables plugin in AJAX requests
52    *
53    * @var boolean
54    */
55   public $noajax = false;
56
57   /**
58    * Disables plugin in framed mode
59    *
60    * @var boolean
61    */
62   public $noframe = false;
63
cc97ea 64   protected $home;
T 65   protected $urlbase;
05a631 66   private $mytask;
cc97ea 67
2cd443 68
cc97ea 69   /**
T 70    * Default constructor.
5c461b 71    *
A 72    * @param rcube_plugin_api $api Plugin API
cc97ea 73    */
T 74   public function __construct($api)
75   {
76     $this->ID = get_class($this);
77     $this->api = $api;
cdf1ae 78     $this->home = $api->dir . $this->ID;
cc97ea 79     $this->urlbase = $api->url . $this->ID . '/';
T 80   }
479af9 81
cc97ea 82   /**
T 83    * Initialization method, needs to be implemented by the plugin itself
84    */
85   abstract function init();
0501b6 86
T 87
88   /**
89    * Attempt to load the given plugin which is required for the current plugin
90    *
91    * @param string Plugin name
92    * @return boolean True on success, false on failure
93    */
94   public function require_plugin($plugin_name)
95   {
96     return $this->api->load_plugin($plugin_name);
97   }
98
99
c73b19 100   /**
T 101    * Load local config file from plugins directory.
102    * The loaded values are patched over the global configuration.
103    *
5c461b 104    * @param string $fname Config file name relative to the plugin's folder
029c2f 105    * @return boolean True on success, false on failure
c73b19 106    */
T 107   public function load_config($fname = 'config.inc.php')
108   {
109     $fpath = $this->home.'/'.$fname;
be98df 110     $rcube = rcube::get_instance();
A 111     if (is_file($fpath) && !$rcube->config->load_from_file($fpath)) {
0c2596 112       rcube::raise_error(array(
A 113         'code' => 527, 'type' => 'php',
10eedb 114         'file' => __FILE__, 'line' => __LINE__,
A 115         'message' => "Failed to load config from $fpath"), true, false);
029c2f 116       return false;
T 117     }
479af9 118
029c2f 119     return true;
c73b19 120   }
cc97ea 121
T 122   /**
123    * Register a callback function for a specific (server-side) hook
124    *
5c461b 125    * @param string $hook Hook name
A 126    * @param mixed  $callback Callback function as string or array with object reference and method name
cc97ea 127    */
T 128   public function add_hook($hook, $callback)
129   {
130     $this->api->register_hook($hook, $callback);
131   }
479af9 132
A 133   /**
134    * Unregister a callback function for a specific (server-side) hook.
135    *
136    * @param string $hook Hook name
137    * @param mixed  $callback Callback function as string or array with object reference and method name
138    */
139   public function remove_hook($hook, $callback)
140   {
141     $this->api->unregister_hook($hook, $callback);
142   }
143
cc97ea 144   /**
T 145    * Load localized texts from the plugins dir
146    *
5c461b 147    * @param string $dir Directory to search in
A 148    * @param mixed  $add2client Make texts also available on the client (array with list or true for all)
cc97ea 149    */
T 150   public function add_texts($dir, $add2client = false)
151   {
152     $domain = $this->ID;
59041f 153     $lang   = $_SESSION['language'];
AM 154     $langs  = array_unique(array('en_US', $lang));
cc97ea 155     $locdir = slashify(realpath(slashify($this->home) . $dir));
59041f 156     $texts  = array();
AM 157
158     // Language aliases used to find localization in similar lang, see below
159     $aliases = array(
160         'de_CH' => 'de_DE',
161         'es_AR' => 'es_ES',
162         'fa_AF' => 'fa_IR',
163         'nl_BE' => 'nl_NL',
164         'pt_BR' => 'pt_PT',
165         'zh_CN' => 'zh_TW',
166     );
7c9850 167
A 168     // use buffering to handle empty lines/spaces after closing PHP tag
169     ob_start();
170
59041f 171     foreach ($langs as $lng) {
aecadc 172       $fpath = $locdir . $lng . '.inc';
A 173       if (is_file($fpath) && is_readable($fpath)) {
59041f 174         include $fpath;
aecadc 175         $texts = (array)$labels + (array)$messages + (array)$texts;
A 176       }
59041f 177       else if ($lng != 'en_US') {
AM 178         // Find localization in similar language (#1488401)
179         $alias = null;
180         if (!empty($aliases[$lng])) {
181           $alias = $aliases[$lng];
182         }
183         else if ($key = array_search($lng, $aliases)) {
184           $alias = $key;
185         }
186
187         if (!empty($alias)) {
188           $fpath = $locdir . $alias . '.inc';
189           if (is_file($fpath) && is_readable($fpath)) {
190             include $fpath;
191             $texts = (array)$labels + (array)$messages + (array)$texts;
192           }
193         }
194       }
cc97ea 195     }
T 196
7c9850 197     ob_end_clean();
A 198
cc97ea 199     // prepend domain to text keys and add to the application texts repository
T 200     if (!empty($texts)) {
201       $add = array();
202       foreach ($texts as $key => $value)
203         $add[$domain.'.'.$key] = $value;
204
be98df 205       $rcmail = rcmail::get_instance();
cc97ea 206       $rcmail->load_language($lang, $add);
479af9 207
cc97ea 208       // add labels to client
T 209       if ($add2client) {
210         $js_labels = is_array($add2client) ? array_map(array($this, 'label_map_callback'), $add2client) : array_keys($add);
211         $rcmail->output->add_label($js_labels);
212       }
213     }
214   }
479af9 215
cc97ea 216   /**
T 217    * Wrapper for rcmail::gettext() adding the plugin ID as domain
218    *
5c461b 219    * @param string $p Message identifier
cc97ea 220    * @return string Localized text
T 221    * @see rcmail::gettext()
222    */
1c932d 223   public function gettext($p)
cc97ea 224   {
0c2596 225     return rcube::get_instance()->gettext($p, $this->ID);
cc97ea 226   }
1c932d 227
T 228   /**
229    * Register this plugin to be responsible for a specific task
230    *
5c461b 231    * @param string $task Task name (only characters [a-z0-9_.-] are allowed)
1c932d 232    */
T 233   public function register_task($task)
234   {
05a631 235     if ($this->api->register_task($task, $this->ID))
T 236       $this->mytask = $task;
1c932d 237   }
T 238
cc97ea 239   /**
T 240     * Register a handler for a specific client-request action
241     *
242     * The callback will be executed upon a request like /?_task=mail&_action=plugin.myaction
243     *
5c461b 244     * @param string $action  Action name (should be unique)
A 245     * @param mixed $callback Callback function as string or array with object reference and method name
cc97ea 246    */
T 247   public function register_action($action, $callback)
248   {
05a631 249     $this->api->register_action($action, $this->ID, $callback, $this->mytask);
cc97ea 250   }
T 251
252   /**
253    * Register a handler function for a template object
254    *
255    * When parsing a template for display, tags like <roundcube:object name="plugin.myobject" />
256    * will be replaced by the return value if the registered callback function.
257    *
5c461b 258    * @param string $name Object name (should be unique and start with 'plugin.')
A 259    * @param mixed  $callback Callback function as string or array with object reference and method name
cc97ea 260    */
T 261   public function register_handler($name, $callback)
262   {
263     $this->api->register_handler($name, $this->ID, $callback);
264   }
265
266   /**
267    * Make this javascipt file available on the client
268    *
5c461b 269    * @param string $fn File path; absolute or relative to the plugin directory
cc97ea 270    */
T 271   public function include_script($fn)
272   {
eb6f19 273     $this->api->include_script($this->resource_url($fn));
cc97ea 274   }
T 275
276   /**
277    * Make this stylesheet available on the client
278    *
5c461b 279    * @param string $fn File path; absolute or relative to the plugin directory
cc97ea 280    */
T 281   public function include_stylesheet($fn)
282   {
eb6f19 283     $this->api->include_stylesheet($this->resource_url($fn));
cc97ea 284   }
479af9 285
cc97ea 286   /**
T 287    * Append a button to a certain container
288    *
5c461b 289    * @param array $p Hash array with named parameters (as used in skin templates)
A 290    * @param string $container Container name where the buttons should be added to
cc97ea 291    * @see rcube_remplate::button()
T 292    */
293   public function add_button($p, $container)
294   {
295     if ($this->api->output->type == 'html') {
296       // fix relative paths
297       foreach (array('imagepas', 'imageact', 'imagesel') as $key)
298         if ($p[$key])
eb6f19 299           $p[$key] = $this->api->url . $this->resource_url($p[$key]);
479af9 300
cc97ea 301       $this->api->add_content($this->api->output->button($p), $container);
T 302     }
303   }
479af9 304
24e219 305   /**
T 306    * Generate an absolute URL to the given resource within the current
307    * plugin directory
308    *
5c461b 309    * @param string $fn The file name
24e219 310    * @return string Absolute URL to the given resource
T 311    */
312   public function url($fn)
313   {
314       return $this->api->url . $this->resource_url($fn);
315   }
cc97ea 316
T 317   /**
318    * Make the given file name link into the plugin directory
5c461b 319    *
A 320    * @param string $fn Filename
cc97ea 321    */
eb6f19 322   private function resource_url($fn)
cc97ea 323   {
23a2ee 324     if ($fn[0] != '/' && !preg_match('|^https?://|i', $fn))
cc97ea 325       return $this->ID . '/' . $fn;
T 326     else
327       return $fn;
328   }
715a1b 329
01acca 330   /**
T 331    * Provide path to the currently selected skin folder within the plugin directory
332    * with a fallback to the default skin folder.
333    *
334    * @return string Skin path relative to plugins directory
335    */
715a1b 336   public function local_skin_path()
01acca 337   {
0c2596 338     $rcmail = rcube::get_instance();
9f1652 339     foreach (array($rcmail->config->get('skin'),'default') as $skin) {
TB 340       $skin_path = 'skins/' . $skin;
341       if (is_dir(realpath(slashify($this->home) . $skin_path)))
342         break;
343     }
344
01acca 345     return $skin_path;
T 346   }
cc97ea 347
T 348   /**
349    * Callback function for array_map
5c461b 350    *
A 351    * @param string $key Array key.
352    * @return string
cc97ea 353    */
T 354   private function label_map_callback($key)
355   {
356     return $this->ID.'.'.$key;
357   }
358
359 }