Source for file plugin-defs.php

Documentation is available at plugin-defs.php

  1. <?php
  2. /* ******************************************************************** */
  3. /* CATALYST PHP Source Code */
  4. /* -------------------------------------------------------------------- */
  5. /* This program is free software; you can redistribute it and/or modify */
  6. /* it under the terms of the GNU General Public License as published by */
  7. /* the Free Software Foundation; either version 2 of the License, or */
  8. /* (at your option) any later version. */
  9. /* */
  10. /* This program is distributed in the hope that it will be useful, */
  11. /* but WITHOUT ANY WARRANTY; without even the implied warranty of */
  12. /* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the */
  13. /* GNU General Public License for more details. */
  14. /* */
  15. /* You should have received a copy of the GNU General Public License */
  16. /* along with this program; if not, write to: */
  17. /* The Free Software Foundation, Inc., 59 Temple Place, Suite 330, */
  18. /* Boston, MA 02111-1307 USA */
  19. /* -------------------------------------------------------------------- */
  20. /* */
  21. /* Filename: plugin-defs.php */
  22. /* Author: Paul Waite */
  23. /* Description: Definitions for managing plugin regions for webpages. */
  24. /* */
  25. /* ******************************************************************** */
  26. /** @package core *//**
  27. * The page section class
  28. * The class takes care of page sections. A page section is any part of a
  29. * webpage. Page sections we define for HTML pages are: head, body and
  30. * foot. Each section has a common set of properties and methods and these
  31. * are defined here.
  32. * @package core
  33. */
  34. class page_section extends RenderableObject {
  35. // Public
  36. /** Page section content */
  37.  
  38. var $content = "";
  39.  
  40. // Private
  41. /** Script content for this page section
  42. @access private */
  43. var $script;
  44. /** Scripts which are sourced via a URL
  45. @access private */
  46. var $scriptsrc;
  47. // .....................................................................
  48. /**
  49. * Constructor
  50. * Create a new page section object.
  51. * @param string $content Initial page content
  52. */
  53. function page_section($content="") {
  54. $this->content = $content;
  55. } // page_section
  56. // .....................................................................
  57. /**
  58. * Add new content to the page section.
  59. * @param string $newstuff Initial page content
  60. */
  61. function add($newstuff) {
  62. $this->content .= $newstuff;
  63. return $this;
  64. } // add
  65. // .....................................................................
  66. /**
  67. * Clear all content from the page section.
  68. */
  69. function clear() {
  70. $this->content = "";
  71. $this->script = "";
  72. $this->scriptsrc = "";
  73. return $this;
  74. } // clear
  75. // .....................................................................
  76. /** Return content, if not null or newline.
  77. * @return string The page section content
  78. */
  79. function get_trimcontent() {
  80. $content = trim($this->content);
  81. if ($content == "\n") $content = "";
  82. return $content;
  83. } // get_trimcontent
  84. // .....................................................................
  85. /**
  86. * Add popup window scripting.
  87. * This method adds Javascript which specifically supports the opening
  88. * of a popup window from a function call elsewhere in the webpage. There
  89. * are various options to force the size and position, or leave to be
  90. * passed as parameters in the javascript function call.
  91. * NB: This does NOT open the window. It inserts the Javascript for you to
  92. * be able to call a function to open the window from elsewhere in the page.
  93. * @param string $popupname The name you want the function to be called
  94. * @param integer $width Width (px) of window if fixed, else will be a parameter
  95. * @param integer $height Height (px) of window if fixed, else will be a parameter
  96. * @param integer $left Left offset (px) of window if fixed, else will be a parameter
  97. * @param integer $top Left offset (px) of window if fixed, else will be a parameter
  98. * @param string $features The window features, if you want to override the defaults
  99. */
  100. function add_popup_script(
  101. $popupname,
  102. $width=false,
  103. $height=false,
  104. $left=false,
  105. $top=false,
  106. $features="toolbar=no,status=no,scrollbars=no,resizable=yes"
  107. )
  108. {
  109. $js = "var " . $popupname . "Win=null;\n";
  110. $js .= "function $popupname(theurl,width,height,left,top) {\n";
  111. if ($width === false) $js .= " if(width) ws='width='+width;else ws='';";
  112. else $js .= " ws='width='+$width;";
  113. if ($height === false) $js .= "if(height) hs='height='+height;else hs='';";
  114. else $js .= "hs='height='+$height;";
  115. if ($left === false) $js .= "if(left) ls='left='+left;else ls='';";
  116. else $js .= "ls='left='+$left;";
  117. if ($top === false) $js .= "if(top) ts='top='+top;else ts='';";
  118. else $js .= "ts='top='+$top;";
  119. $js .= "\n var feats='$features';\n";
  120. $js .= " if(ws!='') feats+=','+ws;";
  121. $js .= " if(hs!='') feats+=','+hs;";
  122. $js .= " if(ls!='') feats+=','+ls;";
  123. $js .= " if(ts!='') feats+=','+ts;\n";
  124. $js .= " " . $popupname . "Win=window.open(theurl,'$popupname',feats);\n";
  125. $js .= " if(" . $popupname . "Win != null) " . $popupname . "Win.focus();\n";
  126. $js .= "}\n";
  127. $this->add_script($js);
  128. } // add_popup_script
  129. // .....................................................................
  130. /**
  131. * Add more scripting to this page section.
  132. * @param string $script Script content (omit <script> tags)
  133. * @param string $language The language the script is in
  134. */
  135. function add_script($script, $language="javascript") {
  136. $this->add_named_script($script, "default", $language);
  137. } // add_script
  138. // .....................................................................
  139. /**
  140. * This adds a specific lump of script to the webpage under a unique name.
  141. * It allows you to collect multiple additions of script content under
  142. * a single grouping, and so cause the final rendering to group it all
  143. * together.
  144. * @param string $script Script content (omit <script> tags)
  145. * @param string $name Script content grouping identity
  146. * @param string $language The language the script is in
  147. */
  148. function add_named_script($script, $name, $language="javascript") {
  149. if ($name == "") {
  150. $name = "default";
  151. }
  152. $this->script[$name][$language] .= $script;
  153. } // add_named_script
  154. // .....................................................................
  155. /**
  156. * Add script reference link
  157. * Add more scripting to this section in the form of
  158. * a link to a script source file.
  159. * @param string $src URL pointing to the script
  160. * @param string $language The language the script is in
  161. */
  162. function add_scriptsrc($src, $language="javascript") {
  163. $this->scriptsrc[$language][] = $src;
  164. } // add_scriptsrc
  165. // .....................................................................
  166. /**
  167. * Returns all of the defined script. Literal script is rendered for each
  168. * language if more than one language is being used. Each language is
  169. * bracketed with the usual <script language=foo></script> tags. Any
  170. * script sources (URL references to scripts) are also rendered.
  171. * @return string All the defined script content including source references
  172. */
  173. // Render script..
  174. function script() {
  175. $s = "";
  176. if (isset($this->scriptsrc) && is_array($this->scriptsrc)) {
  177. foreach ($this->scriptsrc as $language => $srcs) {
  178. foreach ($srcs as $src) {
  179. $s .= "<script type=\"text/$language\" src=\"$src\"></script>\n";
  180. }
  181. }
  182. }
  183. if (isset($this->script) && is_array($this->script)) {
  184. foreach ($this->script as $groupname => $scripts) {
  185. if ($groupname != "default") {
  186. $s .= "<!-- $groupname -->\n";
  187. }
  188. foreach ($scripts as $language => $script) {
  189. $s .= "<script type=\"text/$language\" language=\"$language\">\n";
  190. $s .= "<!--\n";
  191. $s .= $script;
  192. $s .= "//-->\n";
  193. $s .= "</script>\n";
  194. }
  195. }
  196. }
  197. return $s;
  198. } // script
  199. // .....................................................................
  200. /**
  201. * Replaces multiple occurrences of the given tag (pattern) in the
  202. * body content with the specified new stuff.
  203. * @param string $tag Pattern to replace in content
  204. * @param string $newstuff Stuff to replace the tag with
  205. */
  206. function replace($tag, $newstuff) {
  207. $tmp = str_replace($tag, $newstuff, $this->content);
  208. $this->content = $tmp;
  209. return $this;
  210. } // replace
  211. // ....................................................................
  212. /**
  213. * Read in the template for this page section.
  214. * @param string The full path of the template to get
  215. * @return string The full content of the template
  216. */
  217. function get_template($templatefile="") {
  218. global $TEMPLATES;
  219. $template = "";
  220. if ($templatefile != "") {
  221. if (isset($TEMPLATES[$templatefile])) {
  222. // Get cached copy..
  223. $template = $TEMPLATES[$templatefile];
  224. }
  225. else {
  226. // Read from actual template file..
  227. $tpfile = new inputfile($templatefile);
  228. if ($tpfile->opened) {
  229. $content = $tpfile->readall();
  230. $tpfile->closefile();
  231. if ($content !== false) {
  232. $template = $content;
  233. }
  234. }
  235. $TEMPLATES[$templatefile] = $template;
  236. }
  237. }
  238. return $template;
  239. } // get_template
  240. // ....................................................................
  241. /**
  242. * This renders the page section as HTML.
  243. * @return string The page section as HTML.
  244. */
  245. function html() {
  246. return $this->content;
  247. } // html
  248. // ....................................................................
  249. /**
  250. * This renders the page section as WML.
  251. * @return string The page section as WML.
  252. */
  253. function wml() {
  254. return $this->content;
  255. } // wml
  256.  
  257. } // page_section class
  258. // ----------------------------------------------------------------------
  259.  
  260. /**
  261. * Pluginset class
  262. * This class manages plugins as a set. It is designed for use by
  263. * webpages, which can have many types of plugin content defined for
  264. * them.
  265. * @package core
  266. */
  267. class pluginset {
  268. // Public
  269. // Private
  270. /** Array of plugins in this set
  271. @access private */
  272. var $plugins = array();
  273. /** Flag indicating whether plugins exist
  274. @access private */
  275. var $hascontent = false;
  276. // .....................................................................
  277. /**
  278. * Constructor
  279. * Create a new plugin set. This is just a container for plugins.
  280. */
  281. function pluginset() {}
  282. // .....................................................................
  283. /**
  284. * Clear all plugins from the set
  285. */
  286. function clear() {
  287. unset($this->plugins);
  288. $this->hascontent = false;
  289. } // clear
  290. // .....................................................................
  291. /**
  292. * Add a new plugin to the plugin set. The type of plugin is
  293. * determined from the content passed as the second paramter.
  294. * Allowed types: object (must inherit RenderableObject), a
  295. * function definition, a file-path, or just literal content.
  296. * @param string $pluginid ID of this plugin. Used to find plugin location
  297. * @param mixed $content The plugin content (literal, function, object...)
  298. */
  299. function add_plugin($pluginid, $content="") {
  300. $pluginid = strtoupper($pluginid);
  301. debugbr("adding plugin '$pluginid'");
  302. $this->plugins[$pluginid] = new plugin($pluginid, $content);
  303. $this->hascontent = true;
  304. return $this;
  305. } // add_plugin
  306. // .....................................................................
  307. /**
  308. * Adds content to the given plugin. If the plugin doesn't
  309. * exist yet, then we create it first.
  310. * @param string $pluginid ID of this plugin. Used to find plugin location
  311. * @param mixed $content Content to plug in. May be string, path, object or function def.
  312. */
  313. function addto($pluginid, $content) {
  314. $pluginid = strtoupper($pluginid);
  315. if (!isset($this->plugins[$pluginid])) {
  316. $this->add_plugin($pluginid, $content);
  317. }
  318. else {
  319. $plugin = $this->plugins[$pluginid];
  320. $plugin->add_content($content);
  321. $this->plugins[$pluginid] = $plugin;
  322. }
  323. return $this;
  324. } // addto
  325. // .....................................................................
  326. /**
  327. * This method takes the given template, and renders the plugins on
  328. * it one by one. Each plugin is applied to the template, replacing
  329. * all occurences of the appropriate tag based on the pluginid. Then
  330. * finally the resulting string is returned.
  331. */
  332. function render($template="") {
  333. if ($template != "") {
  334. $plugged = $template;
  335. if (isset($this->plugins)) {
  336. foreach ($this->plugins as $id => $plugin) {
  337. if (is_object($plugin)) {
  338. $newstuff = $plugin->render();
  339. $tag = "<!--" . strtoupper($id) . "-->";
  340. str_replace($tag, $newstuff, $plugged);
  341. }
  342. }
  343. }
  344. }
  345. return $plugged;
  346. } //render
  347.  
  348. } // pluginset class
  349. // ----------------------------------------------------------------------
  350.  
  351. /**
  352. * Plugin class
  353. * A plugin is something which can be used by the system to render
  354. * content to be plugged into a webpage in any specified place.
  355. * The normal plugin just provides a receptacle for content, and
  356. * which will be plugged in when the webpage is built. You can
  357. * also specify a path of a file containing content, an object to
  358. * render() content, or a function to return content.
  359. * We can have multiple types of plugin:
  360. * - Standard: Literal content as provided
  361. * - Function: A function call which returns content
  362. * - Object: An object which renders content
  363. * - File: A file which contains content
  364. * @package core
  365. */
  366. class plugin extends page_section {
  367. // Public
  368. // Private
  369. /** ID or name of this plugin
  370. @access private */
  371. var $pluginid = "";
  372. /** Array of plugin content objects
  373. @access private */
  374. var $plugin_contents;
  375. // .....................................................................
  376. /**
  377. * Constructor
  378. * Create a new plugin object.
  379. * @param string $pluginid ID of this plugin. Used to find plugin location
  380. * @param string $content Content to put into this plugin location
  381. */
  382. function plugin($pluginid, $content="") {
  383. $this->page_section();
  384. $this->pluginid = strtoupper($pluginid);
  385. $this->add_content($content);
  386. } // plugin
  387. // .....................................................................
  388. /**
  389. * Allows adding of any type of content to the plugin. This could be
  390. * literal (string), a file path referencing a file full of content, or
  391. * and object supporting render(), or the name of a function which is in
  392. * scope. In the latter case, the function name is saved here, and will
  393. * only be executed later on when plugins are rendered prior to sending
  394. * the webpage. This allows 'late' content rendering.
  395. * @param mixed $content Content to plug in: string, path, object or func name
  396. */
  397. function add_content($content="") {
  398. if (is_object($content)) {
  399. // An object which returns content via render()..
  400. $this->plugin_contents[] = new object_plugin_content($content);
  401. }
  402. elseif (is_string($content)) {
  403. $pattern = "/^.+\(.*\)" . chr(36) . "/";
  404. if (preg_match($pattern, $content)) {
  405. // A function definition..
  406. $this->plugin_contents[] = new func_plugin_content($content);
  407. }
  408. elseif (realpath($content) && file_exists($content)) {
  409. // File content..
  410. $this->plugin_contents[] = new file_plugin_content($content);
  411. }
  412. else {
  413. // Standard string content..
  414. $this->plugin_contents[] = new plugin_content($content);
  415. }
  416. }
  417. } // add_content
  418. // .....................................................................
  419. /**
  420. * Returns the string which represents all of the content
  421. * types which have been stored in this plugin. Note that we do not
  422. * differentiate between HTML or WML etc. since the content from our
  423. * point of view is all generic at this stage. Hence we override the
  424. * render() method, and not html() and/or wml().
  425. * @return string Plugin content.
  426. */
  427. function render() {
  428. $s = "";
  429. if (isset($this->plugin_contents)) {
  430. foreach ($this->plugin_contents as $content) {
  431. $new_content = $content->render();
  432. // Now render any content block tags. This scans the
  433. // content string for BLOCKID tags and renders the block
  434. // content in their place if any are found..
  435. if (function_exists("render_layouts")) {
  436. $new_content = render_layouts($new_content);
  437. }
  438. $s .= $new_content;
  439. }
  440. }
  441. return $s;
  442. } // render
  443.  
  444. } // plugin class
  445. // ----------------------------------------------------------------------
  446.  
  447. /**
  448. * Plugin content.
  449. * Literal plugin content.
  450. * for a plugin.
  451. * @package core
  452. * @access private
  453. */
  454. class plugin_content {
  455. /** The plugin content */
  456.  
  457. var $content;
  458. /**
  459. * Constructor. Create a new literal plugin object.
  460. * @param string $content Literal content to be plugged in
  461. */
  462. function plugin_content($content="") {
  463. $this->content = $content;
  464. } // plugin_content
  465. // .....................................................................
  466. /**
  467. * Generate plugin content
  468. * Return content.
  469. * @return string Plugin content.
  470. */
  471. function render() {
  472. return $this->content;
  473. } // render
  474.  
  475. } // plugin_content class
  476. // ----------------------------------------------------------------------
  477.  
  478. /**
  479. * File plugin content
  480. * You can specify the name of a file which contains the content
  481. * for a plugin.
  482. * @package core
  483. * @access private
  484. */
  485. class file_plugin_content extends plugin_content {
  486. /** The path to the file */
  487.  
  488. var $path;
  489. /**
  490. * Constructor
  491. * Create a new file plugin content object.
  492. * @param string $path Path to a file containing content
  493. */
  494. function file_plugin_content($path="") {
  495. if ($path != "") {
  496. if (file_exists($path)) {
  497. $this->path = $path;
  498. $plugfile = new inputfile($path);
  499. if ($plugfile->opened) {
  500. $this->content = $plugfile->readall();
  501. $plugfile->closefile();
  502. }
  503. }
  504. }
  505. } // file_plugin_content
  506.  
  507. } // file_plugin_content class
  508. // ----------------------------------------------------------------------
  509.  
  510. /**
  511. * Function plugin content
  512. * Contains details of a function to be used to generated content,
  513. * @package core
  514. * @access private
  515. */
  516. class func_plugin_content extends plugin_content {
  517. /** The name of the function which returns content */
  518.  
  519. var $funcname = "";
  520. /** The arguments for the function */
  521.  
  522. var $funcargs;
  523. // .....................................................................
  524. /**
  525. * Constructor
  526. * Create a new function plugin object.
  527. * @param string $funcdef Definition of the function to call for content
  528. */
  529. function func_plugin_content($funcdef) {
  530. $pattern = "/^(.+)\((.*)\)" . chr(36) . "/";
  531. if (preg_match($pattern, $funcdef, $matches)) {
  532. $this->funcname = $matches[1];
  533. $argstr = $matches[2];
  534. $argstr = str_replace("\"", "", $argstr);
  535. $argstr = str_replace("'", "", $argstr);
  536. $this->funcargs = explode(",", $argstr);
  537. }
  538. } // func_plugin_content
  539. // .....................................................................
  540. /**
  541. * Generate plugin content
  542. * Call the givenfunction which should return a string, containing
  543. * the content.
  544. * @return string Plugin content.
  545. */
  546. function render() {
  547. if (isset($this->funcname)) {
  548. if (function_exists($this->funcname)) {
  549. $content = call_user_func_array($this->funcname, $this->funcargs);
  550. if (is_string($content) && $content != "") {
  551. $this->content = $content;
  552. }
  553. }
  554. }
  555. return $this->content;
  556. } //render
  557.  
  558. } // func_plugin_content class
  559. // ----------------------------------------------------------------------
  560.  
  561. /**
  562. * Object plugin content
  563. * Contains details of an object to be used to generated content,
  564. * @package core
  565. * @access private
  566. */
  567. class object_plugin_content extends plugin_content {
  568. /** The objects which return content */
  569.  
  570. var $obj;
  571. // .....................................................................
  572. /**
  573. * Constructor
  574. * Create a new object plugin object.
  575. * @param object $obj Object to use for content
  576. */
  577. function object_plugin_content($obj) {
  578. if (method_exists($obj, "html")) {
  579. $this->obj = $obj;
  580. }
  581. } // object_plugin_content
  582. // .....................................................................
  583. /**
  584. * Generate plugin content
  585. * Call object render() method. Return the result.
  586. * @return string Plugin content.
  587. */
  588. function render() {
  589. if (isset($this->obj)) {
  590. $this->content = $this->obj->render();
  591. }
  592. return $this->content;
  593. } //render
  594.  
  595. } // object_plugin_content class
  596. // ----------------------------------------------------------------------
  597.  
  598. ?>

Documentation generated by phpDocumentor 1.3.0RC3