| 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 | |
| A | 8 | | Copyright (C) 2008-2009, Roundcube Dev. - Switzerland | |
| 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 | { | |
| 29 | public $ID; | |
| 30 | public $api; | |
| 31 | public $task; | |
| 32 | protected $home; | |
| 33 | protected $urlbase; | |
| 05a631 | 34 | private $mytask; |
| cc97ea | 35 | |
| T | 36 | /** |
| 37 | * Default constructor. | |
| 38 | */ | |
| 39 | public function __construct($api) | |
| 40 | { | |
| 41 | $this->ID = get_class($this); | |
| 42 | $this->api = $api; | |
| 43 | $this->home = $api->dir . DIRECTORY_SEPARATOR . $this->ID; | |
| 44 | $this->urlbase = $api->url . $this->ID . '/'; | |
| 45 | } | |
| 46 | ||
| 47 | /** | |
| 48 | * Initialization method, needs to be implemented by the plugin itself | |
| 49 | */ | |
| 50 | abstract function init(); | |
| c73b19 | 51 | |
| T | 52 | /** |
| 53 | * Load local config file from plugins directory. | |
| 54 | * The loaded values are patched over the global configuration. | |
| 55 | * | |
| 56 | * @param string Config file name relative to the plugin's folder | |
| 029c2f | 57 | * @return boolean True on success, false on failure |
| c73b19 | 58 | */ |
| T | 59 | public function load_config($fname = 'config.inc.php') |
| 60 | { | |
| 61 | $fpath = $this->home.'/'.$fname; | |
| 62 | $rcmail = rcmail::get_instance(); | |
| b545d3 | 63 | if (is_file($fpath) && !$rcmail->config->load_from_file($fpath)) { |
| 10eedb | 64 | raise_error(array('code' => 527, 'type' => 'php', |
| A | 65 | 'file' => __FILE__, 'line' => __LINE__, |
| 66 | 'message' => "Failed to load config from $fpath"), true, false); | |
| 029c2f | 67 | return false; |
| T | 68 | } |
| 69 | ||
| 70 | return true; | |
| c73b19 | 71 | } |
| cc97ea | 72 | |
| T | 73 | /** |
| 74 | * Register a callback function for a specific (server-side) hook | |
| 75 | * | |
| 76 | * @param string Hook name | |
| 77 | * @param mixed Callback function as string or array with object reference and method name | |
| 78 | */ | |
| 79 | public function add_hook($hook, $callback) | |
| 80 | { | |
| 81 | $this->api->register_hook($hook, $callback); | |
| 82 | } | |
| 83 | ||
| 84 | /** | |
| 85 | * Load localized texts from the plugins dir | |
| 86 | * | |
| 87 | * @param string Directory to search in | |
| 88 | * @param mixed Make texts also available on the client (array with list or true for all) | |
| 89 | */ | |
| 90 | public function add_texts($dir, $add2client = false) | |
| 91 | { | |
| 92 | $domain = $this->ID; | |
| 93 | ||
| 94 | $lang = $_SESSION['language']; | |
| 95 | $locdir = slashify(realpath(slashify($this->home) . $dir)); | |
| 96 | $texts = array(); | |
| 97 | ||
| 98 | foreach (array('en_US', $lang) as $lng) { | |
| 99 | @include($locdir . $lng . '.inc'); | |
| 100 | $texts = (array)$labels + (array)$messages + (array)$texts; | |
| 101 | } | |
| 102 | ||
| 103 | // prepend domain to text keys and add to the application texts repository | |
| 104 | if (!empty($texts)) { | |
| 105 | $add = array(); | |
| 106 | foreach ($texts as $key => $value) | |
| 107 | $add[$domain.'.'.$key] = $value; | |
| 108 | ||
| 109 | $rcmail = rcmail::get_instance(); | |
| 110 | $rcmail->load_language($lang, $add); | |
| 111 | ||
| 112 | // add labels to client | |
| 113 | if ($add2client) { | |
| 114 | $js_labels = is_array($add2client) ? array_map(array($this, 'label_map_callback'), $add2client) : array_keys($add); | |
| 115 | $rcmail->output->add_label($js_labels); | |
| 116 | } | |
| 117 | } | |
| 118 | } | |
| 119 | ||
| 120 | /** | |
| 121 | * Wrapper for rcmail::gettext() adding the plugin ID as domain | |
| 122 | * | |
| 123 | * @return string Localized text | |
| 124 | * @see rcmail::gettext() | |
| 125 | */ | |
| 1c932d | 126 | public function gettext($p) |
| cc97ea | 127 | { |
| T | 128 | return rcmail::get_instance()->gettext($p, $this->ID); |
| 129 | } | |
| 1c932d | 130 | |
| T | 131 | /** |
| 132 | * Register this plugin to be responsible for a specific task | |
| 133 | * | |
| 134 | * @param string Task name (only characters [a-z0-9_.-] are allowed) | |
| 135 | */ | |
| 136 | public function register_task($task) | |
| 137 | { | |
| 05a631 | 138 | if ($this->api->register_task($task, $this->ID)) |
| T | 139 | $this->mytask = $task; |
| 1c932d | 140 | } |
| T | 141 | |
| cc97ea | 142 | /** |
| T | 143 | * Register a handler for a specific client-request action |
| 144 | * | |
| 145 | * The callback will be executed upon a request like /?_task=mail&_action=plugin.myaction | |
| 146 | * | |
| 147 | * @param string Action name (should be unique) | |
| 148 | * @param mixed Callback function as string or array with object reference and method name | |
| 149 | */ | |
| 150 | public function register_action($action, $callback) | |
| 151 | { | |
| 05a631 | 152 | $this->api->register_action($action, $this->ID, $callback, $this->mytask); |
| cc97ea | 153 | } |
| T | 154 | |
| 155 | /** | |
| 156 | * Register a handler function for a template object | |
| 157 | * | |
| 158 | * When parsing a template for display, tags like <roundcube:object name="plugin.myobject" /> | |
| 159 | * will be replaced by the return value if the registered callback function. | |
| 160 | * | |
| 161 | * @param string Object name (should be unique and start with 'plugin.') | |
| 162 | * @param mixed Callback function as string or array with object reference and method name | |
| 163 | */ | |
| 164 | public function register_handler($name, $callback) | |
| 165 | { | |
| 166 | $this->api->register_handler($name, $this->ID, $callback); | |
| 167 | } | |
| 168 | ||
| 169 | /** | |
| 170 | * Make this javascipt file available on the client | |
| 171 | * | |
| 172 | * @param string File path; absolute or relative to the plugin directory | |
| 173 | */ | |
| 174 | public function include_script($fn) | |
| 175 | { | |
| eb6f19 | 176 | $this->api->include_script($this->resource_url($fn)); |
| cc97ea | 177 | } |
| T | 178 | |
| 179 | /** | |
| 180 | * Make this stylesheet available on the client | |
| 181 | * | |
| 182 | * @param string File path; absolute or relative to the plugin directory | |
| 183 | */ | |
| 184 | public function include_stylesheet($fn) | |
| 185 | { | |
| eb6f19 | 186 | $this->api->include_stylesheet($this->resource_url($fn)); |
| cc97ea | 187 | } |
| T | 188 | |
| 189 | /** | |
| 190 | * Append a button to a certain container | |
| 191 | * | |
| 192 | * @param array Hash array with named parameters (as used in skin templates) | |
| 193 | * @param string Container name where the buttons should be added to | |
| 194 | * @see rcube_remplate::button() | |
| 195 | */ | |
| 196 | public function add_button($p, $container) | |
| 197 | { | |
| 198 | if ($this->api->output->type == 'html') { | |
| 199 | // fix relative paths | |
| 200 | foreach (array('imagepas', 'imageact', 'imagesel') as $key) | |
| 201 | if ($p[$key]) | |
| eb6f19 | 202 | $p[$key] = $this->api->url . $this->resource_url($p[$key]); |
| cc97ea | 203 | |
| T | 204 | $this->api->add_content($this->api->output->button($p), $container); |
| 205 | } | |
| 206 | } | |
| 24e219 | 207 | |
| T | 208 | /** |
| 209 | * Generate an absolute URL to the given resource within the current | |
| 210 | * plugin directory | |
| 211 | * | |
| 212 | * @param string The file name | |
| 213 | * @return string Absolute URL to the given resource | |
| 214 | */ | |
| 215 | public function url($fn) | |
| 216 | { | |
| 217 | return $this->api->url . $this->resource_url($fn); | |
| 218 | } | |
| cc97ea | 219 | |
| T | 220 | /** |
| 221 | * Make the given file name link into the plugin directory | |
| 222 | */ | |
| eb6f19 | 223 | private function resource_url($fn) |
| cc97ea | 224 | { |
| 23a2ee | 225 | if ($fn[0] != '/' && !preg_match('|^https?://|i', $fn)) |
| cc97ea | 226 | return $this->ID . '/' . $fn; |
| T | 227 | else |
| 228 | return $fn; | |
| 229 | } | |
| 01acca | 230 | |
| T | 231 | /** |
| 232 | * Provide path to the currently selected skin folder within the plugin directory | |
| 233 | * with a fallback to the default skin folder. | |
| 234 | * | |
| 235 | * @return string Skin path relative to plugins directory | |
| 236 | */ | |
| 237 | protected function local_skin_path() | |
| 238 | { | |
| 239 | $skin_path = 'skins/'.$this->api->output->config['skin']; | |
| 240 | if (!is_dir(realpath(slashify($this->home) . $skin_path))) | |
| 241 | $skin_path = 'skins/default'; | |
| 242 | return $skin_path; | |
| 243 | } | |
| cc97ea | 244 | |
| T | 245 | /** |
| 246 | * Callback function for array_map | |
| 247 | */ | |
| 248 | private function label_map_callback($key) | |
| 249 | { | |
| 250 | return $this->ID.'.'.$key; | |
| 251 | } | |
| 252 | ||
| 253 | ||
| 254 | } | |
| 255 | ||
