Roundcubemail devel
view | history | commit | commitdiff
thomascube
2011-04-15 569f8306db3f61831795f15793b1c8f749f94779
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                       |
cc97ea 9  | Licensed under the GNU GPL                                            |
T 10  |                                                                       |
11  | PURPOSE:                                                              |
12  |  Abstract plugins interface/class                                     |
13  |  All plugins need to extend this class                                |
14  +-----------------------------------------------------------------------+
15  | Author: Thomas Bruederli <roundcube@gmail.com>                        |
16  +-----------------------------------------------------------------------+
17
1d786c 18  $Id$
cc97ea 19
T 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   }
81   
82   /**
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;
110     $rcmail = rcmail::get_instance();
b545d3 111     if (is_file($fpath) && !$rcmail->config->load_from_file($fpath)) {
10eedb 112       raise_error(array('code' => 527, 'type' => 'php',
A 113         'file' => __FILE__, 'line' => __LINE__,
114         'message' => "Failed to load config from $fpath"), true, false);
029c2f 115       return false;
T 116     }
117     
118     return true;
c73b19 119   }
cc97ea 120
T 121   /**
122    * Register a callback function for a specific (server-side) hook
123    *
5c461b 124    * @param string $hook Hook name
A 125    * @param mixed  $callback Callback function as string or array with object reference and method name
cc97ea 126    */
T 127   public function add_hook($hook, $callback)
128   {
129     $this->api->register_hook($hook, $callback);
130   }
131   
132   /**
133    * Load localized texts from the plugins dir
134    *
5c461b 135    * @param string $dir Directory to search in
A 136    * @param mixed  $add2client Make texts also available on the client (array with list or true for all)
cc97ea 137    */
T 138   public function add_texts($dir, $add2client = false)
139   {
140     $domain = $this->ID;
141     
142     $lang = $_SESSION['language'];
143     $locdir = slashify(realpath(slashify($this->home) . $dir));
144     $texts = array();
7c9850 145
A 146     // use buffering to handle empty lines/spaces after closing PHP tag
147     ob_start();
148
cc97ea 149     foreach (array('en_US', $lang) as $lng) {
T 150       @include($locdir . $lng . '.inc');
151       $texts = (array)$labels + (array)$messages + (array)$texts;
152     }
153
7c9850 154     ob_end_clean();
A 155
cc97ea 156     // prepend domain to text keys and add to the application texts repository
T 157     if (!empty($texts)) {
158       $add = array();
159       foreach ($texts as $key => $value)
160         $add[$domain.'.'.$key] = $value;
161
162       $rcmail = rcmail::get_instance();
163       $rcmail->load_language($lang, $add);
164       
165       // add labels to client
166       if ($add2client) {
167         $js_labels = is_array($add2client) ? array_map(array($this, 'label_map_callback'), $add2client) : array_keys($add);
168         $rcmail->output->add_label($js_labels);
169       }
170     }
171   }
172   
173   /**
174    * Wrapper for rcmail::gettext() adding the plugin ID as domain
175    *
5c461b 176    * @param string $p Message identifier
cc97ea 177    * @return string Localized text
T 178    * @see rcmail::gettext()
179    */
1c932d 180   public function gettext($p)
cc97ea 181   {
T 182     return rcmail::get_instance()->gettext($p, $this->ID);
183   }
1c932d 184
T 185   /**
186    * Register this plugin to be responsible for a specific task
187    *
5c461b 188    * @param string $task Task name (only characters [a-z0-9_.-] are allowed)
1c932d 189    */
T 190   public function register_task($task)
191   {
05a631 192     if ($this->api->register_task($task, $this->ID))
T 193       $this->mytask = $task;
1c932d 194   }
T 195
cc97ea 196   /**
T 197     * Register a handler for a specific client-request action
198     *
199     * The callback will be executed upon a request like /?_task=mail&_action=plugin.myaction
200     *
5c461b 201     * @param string $action  Action name (should be unique)
A 202     * @param mixed $callback Callback function as string or array with object reference and method name
cc97ea 203    */
T 204   public function register_action($action, $callback)
205   {
05a631 206     $this->api->register_action($action, $this->ID, $callback, $this->mytask);
cc97ea 207   }
T 208
209   /**
210    * Register a handler function for a template object
211    *
212    * When parsing a template for display, tags like <roundcube:object name="plugin.myobject" />
213    * will be replaced by the return value if the registered callback function.
214    *
5c461b 215    * @param string $name Object name (should be unique and start with 'plugin.')
A 216    * @param mixed  $callback Callback function as string or array with object reference and method name
cc97ea 217    */
T 218   public function register_handler($name, $callback)
219   {
220     $this->api->register_handler($name, $this->ID, $callback);
221   }
222
223   /**
224    * Make this javascipt file available on the client
225    *
5c461b 226    * @param string $fn File path; absolute or relative to the plugin directory
cc97ea 227    */
T 228   public function include_script($fn)
229   {
eb6f19 230     $this->api->include_script($this->resource_url($fn));
cc97ea 231   }
T 232
233   /**
234    * Make this stylesheet available on the client
235    *
5c461b 236    * @param string $fn File path; absolute or relative to the plugin directory
cc97ea 237    */
T 238   public function include_stylesheet($fn)
239   {
eb6f19 240     $this->api->include_stylesheet($this->resource_url($fn));
cc97ea 241   }
T 242   
243   /**
244    * Append a button to a certain container
245    *
5c461b 246    * @param array $p Hash array with named parameters (as used in skin templates)
A 247    * @param string $container Container name where the buttons should be added to
cc97ea 248    * @see rcube_remplate::button()
T 249    */
250   public function add_button($p, $container)
251   {
252     if ($this->api->output->type == 'html') {
253       // fix relative paths
254       foreach (array('imagepas', 'imageact', 'imagesel') as $key)
255         if ($p[$key])
eb6f19 256           $p[$key] = $this->api->url . $this->resource_url($p[$key]);
cc97ea 257       
T 258       $this->api->add_content($this->api->output->button($p), $container);
259     }
260   }
24e219 261   
T 262   /**
263    * Generate an absolute URL to the given resource within the current
264    * plugin directory
265    *
5c461b 266    * @param string $fn The file name
24e219 267    * @return string Absolute URL to the given resource
T 268    */
269   public function url($fn)
270   {
271       return $this->api->url . $this->resource_url($fn);
272   }
cc97ea 273
T 274   /**
275    * Make the given file name link into the plugin directory
5c461b 276    *
A 277    * @param string $fn Filename
cc97ea 278    */
eb6f19 279   private function resource_url($fn)
cc97ea 280   {
23a2ee 281     if ($fn[0] != '/' && !preg_match('|^https?://|i', $fn))
cc97ea 282       return $this->ID . '/' . $fn;
T 283     else
284       return $fn;
285   }
01acca 286   
T 287   /**
288    * Provide path to the currently selected skin folder within the plugin directory
289    * with a fallback to the default skin folder.
290    *
291    * @return string Skin path relative to plugins directory
292    */
293   protected function local_skin_path()
294   {
1ac543 295       $skin_path = 'skins/'.$this->api->config->get('skin');
01acca 296       if (!is_dir(realpath(slashify($this->home) . $skin_path)))
T 297         $skin_path = 'skins/default';
298     return $skin_path;
299   }
cc97ea 300
T 301   /**
302    * Callback function for array_map
5c461b 303    *
A 304    * @param string $key Array key.
305    * @return string
cc97ea 306    */
T 307   private function label_map_callback($key)
308   {
309     return $this->ID.'.'.$key;
310   }
311
312
313 }
314