| [ Index ] |
PHP Cross Reference of Nucleus CMS v3.51 code documentation |
[Summary view] [Print] [Text view]
1 <?php 2 /* 3 * Nucleus: PHP/MySQL Weblog CMS (http://nucleuscms.org/) 4 * Copyright (C) 2002-2009 The Nucleus Group 5 * 6 * This program is free software; you can redistribute it and/or 7 * modify it under the terms of the GNU General Public License 8 * as published by the Free Software Foundation; either version 2 9 * of the License, or (at your option) any later version. 10 * (see nucleus/documentation/index.html#license for more info) 11 */ 12 /** 13 * This is an (abstract) class of which all Nucleus Plugins must inherit 14 * 15 * for more information on plugins and how to write your own, see the 16 * plugins.html file that is included with the Nucleus documenation 17 * 18 * @license http://nucleuscms.org/license.txt GNU General Public License 19 * @copyright Copyright (C) 2002-2009 The Nucleus Group 20 * @version $Id: PLUGIN.php 1393 2009-07-24 21:06:40Z ftruscot $ 21 */ 22 class NucleusPlugin { 23 24 // these functions _have_ to be redefined in your plugin 25 26 function getName() { return 'Undefined'; } 27 function getAuthor() { return 'Undefined'; } 28 function getURL() { return 'Undefined'; } 29 function getVersion() { return '0.0'; } 30 function getDescription() { return 'Undefined';} 31 32 // these function _may_ be redefined in your plugin 33 34 function getMinNucleusVersion() { return 150; } 35 function getMinNucleusPatchLevel() { return 0; } 36 function getEventList() { return array(); } 37 function getTableList() { return array(); } 38 function hasAdminArea() { return 0; } 39 40 function install() {} 41 function unInstall() {} 42 43 function init() {} 44 45 function doSkinVar($skinType) {} 46 function doTemplateVar(&$item) { 47 $args = func_get_args(); 48 array_shift($args); 49 array_unshift($args, 'template'); 50 call_user_func_array(array(&$this,'doSkinVar'),$args); 51 } 52 function doTemplateCommentsVar(&$item, &$comment) { 53 $args = func_get_args(); 54 array_shift($args); 55 array_shift($args); 56 array_unshift($args, 'template'); 57 call_user_func_array(array(&$this,'doSkinVar'),$args); 58 } 59 function doAction($type) { return _ERROR_PLUGIN_NOSUCHACTION; } 60 function doIf($key,$value) { return false; } 61 function doItemVar (&$item) {} 62 63 /** 64 * Checks if a plugin supports a certain feature. 65 * 66 * @returns 1 if the feature is reported, 0 if not 67 * @param $feature 68 * Name of the feature. See plugin documentation for more info 69 * 'SqlTablePrefix' -> if the plugin uses the sql_table() method to get table names 70 * 'HelpPage' -> if the plugin provides a helppage 71 * 'SqlApi' -> if the plugin uses the complete sql_* api (must also require nucleuscms 3.5) 72 */ 73 function supportsFeature($feature) { 74 return 0; 75 } 76 77 /** 78 * Report a list of plugin that is required to function 79 * 80 * @returns an array of names of plugin, an empty array indicates no dependency 81 */ 82 function getPluginDep() { return array(); } 83 84 // these helper functions should not be redefined in your plugin 85 86 /** 87 * Creates a new option for this plugin 88 * 89 * @param name 90 * A string uniquely identifying your option. (max. length is 20 characters) 91 * @param description 92 * A description that will show up in the nucleus admin area (max. length: 255 characters) 93 * @param type 94 * Either 'text', 'yesno' or 'password' 95 * This info is used when showing 'edit plugin options' screens 96 * @param value 97 * Initial value for the option (max. value length is 128 characters) 98 */ 99 function createOption($name, $desc, $type, $defValue = '', $typeExtras = '') { 100 return $this->_createOption('global', $name, $desc, $type, $defValue, $typeExtras); 101 } 102 function createBlogOption($name, $desc, $type, $defValue = '', $typeExtras = '') { 103 return $this->_createOption('blog', $name, $desc, $type, $defValue, $typeExtras); 104 } 105 function createMemberOption($name, $desc, $type, $defValue = '', $typeExtras = '') { 106 return $this->_createOption('member', $name, $desc, $type, $defValue, $typeExtras); 107 } 108 function createCategoryOption($name, $desc, $type, $defValue = '', $typeExtras = '') { 109 return $this->_createOption('category', $name, $desc, $type, $defValue, $typeExtras); 110 } 111 function createItemOption($name, $desc, $type, $defValue = '', $typeExtras = '') { 112 return $this->_createOption('item', $name, $desc, $type, $defValue, $typeExtras); 113 } 114 115 /** 116 * Removes the option from the database 117 * 118 * Note: Options get erased automatically on plugin uninstall 119 */ 120 function deleteOption($name) { 121 return $this->_deleteOption('global', $name); 122 } 123 function deleteBlogOption($name) { 124 return $this->_deleteOption('blog', $name); 125 } 126 function deleteMemberOption($name) { 127 return $this->_deleteOption('member', $name); 128 } 129 function deleteCategoryOption($name) { 130 return $this->_deleteOption('category', $name); 131 } 132 function deleteItemOption($name) { 133 return $this->_deleteOption('item', $name); 134 } 135 136 /** 137 * Sets the value of an option to something new 138 */ 139 function setOption($name, $value) { 140 return $this->_setOption('global', 0, $name, $value); 141 } 142 function setBlogOption($blogid, $name, $value) { 143 return $this->_setOption('blog', $blogid, $name, $value); 144 } 145 function setMemberOption($memberid, $name, $value) { 146 return $this->_setOption('member', $memberid, $name, $value); 147 } 148 function setCategoryOption($catid, $name, $value) { 149 return $this->_setOption('category', $catid, $name, $value); 150 } 151 function setItemOption($itemid, $name, $value) { 152 return $this->_setOption('item', $itemid, $name, $value); 153 } 154 155 /** 156 * Retrieves the current value for an option 157 */ 158 function getOption($name) 159 { 160 // only request the options the very first time. On subsequent requests 161 // the static collection is used to save SQL queries. 162 if ($this->plugin_options == 0) 163 { 164 $this->plugin_options = array(); 165 $query = sql_query( 166 'SELECT d.oname as name, o.ovalue as value '. 167 'FROM '. 168 sql_table('plugin_option').' o, '. 169 sql_table('plugin_option_desc').' d '. 170 'WHERE d.opid='. intval($this->getID()).' AND d.oid=o.oid' 171 ); 172 while ($row = sql_fetch_object($query)) 173 $this->plugin_options[strtolower($row->name)] = $row->value; 174 } 175 if (isset($this->plugin_options[strtolower($name)])) 176 return $this->plugin_options[strtolower($name)]; 177 else 178 return $this->_getOption('global', 0, $name); 179 } 180 181 function getBlogOption($blogid, $name) { 182 return $this->_getOption('blog', $blogid, $name); 183 } 184 function getMemberOption($memberid, $name) { 185 return $this->_getOption('member', $memberid, $name); 186 } 187 function getCategoryOption($catid, $name) { 188 return $this->_getOption('category', $catid, $name); 189 } 190 function getItemOption($itemid, $name) { 191 return $this->_getOption('item', $itemid, $name); 192 } 193 194 /** 195 * Retrieves an associative array with the option value for each 196 * context id 197 */ 198 function getAllBlogOptions($name) { 199 return $this->_getAllOptions('blog', $name); 200 } 201 function getAllMemberOptions($name) { 202 return $this->_getAllOptions('member', $name); 203 } 204 function getAllCategoryOptions($name) { 205 return $this->_getAllOptions('category', $name); 206 } 207 function getAllItemOptions($name) { 208 return $this->_getAllOptions('item', $name); 209 } 210 211 /** 212 * Retrieves an indexed array with the top (or bottom) of an option 213 * (delegates to _getOptionTop()) 214 */ 215 function getBlogOptionTop($name, $amount = 10, $sort = 'desc') { 216 return $this->_getOptionTop('blog', $name, $amount, $sort); 217 } 218 function getMemberOptionTop($name, $amount = 10, $sort = 'desc') { 219 return $this->_getOptionTop('member', $name, $amount, $sort); 220 } 221 function getCategoryOptionTop($name, $amount = 10, $sort = 'desc') { 222 return $this->_getOptionTop('category', $name, $amount, $sort); 223 } 224 function getItemOptionTop($name, $amount = 10, $sort = 'desc') { 225 return $this->_getOptionTop('item', $name, $amount, $sort); 226 } 227 228 /** 229 * Returns the plugin ID 230 * 231 * public 232 */ 233 function getID() { 234 return $this->plugid; 235 } 236 237 /** 238 * Returns the URL of the admin area for this plugin (in case there's 239 * no such area, the returned information is invalid) 240 * 241 * public 242 */ 243 function getAdminURL() { 244 global $CONF; 245 return $CONF['PluginURL'] . $this->getShortName() . '/'; 246 } 247 248 /** 249 * Returns the directory where the admin directory is located and 250 * where the plugin can maintain his extra files 251 * 252 * public 253 */ 254 function getDirectory() { 255 global $DIR_PLUGINS; 256 return $DIR_PLUGINS . $this->getShortName() . '/'; 257 } 258 259 /** 260 * Derives the short name for the plugin from the classname (all 261 * lowercase) 262 * 263 * public 264 */ 265 function getShortName() { 266 return str_replace('np_','',strtolower(get_class($this))); 267 } 268 269 /** 270 * Clears the option value cache which saves the option values during 271 * the plugin execution. This function is usefull if the options has 272 * changed during the plugin execution (especially in association with 273 * the PrePluginOptionsUpdate and the PostPluginOptionsUpdate events) 274 * 275 * public 276 **/ 277 function clearOptionValueCache(){ 278 $this->_aOptionValues = array(); 279 $this->plugin_options = 0; 280 } 281 282 // internal functions of the class starts here 283 284 var $_aOptionValues; // oid_contextid => value 285 var $_aOptionToInfo; // context_name => array('oid' => ..., 'default' => ...) 286 var $plugin_options; // see getOption() 287 var $plugid; // plugin id 288 289 290 /** 291 * Class constructor: Initializes some internal data 292 */ 293 function NucleusPlugin() { 294 $this->_aOptionValues = array(); // oid_contextid => value 295 $this->_aOptionToInfo = array(); // context_name => array('oid' => ..., 'default' => ...) 296 $this->plugin_options = 0; 297 } 298 299 /** 300 * Retrieves an array of the top (or bottom) of an option from a plugin. 301 * @author TeRanEX 302 * @param string $context the context for the option: item, blog, member,... 303 * @param string $name the name of the option 304 * @param int $amount how many rows must be returned 305 * @param string $sort desc or asc 306 * @return array array with both values and contextid's 307 * @access private 308 */ 309 function _getOptionTop($context, $name, $amount = 10, $sort = 'desc') { 310 if (($sort != 'desc') && ($sort != 'asc')) { 311 $sort= 'desc'; 312 } 313 314 $oid = $this->_getOID($context, $name); 315 316 // retrieve the data and return 317 $q = 'SELECT otype, oextra FROM '.sql_table('plugin_option_desc').' WHERE oid = '.$oid; 318 $query = sql_query($q); 319 320 $o = sql_fetch_array($query); 321 322 if (($this->optionCanBeNumeric($o['otype'])) && ($o['oextra'] == 'number' )) { 323 $orderby = 'CAST(ovalue AS SIGNED)'; 324 } else { 325 $orderby = 'ovalue'; 326 } 327 $q = 'SELECT ovalue value, ocontextid id FROM '.sql_table('plugin_option').' WHERE oid = '.$oid.' ORDER BY '.$orderby.' '.$sort.' LIMIT 0,'.intval($amount); 328 $query = sql_query($q); 329 330 // create the array 331 $i = 0; 332 $top = array(); 333 while($row = sql_fetch_array($query)) { 334 $top[$i++] = $row; 335 } 336 337 // return the array (duh!) 338 return $top; 339 } 340 341 /** 342 * Creates an option in the database table plugin_option_desc 343 * 344 * private 345 */ 346 function _createOption($context, $name, $desc, $type, $defValue, $typeExtras = '') { 347 // create in plugin_option_desc 348 $query = 'INSERT INTO ' . sql_table('plugin_option_desc') 349 .' (opid, oname, ocontext, odesc, otype, odef, oextra)' 350 .' VALUES ('.intval($this->plugid) 351 .', \''.addslashes($name).'\'' 352 .', \''.addslashes($context).'\'' 353 .', \''.addslashes($desc).'\'' 354 .', \''.addslashes($type).'\'' 355 .', \''.addslashes($defValue).'\'' 356 .', \''.addslashes($typeExtras).'\')'; 357 sql_query($query); 358 $oid = sql_insert_id(); 359 360 $key = $context . '_' . $name; 361 $this->_aOptionToInfo[$key] = array('oid' => $oid, 'default' => $defValue); 362 return 1; 363 } 364 365 366 /** 367 * Deletes an option from the database tables 368 * plugin_option and plugin_option_desc 369 * 370 * private 371 */ 372 function _deleteOption($context, $name) { 373 $oid = $this->_getOID($context, $name); 374 if (!$oid) return 0; // no such option 375 376 // delete all things from plugin_option 377 sql_query('DELETE FROM ' . sql_table('plugin_option') . ' WHERE oid=' . $oid); 378 379 // delete entry from plugin_option_desc 380 sql_query('DELETE FROM ' . sql_table('plugin_option_desc') . ' WHERE oid=' . $oid); 381 382 // clear from cache 383 unset($this->_aOptionToInfo[$context . '_' . $name]); 384 $this->_aOptionValues = array(); 385 return 1; 386 } 387 388 /** 389 * Update an option in the database table plugin_option 390 * 391 * returns: 1 on success, 0 on failure 392 * private 393 */ 394 function _setOption($context, $contextid, $name, $value) { 395 global $manager; 396 397 $oid = $this->_getOID($context, $name); 398 if (!$oid) return 0; 399 400 // check if context id exists 401 switch ($context) { 402 case 'member': 403 if (!MEMBER::existsID($contextid)) return 0; 404 break; 405 case 'blog': 406 if (!$manager->existsBlogID($contextid)) return 0; 407 break; 408 case 'category': 409 if (!$manager->existsCategory($contextid)) return 0; 410 break; 411 case 'item': 412 if (!$manager->existsItem($contextid, true, true)) return 0; 413 break; 414 case 'global': 415 if ($contextid != 0) return 0; 416 break; 417 } 418 419 420 // update plugin_option 421 sql_query('DELETE FROM ' . sql_table('plugin_option') . ' WHERE oid='.intval($oid) . ' and ocontextid='. intval($contextid)); 422 sql_query('INSERT INTO ' . sql_table('plugin_option') . ' (ovalue, oid, ocontextid) VALUES (\''.addslashes($value).'\', '. intval($oid) . ', ' . intval($contextid) . ')'); 423 424 // update cache 425 $this->_aOptionValues[$oid . '_' . $contextid] = $value; 426 427 return 1; 428 } 429 430 /** 431 * Get an option from Cache or database 432 * - if not in the option Cache read it from the database 433 * - if not in the database write default values into the database 434 * 435 * private 436 */ 437 function _getOption($context, $contextid, $name) { 438 $oid = $this->_getOID($context, $name); 439 if (!$oid) return ''; 440 441 442 $key = $oid . '_' . $contextid; 443 444 if (isset($this->_aOptionValues[$key])) 445 return $this->_aOptionValues[$key]; 446 447 // get from DB 448 $res = sql_query('SELECT ovalue FROM ' . sql_table('plugin_option') . ' WHERE oid='.intval($oid).' and ocontextid=' . intval($contextid)); 449 450 if (!$res || (sql_num_rows($res) == 0)) { 451 $defVal = $this->_getDefVal($context, $name); 452 $this->_aOptionValues[$key] = $defVal; 453 454 // fill DB with default value 455 $query = 'INSERT INTO ' . sql_table('plugin_option') . ' (oid,ocontextid,ovalue)' 456 .' VALUES ('.intval($oid).', '.intval($contextid).', \''.addslashes($defVal).'\')'; 457 sql_query($query); 458 } 459 else { 460 $o = sql_fetch_object($res); 461 $this->_aOptionValues[$key] = $o->ovalue; 462 } 463 464 return $this->_aOptionValues[$key]; 465 } 466 467 /** 468 * Returns assoc array with all values for a given option 469 * (one option per possible context id) 470 * 471 * private 472 */ 473 function _getAllOptions($context, $name) { 474 $oid = $this->_getOID($context, $name); 475 if (!$oid) return array(); 476 $defVal = $this->_getDefVal($context, $name); 477 478 $aOptions = array(); 479 switch ($context) { 480 case 'blog': 481 $r = sql_query('SELECT bnumber as contextid FROM ' . sql_table('blog')); 482 break; 483 case 'category': 484 $r = sql_query('SELECT catid as contextid FROM ' . sql_table('category')); 485 break; 486 case 'member': 487 $r = sql_query('SELECT mnumber as contextid FROM ' . sql_table('member')); 488 break; 489 case 'item': 490 $r = sql_query('SELECT inumber as contextid FROM ' . sql_table('item')); 491 break; 492 } 493 if ($r) { 494 while ($o = sql_fetch_object($r)) 495 $aOptions[$o->contextid] = $defVal; 496 } 497 498 $res = sql_query('SELECT ocontextid, ovalue FROM ' . sql_table('plugin_option') . ' WHERE oid=' . $oid); 499 while ($o = sql_fetch_object($res)) 500 $aOptions[$o->ocontextid] = $o->ovalue; 501 502 return $aOptions; 503 } 504 505 /** 506 * Gets the 'option identifier' that corresponds to a given option name. 507 * When this method is called for the first time, all the OIDs for the plugin 508 * are loaded into memory, to avoid re-doing the same query all over. 509 */ 510 function _getOID($context, $name) { 511 $key = $context . '_' . $name; 512 $info = $this->_aOptionToInfo[$key]; 513 if (is_array($info)) return $info['oid']; 514 515 // load all OIDs for this plugin from the database 516 $this->_aOptionToInfo = array(); 517 $query = 'SELECT oid, oname, ocontext, odef FROM ' . sql_table('plugin_option_desc') . ' WHERE opid=' . intval($this->plugid); 518 $res = sql_query($query); 519 while ($o = sql_fetch_object($res)) { 520 $k = $o->ocontext . '_' . $o->oname; 521 $this->_aOptionToInfo[$k] = array('oid' => $o->oid, 'default' => $o->odef); 522 } 523 sql_free_result($res); 524 525 return $this->_aOptionToInfo[$key]['oid']; 526 } 527 function _getDefVal($context, $name) { 528 $key = $context . '_' . $name; 529 $info = $this->_aOptionToInfo[$key]; 530 if (is_array($info)) return $info['default']; 531 } 532 533 534 /** 535 * Deletes all option values for a given context and contextid 536 * (used when e.g. a blog, member or category is deleted) 537 * 538 * (static method) 539 */ 540 function _deleteOptionValues($context, $contextid) { 541 // delete all associated plugin options 542 $aOIDs = array(); 543 // find ids 544 $query = 'SELECT oid FROM '.sql_table('plugin_option_desc') . ' WHERE ocontext=\''.addslashes($context).'\''; 545 $res = sql_query($query); 546 while ($o = sql_fetch_object($res)) 547 array_push($aOIDs, $o->oid); 548 sql_free_result($res); 549 // delete those options. go go go 550 if (count($aOIDs) > 0) { 551 $query = 'DELETE FROM ' . sql_table('plugin_option') . ' WHERE oid in ('.implode(',',$aOIDs).') and ocontextid=' . intval($contextid); 552 sql_query($query); 553 } 554 } 555 556 /** 557 * splits the option's typeextra field (at ;'s) to split the meta collection 558 * @param string $typeExtra the value of the typeExtra field of an option 559 * @return array array of the meta-key/value-pairs 560 * @author TeRanEX 561 * @static 562 */ 563 function getOptionMeta($typeExtra) { 564 $tmpMeta = explode(';', $typeExtra); 565 $meta = array(); 566 for ($i = 0; $i < count($tmpMeta); $i++) { 567 if (($i == 0) && (!strstr($tmpMeta[0], '='))) { 568 // we have the select-list 569 $meta['select'] = $tmpMeta[0]; 570 } else { 571 $tmp = explode('=', $tmpMeta[$i]); 572 $meta[$tmp[0]] = $tmp[1]; 573 } 574 } 575 return $meta; 576 } 577 578 /** 579 * filters the selectlists out of the meta collection 580 * @param string $typeExtra the value of the typeExtra field of an option 581 * @return string the selectlist 582 * @author TeRanEX 583 */ 584 function getOptionSelectValues($typeExtra) { 585 $meta = NucleusPlugin::getOptionMeta($typeExtra); 586 //the select list must always be the first part 587 return $meta['select']; 588 } 589 590 /** 591 * checks if the eventlist in the database is up-to-date 592 * @return bool if it is up-to-date it return true, else false 593 * @author TeRanEX 594 */ 595 function subscribtionListIsUptodate() { 596 $res = sql_query('SELECT event FROM '.sql_table('plugin_event').' WHERE pid = '.$this->getID()); 597 $ev = array(); 598 while($a = sql_fetch_array($res)) { 599 array_push($ev, $a['event']); 600 } 601 if (count($ev) != count($this->getEventList())) { 602 return false; 603 } 604 $d = array_diff($ev, $this->getEventList()); 605 if (count($d) > 0) { 606 // there are differences so the db is not up-to-date 607 return false; 608 } 609 return true; 610 } 611 612 /** 613 * @param $aOptions: array ( 'oid' => array( 'contextid' => 'value')) 614 * (taken from request using requestVar()) 615 * @param $newContextid: integer (accepts a contextid when it is for a new 616 * contextid there was no id available at the moment of writing the 617 * formcontrols into the page (by ex: itemOptions for new item) 618 * @static 619 */ 620 function _applyPluginOptions(&$aOptions, $newContextid = 0) { 621 global $manager; 622 if (!is_array($aOptions)) return; 623 624 foreach ($aOptions as $oid => $values) { 625 626 // get option type info 627 $query = 'SELECT opid, oname, ocontext, otype, oextra, odef FROM ' . sql_table('plugin_option_desc') . ' WHERE oid=' . intval($oid); 628 $res = sql_query($query); 629 if ($o = sql_fetch_object($res)) 630 { 631 foreach ($values as $key => $value) { 632 // avoid overriding the key used by foreach statement 633 $contextid=$key; 634 635 // retreive any metadata 636 $meta = NucleusPlugin::getOptionMeta($o->oextra); 637 638 // if the option is readonly or hidden it may not be saved 639 if (($meta['access'] != 'readonly') && ($meta['access'] != 'hidden')) { 640 641 $value = undoMagic($value); // value comes from request 642 643 switch($o->otype) { 644 case 'yesno': 645 if (($value != 'yes') && ($value != 'no')) $value = 'no'; 646 break; 647 default: 648 break; 649 } 650 651 // check the validity of numerical options 652 if (($meta['datatype'] == 'numerical') && (!is_numeric($value))) { 653 //the option must be numeric, but the it isn't 654 //use the default for this option 655 $value = $o->odef; 656 } 657 658 // decide wether we are using the contextid of newContextid 659 if ($newContextid != 0) { 660 $contextid = $newContextid; 661 } 662 663 //trigger event PrePluginOptionsUpdate to give the plugin the 664 //possibility to change/validate the new value for the option 665 $manager->notify('PrePluginOptionsUpdate',array('context' => $o->ocontext, 'plugid' => $o->opid, 'optionname' => $o->oname, 'contextid' => $contextid, 'value' => &$value)); 666 667 // delete the old value for the option 668 sql_query('DELETE FROM '.sql_table('plugin_option').' WHERE oid='.intval($oid).' AND ocontextid='.intval($contextid)); 669 sql_query('INSERT INTO '.sql_table('plugin_option')." (oid, ocontextid, ovalue) VALUES (".intval($oid).",".intval($contextid).",'" . addslashes($value) . "')"); 670 } 671 } 672 } 673 // clear option value cache if the plugin object is already loaded 674 if (is_object($o)) { 675 $plugin=& $manager->pidLoaded($o->opid); 676 if ($plugin) $plugin->clearOptionValueCache(); 677 } 678 } 679 } 680 } 681 ?>
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
| Generated: Sun Aug 1 03:56:06 2010 |