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 determined
  293. * from the content passed as the second paramter. Allowed data-types
  294. * for content: object (must inherit RenderableObject), a function
  295. * 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("pluginset: defining new plugin '$pluginid'", DBG_DEBUG);
  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 exist yet,
  309. * then we create it first. If it already exists, then we append the
  310. * new content to it.
  311. * @param string $pluginid ID of this plugin. Used to find plugin location
  312. * @param mixed $content The plugin content (literal, function, object...)
  313. */
  314. function addto($pluginid, $content) {
  315. $pluginid = strtoupper($pluginid);
  316. if (!isset($this->plugins[$pluginid])) {
  317. $this->add_plugin($pluginid, $content);
  318. }
  319. else {
  320. $plugin = $this->plugins[$pluginid];
  321. $plugin->add_content($content);
  322. $this->plugins[$pluginid] = $plugin;
  323. }
  324. return $this;
  325. } // addto
  326. // .....................................................................
  327. /**
  328. * This method takes the given template, and renders the plugins on
  329. * it one by one. Each plugin is applied to the template, replacing
  330. * all occurences of the appropriate tag based on the pluginid. Then
  331. * finally the resulting string is returned.
  332. */
  333. function render($template="") {
  334. if ($template != "") {
  335. $plugged = $template;
  336. if (isset($this->plugins)) {
  337. foreach ($this->plugins as $id => $plugin) {
  338. if (is_object($plugin)) {
  339. $newstuff = $plugin->render();
  340. $tag = "<!--" . strtoupper($id) . "-->";
  341. str_replace($tag, $newstuff, $plugged);
  342. }
  343. }
  344. }
  345. }
  346. return $plugged;
  347. } //render
  348.  
  349. } // pluginset class
  350. // ----------------------------------------------------------------------
  351.  
  352. /**
  353. * Plugin class
  354. * A plugin is something which can be used by the system to render
  355. * content to be plugged into a webpage in any specified place.
  356. * The normal plugin just provides a receptacle for content, and
  357. * which will be plugged in when the webpage is built. You can
  358. * also specify a path of a file containing content, an object to
  359. * render() content, or a function to return content.
  360. * We can have multiple types of plugin:
  361. * - Standard: Literal content as provided
  362. * - Function: A function call which returns content
  363. * - Object: An object which renders content
  364. * - File: A file which contains content
  365. * @package core
  366. */
  367. class plugin extends page_section {
  368. // Public
  369. // Private
  370. /** ID or name of this plugin
  371. @access private */
  372. var $pluginid = "";
  373. /** Array of plugin content objects
  374. @access private */
  375. var $plugin_contents;
  376. // .....................................................................
  377. /**
  378. * Constructor
  379. * Create a new plugin object.
  380. * @param string $pluginid ID of this plugin. Used to find plugin location
  381. * @param string $content Content to put into this plugin location
  382. */
  383. function plugin($pluginid, $content="") {
  384. $this->page_section();
  385. $this->pluginid = strtoupper($pluginid);
  386. $this->add_content($content);
  387. } // plugin
  388. // .....................................................................
  389. /**
  390. * Allows adding of any type of content to the plugin. This could be
  391. * literal (string), a file path referencing a file full of content, or
  392. * and object supporting render(), or the name of a function which is in
  393. * scope. In the latter case, the function name is saved here, and will
  394. * only be executed later on when plugins are rendered prior to sending
  395. * the webpage. This allows 'late' content rendering.
  396. * @param mixed $content Content to plug in: string, path, object or func name
  397. */
  398. function add_content($content="") {
  399. if (is_object($content)) {
  400. // An object which returns content via render()..
  401. $this->plugin_contents[] = new object_plugin_content($content);
  402. }
  403. elseif (is_string($content)) {
  404. $pattern = "/^.+\(.*\)" . chr(36) . "/";
  405. if (preg_match($pattern, $content)) {
  406. // A function definition..
  407. $this->plugin_contents[] = new func_plugin_content($content);
  408. }
  409. elseif (realpath($content) && file_exists($content)) {
  410. // File content..
  411. $this->plugin_contents[] = new file_plugin_content($content);
  412. }
  413. else {
  414. // Standard string content..
  415. $this->plugin_contents[] = new plugin_content($content);
  416. }
  417. }
  418. } // add_content
  419. // .....................................................................
  420. /**
  421. * Returns the string which represents all of the content
  422. * types which have been stored in this plugin. Note that we do not
  423. * differentiate between HTML or WML etc. since the content from our
  424. * point of view is all generic at this stage. Hence we override the
  425. * render() method, and not html() and/or wml().
  426. * @return string Plugin content.
  427. */
  428. function render() {
  429. $s = "";
  430. if (isset($this->plugin_contents)) {
  431. foreach ($this->plugin_contents as $content) {
  432. $new_content = $content->render();
  433. // Now render any content block tags. This scans the
  434. // content string for BLOCKID tags and renders the block
  435. // content in their place if any are found..
  436. if (function_exists("render_layouts")) {
  437. $new_content = render_layouts($new_content);
  438. }
  439. $s .= $new_content;
  440. }
  441. }
  442. return $s;
  443. } // render
  444.  
  445. } // plugin class
  446. // ----------------------------------------------------------------------
  447.  
  448. /**
  449. * Plugin content.
  450. * Literal plugin content.
  451. * for a plugin.
  452. * @package core
  453. * @access private
  454. */
  455. class plugin_content {
  456. /** The plugin content */
  457.  
  458. var $content;
  459. /** Whether the content is valid */
  460.  
  461. var $valid = false;
  462. /**
  463. * Constructor. Create a new literal plugin object.
  464. * @param string $content Literal content to be plugged in
  465. */
  466. function plugin_content($content="") {
  467. $this->content = $content;
  468. $this->valid = true;
  469. } // plugin_content
  470. // .....................................................................
  471. /**
  472. * Generate plugin content
  473. * Return content.
  474. * @return string Plugin content.
  475. */
  476. function render() {
  477. return $this->content;
  478. } // render
  479.  
  480. } // plugin_content class
  481. // ----------------------------------------------------------------------
  482.  
  483. /**
  484. * File plugin content
  485. * You can specify the name of a file which contains the content
  486. * for a plugin.
  487. * @package core
  488. * @access private
  489. */
  490. class file_plugin_content extends plugin_content {
  491. /** The path to the file */
  492.  
  493. var $path;
  494. /**
  495. * Constructor
  496. * Create a new file plugin content object.
  497. * @param string $path Path to a file containing content
  498. */
  499. function file_plugin_content($path="") {
  500. if ($path != "") {
  501. if (file_exists($path)) {
  502. $this->path = $path;
  503. $plugfile = new inputfile($path);
  504. if ($plugfile->opened) {
  505. $this->content = trim($plugfile->readall());
  506. $plugfile->closefile();
  507. $this->valid = true;
  508. }
  509. }
  510. }
  511. } // file_plugin_content
  512.  
  513. } // file_plugin_content class
  514. // ----------------------------------------------------------------------
  515.  
  516. /**
  517. * Function plugin content
  518. * Contains details of a function to be used to generated content,
  519. * @package core
  520. * @access private
  521. */
  522. class func_plugin_content extends plugin_content {
  523. /** The name of the function which returns content */
  524.  
  525. var $funcname = "";
  526. /** The arguments for the function */
  527.  
  528. var $funcargs;
  529. // .....................................................................
  530. /**
  531. * Constructor
  532. * Create a new function plugin object.
  533. * @param string $funcdef Definition of the function to call for content
  534. */
  535. function func_plugin_content($funcdef) {
  536. $pattern = "/^(.+)\((.*)\)" . chr(36) . "/";
  537. if (preg_match($pattern, $funcdef, $matches)) {
  538. $this->funcname = $matches[1];
  539. $argstr = $matches[2];
  540. $argstr = str_replace("\"", "", $argstr);
  541. $argstr = str_replace("'", "", $argstr);
  542. $this->funcargs = explode(",", $argstr);
  543. $this->valid = true;
  544. }
  545. } // func_plugin_content
  546. // .....................................................................
  547. /**
  548. * Generate plugin content
  549. * Call the givenfunction which should return a string, containing
  550. * the content.
  551. * @return string Plugin content.
  552. */
  553. function render() {
  554. if (isset($this->funcname)) {
  555. if (function_exists($this->funcname)) {
  556. $content = call_user_func_array($this->funcname, $this->funcargs);
  557. if (is_string($content) && $content != "") {
  558. $this->content = $content;
  559. }
  560. }
  561. }
  562. return $this->content;
  563. } //render
  564.  
  565. } // func_plugin_content class
  566. // ----------------------------------------------------------------------
  567.  
  568. /**
  569. * Object plugin content
  570. * Contains details of an object to be used to generated content,
  571. * @package core
  572. * @access private
  573. */
  574. class object_plugin_content extends plugin_content {
  575. /** The objects which return content */
  576.  
  577. var $obj;
  578. // .....................................................................
  579. /**
  580. * Constructor
  581. * Create a new object plugin object.
  582. * @param object $obj Object to use for content
  583. */
  584. function object_plugin_content($obj) {
  585. if (method_exists($obj, "html")
  586. || method_exists($obj, "wml")
  587. || method_exists($obj, "wmlup")
  588. ) {
  589. $this->obj = $obj;
  590. $this->valid = true;
  591. }
  592. } // object_plugin_content
  593. // .....................................................................
  594. /**
  595. * Generate plugin content
  596. * Call object render() method. Return the result.
  597. * @return string Plugin content.
  598. */
  599. function render() {
  600. if (isset($this->obj)) {
  601. $this->content = $this->obj->render();
  602. }
  603. return $this->content;
  604. } //render
  605.  
  606. } // object_plugin_content class
  607. // ----------------------------------------------------------------------
  608.  
  609. /**
  610. * Cm Layout plugin content
  611. * Contains details of a Content-Managed Layout block which is to
  612. * be generated and plugged in. The ID of the layout is provided.
  613. * @package core
  614. * @access private
  615. */
  616. class cm_plugin_content extends plugin_content {
  617. /** The text identifier of the CM layout
  618. which returns content */
  619. var $layoutid;
  620. // .....................................................................
  621. /**
  622. * Constructor
  623. * Create a new CM layout plugin object.
  624. * @param string $layoutid Unique string naming/identifying the layout.
  625. */
  626. function cm_plugin_content($layoutid="") {
  627. if ($layoutid != "") {
  628. $this->layoutid = $layoutid;
  629. $this->valid = true;
  630. }
  631. } // cm_plugin_content
  632. // .....................................................................
  633. /**
  634. * Generate CM Layout content. All that is required here is the
  635. * specific format required to be plugged into the webpage.
  636. * @return string Plugin content.
  637. */
  638. function render() {
  639. if ($this->valid) {
  640. $this->content = "\"<!--LAYOUTID=\\\"" . $this->layoutid . "\\\"-->\"";
  641. }
  642. return $this->content;
  643. } //render
  644.  
  645. } // cm_plugin_content class
  646. // ----------------------------------------------------------------------
  647.  
  648. ?>

Documentation generated by phpDocumentor 1.3.0RC3