2 * Nucleus: PHP/MySQL Weblog CMS (http://nucleuscms.org/)
3 * Copyright (C) 2002-2004 The Nucleus Group
5 * This program is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU General Public License
7 * as published by the Free Software Foundation; either version 2
8 * of the License, or (at your option) any later version.
9 * (see nucleus/documentation/index.html#license for more info)
11 * This is an (abstract) class of which all Nucleus Plugins must inherit
13 * for more information on plugins and how to write your own, see the
14 * plugins.html file that is included with the Nucleus documenation
16 * $Id: PLUGIN.php,v 1.1.1.1 2005-02-28 07:14:52 kimitake Exp $
20 // these functions _have_ to be redefined in your plugin
22 function getName() { return 'Undefined'; }
23 function getAuthor() { return 'Undefined'; }
24 function getURL() { return 'Undefined'; }
25 function getVersion() { return '0.0'; }
26 function getDescription() { return 'Undefined';}
28 // these function _may_ be redefined in your plugin
30 function getMinNucleusVersion() { return 150; }
31 function getMinNucleusPatchLevel() { return 0; }
32 function getEventList() { return array(); }
33 function getTableList() { return array(); }
34 function hasAdminArea() { return 0; }
37 function unInstall() {}
41 function doSkinVar($skinType) {}
42 function doTemplateVar(&$item) {
43 $args = func_get_args();
45 array_unshift($args, 'template');
46 call_user_func_array(array(&$this,'doSkinVar'),$args);
48 function doTemplateCommentsVar(&$item, &$comment) {
49 $args = func_get_args();
52 array_unshift($args, 'template');
53 call_user_func_array(array(&$this,'doSkinVar'),$args);
55 function doAction($type) { return 'No Such Action'; }
58 * Checks if a plugin supports a certain feature.
60 * @returns 1 if the feature is reported, 0 if not
62 * Name of the feature. See plugin documentation for more info
63 * 'SqlTablePrefix' -> if the plugin uses the sql_table() method to get table names
64 * 'HelpPage' -> if the plugin provides a helppage
66 function supportsFeature($feature) {
71 * Report a list of plugin that is required to function
73 * @returns an array of names of plugin, an empty array indicates no dependency
75 function getPluginDep() { return array(); }
77 // these helper functions should not be redefined in your plugin
80 * Creates a new option for this plugin
83 * A string uniquely identifying your option. (max. length is 20 characters)
85 * A description that will show up in the nucleus admin area (max. length: 255 characters)
87 * Either 'text', 'yesno' or 'password'
88 * This info is used when showing 'edit plugin options' screens
90 * Initial value for the option (max. value length is 128 characters)
92 function createOption($name, $desc, $type, $defValue = '', $typeExtras = '') {
93 return $this->_createOption('global', $name, $desc, $type, $defValue, $typeExtras);
95 function createBlogOption($name, $desc, $type, $defValue = '', $typeExtras = '') {
96 return $this->_createOption('blog', $name, $desc, $type, $defValue, $typeExtras);
98 function createMemberOption($name, $desc, $type, $defValue = '', $typeExtras = '') {
99 return $this->_createOption('member', $name, $desc, $type, $defValue, $typeExtras);
101 function createCategoryOption($name, $desc, $type, $defValue = '', $typeExtras = '') {
102 return $this->_createOption('category', $name, $desc, $type, $defValue, $typeExtras);
104 function createItemOption($name, $desc, $type, $defValue = '', $typeExtras = '') {
105 return $this->_createOption('item', $name, $desc, $type, $defValue, $typeExtras);
109 * Removes the option from the database
111 * Note: Options get erased automatically on plugin uninstall
113 function deleteOption($name) {
114 return $this->_deleteOption('global', $name);
116 function deleteBlogOption($name) {
117 return $this->_deleteOption('blog', $name);
119 function deleteMemberOption($name) {
120 return $this->_deleteOption('member', $name);
122 function deleteCategoryOption($name) {
123 return $this->_deleteOption('category', $name);
125 function deleteItemOption($name) {
126 return $this->_deleteOption('item', $name);
130 * Sets the value of an option to something new
132 function setOption($name, $value) {
133 return $this->_setOption('global', 0, $name, $value);
135 function setBlogOption($blogid, $name, $value) {
136 return $this->_setOption('blog', $blogid, $name, $value);
138 function setMemberOption($memberid, $name, $value) {
139 return $this->_setOption('member', $memberid, $name, $value);
141 function setCategoryOption($catid, $name, $value) {
142 return $this->_setOption('category', $catid, $name, $value);
144 function setItemOption($itemid, $name, $value) {
145 return $this->_setOption('item', $itemid, $name, $value);
149 * Retrieves the current value for an option
151 function getOption($name)
153 // only request the options the very first time. On subsequent requests
154 // the static collection is used to save SQL queries.
155 if ($this->plugin_options == 0)
157 $this->plugin_options = array();
158 $query = mysql_query(
159 'SELECT d.oname as name, o.ovalue as value '.
161 sql_table('plugin_option').' o, '.
162 sql_table('plugin_option_desc').' d '.
163 'WHERE d.opid='. intval($this->getID()).' AND d.oid=o.oid'
165 while ($row = mysql_fetch_object($query))
166 $this->plugin_options[strtolower($row->name)] = $row->value;
168 if (isset($this->plugin_options[strtolower($name)]))
169 return $this->plugin_options[strtolower($name)];
171 return $this->_getOption('global', 0, $name);
174 function getBlogOption($blogid, $name) {
175 return $this->_getOption('blog', $blogid, $name);
177 function getMemberOption($memberid, $name) {
178 return $this->_getOption('member', $memberid, $name);
180 function getCategoryOption($catid, $name) {
181 return $this->_getOption('category', $catid, $name);
183 function getItemOption($itemid, $name) {
184 return $this->_getOption('item', $itemid, $name);
188 * Retrieves an associative array with the option value for each
191 function getAllBlogOptions($name) {
192 return $this->_getAllOptions('blog', $name);
194 function getAllMemberOptions($name) {
195 return $this->_getAllOptions('member', $name);
197 function getAllCategoryOptions($name) {
198 return $this->_getAllOptions('category', $name);
200 function getAllItemOptions($name) {
201 return $this->_getAllOptions('item', $name);
205 * Retrieves an indexed array with the top (or bottom) of an option
206 * (delegates to _getOptionTop())
208 function getBlogOptionTop($name, $amount = 10, $sort = 'desc') {
209 return $this->_getOptionTop('blog', $name, $amount, $sort);
211 function getMemberOptionTop($name, $amount = 10, $sort = 'desc') {
212 return $this->_getOptionTop('member', $name, $amount, $sort);
214 function getCategoryOptionTop($name, $amount = 10, $sort = 'desc') {
215 return $this->_getOptionTop('category', $name, $amount, $sort);
217 function getItemOptionTop($name, $amount = 10, $sort = 'desc') {
218 return $this->_getOptionTop('item', $name, $amount, $sort);
222 * Retrieves an array of the top (or bottom) of an option from a plugin.
224 * @param string $context the context for the option: item, blog, member,...
225 * @param string $name the name of the option
226 * @param int $amount how many rows must be returned
227 * @param string $sort desc or asc
228 * @return array array with both values and contextid's
231 function _getOptionTop($context, $name, $amount = 10, $sort = 'desc') {
232 if (($sort != 'desc') && ($sort != 'asc')) {
236 $oid = $this->_getOID($context, $name);
238 // retrieve the data and return
239 $q = 'SELECT otype, oextra FROM '.sql_table('plugin_option_desc').' WHERE oid = '.$oid;
240 $query = mysql_query($q);
242 $o = mysql_fetch_array($query);
244 if (($this->optionCanBeNumeric($o['otype'])) && ($o['oextra'] == 'number' )) {
245 $orderby = 'CAST(ovalue AS SIGNED)';
249 $q = 'SELECT ovalue value, ocontextid id FROM '.sql_table('plugin_option').' WHERE oid = '.$oid.' ORDER BY '.$orderby.' '.$sort.' LIMIT 0,'.$amount;
250 $query = mysql_query($q);
255 while($row = mysql_fetch_array($query)) {
259 // return the array (duh!)
264 * Returns the plugin ID
267 return $this->plugid;
271 * returns the URL of the admin area for this plugin (in case there's
272 * no such area, the returned information is invalid)
274 function getAdminURL() {
276 return $CONF['PluginURL'] . $this->getShortName() . '/';
280 * Returns the directory where the admin directory is located and
281 * where the plugin can maintain his extra files
283 function getDirectory() {
285 return $DIR_PLUGINS . $this->getShortName() . '/';
289 * Derives the short name for the plugin from the classname (all lowercase)
291 function getShortName() {
292 return str_replace('np_','',strtolower(get_class($this)));
295 var $_aOptionValues; // oid_contextid => value
296 var $_aOptionToInfo; // context_name => array('oid' => ..., 'default' => ...)
297 var $plugin_options; // see getOption()
298 var $plugid; // plugin id
301 // constructor. Initializes some internal data
302 function NucleusPlugin() {
303 $this->_aOptionValues = array(); // oid_contextid => value
304 $this->_aOptionToInfo = array(); // context_name => array('oid' => ..., 'default' => ...)
305 $this->plugin_options = 0;
309 function _createOption($context, $name, $desc, $type, $defValue, $typeExtras = '') {
310 // create in plugin_option_desc
311 $query = 'INSERT INTO ' . sql_table('plugin_option_desc')
312 .' (opid, oname, ocontext, odesc, otype, odef, oextra)'
313 .' VALUES ('.intval($this->plugid)
314 .', \''.addslashes($name).'\''
315 .', \''.addslashes($context).'\''
316 .', \''.addslashes($desc).'\''
317 .', \''.addslashes($type).'\''
318 .', \''.addslashes($defValue).'\''
319 .', \''.addslashes($typeExtras).'\')';
321 $oid = mysql_insert_id();
323 $key = $context . '_' . $name;
324 $this->_aOptionToInfo[$key] = array('oid' => $oid, 'default' => $defValue);
330 function _deleteOption($context, $name) {
331 $oid = $this->_getOID($context, $name);
332 if (!$oid) return 0; // no such option
334 // delete all things from plugin_option
335 sql_query('DELETE FROM ' . sql_table('plugin_option') . ' WHERE oid=' . $oid);
337 // delete entry from plugin_option_desc
338 sql_query('DELETE FROM ' . sql_table('plugin_option_desc') . ' WHERE oid=' . $oid);
341 unset($this->_aOptionToInfo[$context . '_' . $name]);
342 $this->_aOptionValues = array();
348 * returns: 1 on success, 0 on failure
350 function _setOption($context, $contextid, $name, $value) {
353 $oid = $this->_getOID($context, $name);
356 // check if context id exists
359 if (!MEMBER::existsID($contextid)) return 0;
362 if (!$manager->existsBlogID($contextid)) return 0;
365 if (!$manager->existsCategory($contextid)) return 0;
368 if (!$manager->existsItem($contextid, true, true)) return 0;
371 if ($contextid != 0) return 0;
376 // update plugin_option
377 sql_query('DELETE FROM ' . sql_table('plugin_option') . ' WHERE oid='.intval($oid) . ' and ocontextid='. intval($contextid));
378 sql_query('INSERT INTO ' . sql_table('plugin_option') . ' (ovalue, oid, ocontextid) VALUES (\''.addslashes($value).'\', '. intval($oid) . ', ' . intval($contextid) . ')');
381 $this->_aOptionValues[$oid . '_' . $contextid] = $value;
387 function _getOption($context, $contextid, $name) {
388 $oid = $this->_getOID($context, $name);
389 if (!$oid) return '';
392 $key = $oid . '_' . $contextid;
394 if (isset($this->_aOptionValues[$key]))
395 return $this->_aOptionValues[$key];
398 $res = sql_query('SELECT ovalue FROM ' . sql_table('plugin_option') . ' WHERE oid='.intval($oid).' and ocontextid=' . intval($contextid));
400 if (!$res || (mysql_num_rows($res) == 0)) {
401 $defVal = $this->_getDefVal($context, $name);
402 $this->_aOptionValues[$key] = $defVal;
404 // fill DB with default value
405 $query = 'INSERT INTO ' . sql_table('plugin_option') . ' (oid,ocontextid,ovalue)'
406 .' VALUES ('.intval($oid).', '.intval($contextid).', \''.addslashes($defVal).'\')';
410 $o = mysql_fetch_object($res);
411 $this->_aOptionValues[$key] = $o->ovalue;
414 return $this->_aOptionValues[$key];
418 * Returns assoc array with all values for a given option (one option per
419 * possible context id)
421 function _getAllOptions($context, $name) {
422 $oid = $this->_getOID($context, $name);
423 if (!$oid) return array();
424 $defVal = $this->_getDefVal($context, $name);
429 $r = sql_query('SELECT bnumber as contextid FROM ' . sql_table('blog'));
432 $r = sql_query('SELECT catid as contextid FROM ' . sql_table('category'));
435 $r = sql_query('SELECT mnumber as contextid FROM ' . sql_table('member'));
439 while ($o = mysql_fetch_object($r))
440 $aOptions[$o->contextid] = $defVal;
443 $res = sql_query('SELECT ocontextid, ovalue FROM ' . sql_table('plugin_option') . ' WHERE oid=' . $oid);
444 while ($o = mysql_fetch_object($res))
445 $aOptions[$o->ocontextid] = $o->ovalue;
451 * Gets the 'option identifier' that corresponds to a given option name.
452 * When this method is called for the first time, all the OIDs for the plugin
453 * are loaded into memory, to avoid re-doing the same query all over.
455 function _getOID($context, $name) {
456 $key = $context . '_' . $name;
457 $info = $this->_aOptionToInfo[$key];
458 if (is_array($info)) return $info['oid'];
460 // load all OIDs for this plugin from the database
461 $this->_aOptionToInfo = array();
462 $query = 'SELECT oid, oname, ocontext, odef FROM ' . sql_table('plugin_option_desc') . ' WHERE opid=' . intval($this->plugid);
463 $res = sql_query($query);
464 while ($o = mysql_fetch_object($res)) {
465 $k = $o->ocontext . '_' . $o->oname;
466 $this->_aOptionToInfo[$k] = array('oid' => $o->oid, 'default' => $o->odef);
468 mysql_free_result($res);
470 return $this->_aOptionToInfo[$key]['oid'];
472 function _getDefVal($context, $name) {
473 $key = $context . '_' . $name;
474 $info = $this->_aOptionToInfo[$key];
475 if (is_array($info)) return $info['default'];
480 * Deletes all option values for a given context and contextid
481 * (used when e.g. a blog, member or category is deleted)
485 function _deleteOptionValues($context, $contextid) {
486 // delete all associated plugin options
489 $query = 'SELECT oid FROM '.sql_table('plugin_option_desc') . ' WHERE ocontext=\''.addslashes($context).'\'';
490 $res = sql_query($query);
491 while ($o = mysql_fetch_object($res))
492 array_push($aOIDs, $o->oid);
493 mysql_free_result($res);
494 // delete those options. go go go
495 if (count($aOIDs) > 0) {
496 $query = 'DELETE FROM ' . sql_table('plugin_option') . ' WHERE oid in ('.implode(',',$aOIDs).') and ocontextid=' . intval($contextid);
502 * splits the option's typeextra field (at ;'s) to split the meta collection
503 * @param string $typeExtra the value of the typeExtra field of an option
504 * @return array array of the meta-key/value-pairs
508 function getOptionMeta($typeExtra) {
509 $tmpMeta = explode(';', $typeExtra);
511 for ($i = 0; $i < count($tmpMeta); $i++) {
512 if (($i == 0) && (!strstr($tmpMeta[0], '='))) {
513 // we have the select-list
514 $meta['select'] = $tmpMeta[0];
516 $tmp = explode('=', $tmpMeta[$i]);
517 $meta[$tmp[0]] = $tmp[1];
524 * filters the selectlists out of the meta collection
525 * @param string $typeExtra the value of the typeExtra field of an option
526 * @return string the selectlist
529 function getOptionSelectValues($typeExtra) {
530 $meta = NucleusPlugin::getOptionMeta($typeExtra);
531 //the select list must always be the first part
532 return $meta['select'];
536 * @param $aOptions: array ( 'oid' => array( 'contextid' => 'value'))
537 * (taken from request using requestVar())
538 * @param $newContextid: integer (accepts a contextid when it is for a new
539 * contextid there was no id available at the moment of writing the
540 * formcontrols into the page (by ex: itemOptions for new item)
543 function _applyPluginOptions(&$aOptions, $newContextid = 0) {
545 if (!is_array($aOptions)) return;
547 foreach ($aOptions as $oid => $values) {
549 // get option type info
550 $query = 'SELECT opid, oname, ocontext, otype, oextra, odef FROM ' . sql_table('plugin_option_desc') . ' WHERE oid=' . intval($oid);
551 $res = sql_query($query);
552 if ($o = mysql_fetch_object($res))
554 foreach ($values as $contextid => $value) {
555 // retreive any metadata
556 $meta = NucleusPlugin::getOptionMeta($o->oextra);
558 // if the option is readonly or hidden it may not be saved
559 if (($meta['access'] != 'readonly') && ($meta['access'] != 'hidden')) {
561 $value = undoMagic($value); // value comes from request
565 if (($value != 'yes') && ($value != 'no')) $value = 'no';
571 // check the validity of numerical options
572 if (($meta['datatype'] == 'numerical') && (!is_numeric($value))) {
573 //the option must be numeric, but the it isn't
574 //use the default for this option
578 // decide wether we are using the contextid of newContextid
579 if ($newContextid != 0) {
580 $contextid = $newContextid;
583 //trigger event PrePluginOptionsUpdate to give the plugin the
584 //possibility to change/validate the new value for the option
585 $manager->notify('PrePluginOptionsUpdate',array('context' => $o->ocontext, 'plugid' => $o->opid, 'optionname' => $o->oname, 'contextid' => $contextid, 'value' => &$value));
587 // delete the old value for the option
588 sql_query('DELETE FROM '.sql_table('plugin_option').' WHERE oid='.intval($oid).' AND ocontextid='.intval($contextid));
589 sql_query('INSERT INTO '.sql_table('plugin_option')." (oid, ocontextid, ovalue) VALUES (".intval($oid).",".intval($contextid).",'" . addslashes($value) . "')");